Azure 时序见解 Gen1 参考数据 API

本文介绍用于管理引用数据集中的项的 Azure 时序见解 Gen1 引用数据管理 API。 它假定已在环境中创建了引用数据集。

参考数据包括不经常更改的制造商或位置数据。 参考数据用于将遥测数据置于上下文中，并用于比较遥测数据。

由于数据集是预先存在且固定的，因此设备发送的每个数据包都包含相同的信息。 因此，引用数据不会从设备发送，你可以使用引用数据管理 API 或 Azure 门户来管理数据。

API 概述

引用数据管理 API 是一个批处理 API。

有效的 JSON 请求作属性名称为：

• 放
• 修补
• 删除属性
• 删除
• 获取

放置参考数据项目

插入或替换整个引用数据项$.put[i]（数组中带有键 put 的^第 i 项）。 提交的单位是 $.put[i]. 作是幂等的。

• 端点和作：

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• 请求正文示例：

  {
    "put": [{
      "deviceId": "Fan1",
      "color": "Red",
      "maxSpeed": 5
    },
    {
      "deviceId": "Fan2",
      "color": "White",
      "floor": 2
    }]
  }
  

• 响应示例：

  {
    "put": [
      null,
      null
    ]
  }
  

修补程序参考数据项

更新并插入引用数据项 $.patch[i]的特定属性。

• 端点和作：

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• 请求正文示例：

  {
    "patch": [
      {
        "deviceId": "Fan1",
        "maxSpeed": 108
      },
      {
        "deviceId": "Fan2",
        "floor": 18
      }
    ]
  }
  

• 响应正文示例：

  {
    "patch": [
      null,
      null
    ]
  }
  

删除引用数据项中的属性

从参考数据项 $.deleteproperties[i]中删除指定的属性。

• 端点和作：

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• 请求正文示例：

  {
    "deleteProperties":[
      {
        "key":{
          "deviceId":"Fan2"
        },
        "properties":[
          "floor"
        ]
      }
    ]
  }
  

• 响应正文示例：

  {
    "deleteProperties": [
      null
    ]
  }
  

删除参考数据项

删除由每个 $.delete[i].

• 端点和作：

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• 请求正文示例：

  {
    "delete": [{
      "deviceId": "Fan1"
    }]
  }
  

• 响应正文示例：

  {
    "delete": [
      null
    ]
  }
  

获取参考数据项

获取由每个 $.get[i].

• 端点和作：

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• 请求正文示例：

  {
    "get": [{
      "deviceId": "Fan1"
    },
    {
      "deviceId": "Fan2"
    }]
  }
  

• 响应正文示例：

  {
    "get": [
      {
        "code": "InvalidInput",
        "message": "Key not found.",
        "target": null,
        "details": null,
        "innerError": null
      },
      {
        "id": "Fan2",
        "floor": 18
      }
    ]
  }
  

验证和错误处理

引用数据管理 API 单独处理每个项目，一个项目的错误不会阻止成功写入其他项目。 例如，如果您的请求有 100 个项目，其中一个项目有错误，则写入 99 个项目，拒绝 1 个项目。

物料错误代码

项目错误代码出现在具有 HTTP 状态代码 200 的成功 JSON 响应正文中。

• InvalidInput： Key not found.：表示在引用数据集中找不到查询的项。

  {
    "code": "InvalidInput",
    "message": "Key not found.",
    "target": null,
    "details": null,
    "innerError": null
  }
  

• InvalidInput： payload key 不应包含任何非键属性。：指示 JSON 请求正文查询项不应包含任何非键属性的属性（即引用集架构中指定的属性）。 可以在 Azure 门户中找到关键属性。

  {
    "code": "InvalidInput",
    "message": "Payload key should not contain any non-key property.",
    "target": null,
    "details": null,
    "innerError": null
  }
  

• InvalidInput： 有效负载项应包含所有键属性。：指示 JSON 请求正文查询项应包含所有键属性（即在引用集架构中指定的属性）。 可以在 Azure 门户中找到关键属性。

  {
    "code": "InvalidInput",
    "message": "Payload item should contain all key properties.",
    "target": null,
    "details": null,
    "innerError": null
  }
  

引用数据连接示例

考虑具有以下结构的事件中心消息：

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z"
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z"
  }
]

考虑使用类型为 String 的名称contoso和键 deviceId 设置的引用数据项，该数据项具有以下结构：

当事件中心消息中的两个事件由 Azure 时序见解 Gen1 入口引擎处理时，它们将与正确的引用数据项联接。 事件输出具有以下结构：

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"Red",
    "maxSpeed":5
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"White",
    "floor":2
  }
]

联接规则和语义

联接参考数据时，请遵守以下约束：

• 键名称比较区分大小写。
• 对于字符串属性，键值比较区分大小写。

对于具有多个引用数据集的环境，在联接期间将强制执行三个进一步的约束：

• 引用数据集中的每个项都可以指定自己的非键属性列表。
• 对于任意两个引用数据集 A 和 B，非键属性不得相交。
• 引用数据集仅直接连接到事件，从不连接到其他引用的数据集（然后连接到事件）。 要将引用数据项连接到事件，引用数据项中使用的所有键属性都必须存在于事件中。 此外，键属性不应来自通过其他引用数据项连接到事件的非键属性。

鉴于这些约束，联接引擎可以对给定事件按任意顺序应用联接。 不考虑层次结构和排序。

当前限制

每个 Azure 时序见解 Gen1 环境最多可以添加两个参考数据集。 下表列出了与 Azure 时序见解 Gen1 参考数据关联的其他限制：

另请参阅

有关应用程序注册和 Azure Active Directory 编程模型的详细信息，请参阅 面向开发人员的 Azure Active Directory。

若要了解请求和身份验证参数，请参阅 身份验证和授权。

帮助测试 HTTP 请求和响应的工具包括：

• 提琴手。 这个免费的 Web 调试代理可以拦截您的 REST 请求，因此您可以诊断 HTTP 请求和响应消息。
• JWT.io。 可以使用此工具快速转储持有令牌中的声明，然后验证其内容。
• 邮递员。 这是一个免费的 HTTP 请求和响应测试工具，用于调试 REST API。

通过查看 Gen1 文档，详细了解 Azure 时序见解 Gen1。