你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure 时序见解 Gen1 参考数据 API

项目
07/19/2023

注意

这是一篇 Gen1 文章。

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

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

提示

若要创建引用数据集，请参阅如何创建引用数据集。

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

API 概述

参考数据管理 API 是批处理 API。

重要

针对此 API 的所有操作都是 HTTP POST 操作。
每个操作都接受 JSON 对象作为请求有效负载。
HTTP 请求 JSON 对象定义一个属性名称，该名称指定要由 API 执行的操作。

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

把
Patch
删除多个属性
删除
Get

重要

属性值是引用数据项的数组，必须对其应用操作。
每个项都单独处理，一个项的错误不会阻止其他项成功写入。例如，如果请求包含 100 个项，而一个项有错误，则会写入 99 个项目，一个项被拒绝。
引用数据项使用其完全枚举的关键属性进行查询。

注意

以下所有 JSON 正文示例都假定引用数据集具有名称 deviceId 和类型 为 String 的单个属性键。

放置引用数据项

将整个引用数据项$.put[i]插入或替换 (数组中^第 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 个项目，一个项被拒绝。

项错误代码

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

InvalidInput：找不到键。：指示在引用数据集中找不到查询的项。

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

InvalidInput：有效负载键不应包含任何非键属性。：指示 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 类型的名称和contosokeyId，并具有以下结构：

deviceId	color	maxSpeed	floor
Fan1	Red	5
Fan2	White		2

当事件中心消息中的两个事件由 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 引用数据相关的其他限制：

限制名称	限制值	受影响的 SKU	说明
键属性计数	3	S1、S2	每个引用数据集;仅限 Azure 资源管理器和 Azure 门户
键属性大小	1 KB	S1、S2	每个引用数据集
引用数据项计数	2，000/20，000 (S1/S2)	S1、S2	单位;例如，4 个单位 S1 SKU = 8，000 个项目 (4 x 2，000)
最大并发事务数	2/10 (S1/S2)	S1、S2
最大引用数据事务数	120/600 (S1/S2)	S1、S2	每小时
最大引用数据项计数	1,000	S1、S2	每事务
最大引用数据项大小	8，192 KB	S1、S2	每事务

另请参阅

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

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

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

菲德勒此免费的 Web 调试代理可以截获 REST 请求，因此你可以诊断 HTTP 请求和响应消息。
JWT.io。可以使用此工具在持有者令牌中快速转储声明，然后验证其内容。
Postman。这是一个免费的 HTTP 请求和响应测试工具，用于调试 REST API。

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

通过

Azure 时序见解 Gen1 参考数据 API

API 概述

放置引用数据项

修补引用数据项

删除引用数据项中的属性

删除引用数据项

获取引用数据项

验证和错误处理

项错误代码

引用数据联接示例

联接规则和语义

当前限制

另请参阅

其他资源