Azure 時間序列深入解析 Gen1 參考資料 API

發行項
08/05/2023

警告

這是 Gen1 文章。

本文說明用來管理參考資料集內專案的 Azure 時間序列深入解析 Gen1 參考資料管理 API。它假設已在環境中建立參考資料集。

參考資料報含不常變更的製造商或位置資料。參考資料可用來將遙測資料內容化，並用來比較遙測資料。

提示

若要建立參考資料集，請參閱如何建立參考資料集。

因為資料集是預先存在且固定的，所以裝置所傳送的每個資料封包都會包含相同的資訊。因此，不會從裝置傳送參考資料，而且您可以使用 Reference 資料管理 API 或 Azure 入口網站來管理資料。

API 概觀

參考資料管理 API 是批次 API。

重要

此 API 的所有作業都是 HTTP POST 作業。
每個作業都會接受 JSON 物件作為要求承載。
HTTP 要求 JSON 物件會定義單一屬性名稱，指定要由 API 執行的作業。

有效的 JSON 要求作業屬性名稱如下：

把
修補
刪除屬性
刪除
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： Payload 索引鍵不應包含任何非索引鍵屬性。：表示 JSON 要求本文查詢專案不應包含任何不是索引鍵屬性的屬性， (也就是參考集架構中所指定的屬性) 。您可以在Azure 入口網站中找到索引鍵屬性。
```
{
  "code": "InvalidInput",
  "message": "Payload key should not contain any non-key property.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput： Payload 專案應包含所有索引鍵屬性。：指出 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設定的參考資料項，且其結構如下：

deviceId	color	maxSpeed	floor
Fan1	紅色	5
Fan2	白色		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 Resource Manager 和 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 要求和回應的工具組括：

Fiddler。這個免費的 Web 偵錯 Proxy 可以攔截您的 REST 要求，以便診斷 HTTP 要求和回應訊息。
JWT.io。您可以使用此工具，快速傾印持有人權杖中的宣告，然後驗證其內容。
Postman。這是免費的 HTTP 要求和回應測試控管來偵錯 REST API。

檢閱Gen1 檔，以深入瞭解 Azure 時間序列深入解析 Gen1。

共用方式為

Azure 時間序列深入解析 Gen1 參考資料 API

API 概觀

放置參考資料項

修補參考資料項

刪除參考資料項中的屬性

刪除參考資料項

取得參考資料項

驗證和錯誤處理

專案錯誤碼

參考資料聯結範例

聯結規則和語意

目前的限制

另請參閱

其他資源