IoT 中樞 REST (英文)
IoT 中樞 REST API 會以程式設計方式存取裝置、傳訊和作業服務,以及IoT 中樞中的資源提供者。 您可以從 Azure 中執行的 IoT 服務,或直接透過網際網路從可傳送 HTTPS 要求和接收 HTTPS 回應的任何應用程式,存取訊息服務。
服務
- 使用此 API 來管理IoT 中樞裝置對應項。 您可以擷取和更新裝置對應項屬性,並在裝置上叫用 直接方法 。
- 使用這些 API 來管理 IoT 中樞身分識別登錄中的裝置身分識別。
- 使用這些 API 來管理IoT 中樞中的作業。 您可以排程、取消或取得作業。
所有工作作業都符合 HTTP/1.1 通訊協定規格,而每個作業都會 x-ms-request-id
傳回可用來取得要求相關資訊的標頭。 您必須確保對這些資源提出的要求安全。 如需詳細資訊,請參閱IoT 中樞開發人員指南 –如何建立安全性權杖的詳細資訊安全性。
裝置傳訊
從裝置使用這些 API 將裝置到雲端訊息傳送至 IoT 中樞,並從 IoT 中樞接收雲端到裝置訊息。 所有工作作業都符合 HTTP/1.1 通訊協定規格。 您必須確保對這些資源提出的要求安全。 如需詳細資訊,請參閱IoT 中樞開發人員指南 - 安全性,以取得有關如何建立安全性權杖的特定資訊。
資源提供者
使用這些 API 來管理IoT 中樞資源的部署。 如需如何保護這些要求的詳細資訊,請參閱 Azure REST API 參考。
通用參數和標頭
下列資訊是與IoT 中樞相關的所有工作共同作業:
將 {api-version} 取代為 URI 中的 「2018-06-30」。
以 URI 中的訂閱識別碼取代 {subscription-id}。
將 {resourceGroupName} 取代為包含 (的資源組名,或將包含 IoT 中樞) 。
以 IoT 中樞的名稱取代 {IoTHubName}。
將 Content-Type 標頭設定為 application/json。
將 [授權標頭] 設定為 [使用IoT 中樞安全性權杖] 區段中所建立的 SAS權杖。
Etag 標頭會根據 RFC7232,在範圍設定為單一裝置身分識別的所有要求中傳回。
所有 PUT/PATCH 作業都需要指定下列標頭:
If-Match = [*|<etag from get>]
DELETE 作業可能包含下列標頭:
If-Match = [*|<etag from get>]
ETags 的行為如下所示:
PUT | 資源不存在 | 資源存在 |
---|---|---|
If-Match = 「」 / absent | 201 Created | 200 確定 |
If-Match = 「*」 | 412 先決條件失敗 | 200 確定 |
If-Match = 「xyz」 | 412 先決條件失敗 | 200 OK / 412 前置條件失敗 |
If-None-Match = 「*」 | 201 Created | 412 先決條件失敗 |
刪除 | 資源不存在 | 資源存在 |
---|---|---|
If-Match = 「」 / absent | 204 沒有內容 | 200 確定 |
If-Match = 「*」 | 204 沒有內容 | 200 確定 |
If-Match = 「xyz」 | 204 沒有內容 | 200 OK / 412 前置條件失敗 |
針對非同步呼叫:
PUT 會回應 201 使用 Azure-AsyncOperation 標頭建立的任何非同步作業。 所有同步 (更新) 作業都會傳回 200 OK。
DELETE 會傳回 202 接受位置與 Retry-After 標頭,以及存在之資源的 Azure-AsyncOperation 標頭。
位置標頭包含作業結果的 URL
Retry-After 標頭包含適當的重試間隔,以秒為單位
Azure-AsyncOperation 標頭包含非同步作業結果狀態的 URL
完成時,GET 至作業結果 URL 會產生與原始作業同步完成完全相同的結果