Query - Get Twins
查詢 IoT 中樞，以使用類似 SQL 的語言擷取裝置對應項的相關信息。 如需相關資訊，請參閱 https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-query-language 。 支援分頁。 這隻會傳回裝置對應項的相關信息。
POST https://fully-qualified-iothubname.azure-devices.net/devices/query?api-version=2021-04-12URI 參數
| 名稱 | 位於 | 必要 | 類型 | Description |
|---|---|---|---|---|
|
api-version
|
query | True |
string |
Api 的版本。 |
要求標頭
| 名稱 | 必要 | 類型 | Description |
|---|---|---|---|
| x-ms-continuation |
string |
用來取得下一頁結果的接續令牌。 |
|
| x-ms-max-item-count |
string |
每頁傳回的項目數上限。 如果無法接受指定的值，服務可能會使用不同的值。 |
要求本文
| 名稱 | 類型 | Description |
|---|---|---|
| query |
string |
查詢字串。 |
回應
| 名稱 | 類型 | Description |
|---|---|---|
| 200 OK |
Twin[] |
正常。 標題
|
定義
| 名稱 | Description |
|---|---|
|
Device |
裝置上啟用的功能狀態。 |
|
Query |
Json 查詢要求。 |
| Twin |
裝置或模組的狀態資訊。 當在 IoT 中樞 中建立或刪除對應的裝置/模組身分識別時，就會隱含地建立和刪除。 |
|
Twin |
對應項的所需和報告屬性。 物件的深度上限為 10。 |
| X509Thumbprint |
DeviceCapabilities
裝置上啟用的功能狀態。
| 名稱 | 類型 | Description |
|---|---|---|
| iotEdge |
boolean |
屬性，判斷裝置是否為邊緣裝置。 |
QuerySpecification
Json 查詢要求。
| 名稱 | 類型 | Description |
|---|---|---|
| query |
string |
查詢字串。 |
Twin
裝置或模組的狀態資訊。 當在 IoT 中樞 中建立或刪除對應的裝置/模組身分識別時，就會隱含地建立和刪除。
| 名稱 | 類型 | Description |
|---|---|---|
| authenticationType |
enum:
|
裝置所使用的驗證類型。 |
| capabilities |
裝置上啟用的功能狀態。 |
|
| cloudToDeviceMessageCount |
integer |
傳送的雲端到裝置訊息數目。 |
| connectionState |
enum:
|
裝置的連線狀態。 |
| deviceEtag |
string |
根據RFC7232，代表裝置 ETag 的字串。 |
| deviceId |
string |
IoT 中樞 身分識別登錄中裝置的唯一標識符。 這是區分大小寫的字串 (最多 128 個字元的 ASCII 7 位英數位元字元) ， 和下列特殊字元 {'-'、'：'、'.'、'+'、'%'、'_'、'#'、'*'、'？'、'！'、' ('、') '、'、'@'、'='、'@'、';'、'$'、'''}。 |
| deviceScope |
string |
裝置的範圍。 |
| etag |
string |
字串，表示裝置對應項的 ETag，根據RFC7232。 |
| lastActivityTime |
string |
裝置上次連線或接收或傳送訊息的日期和時間。 日期和時間是以 UTC ISO8601日期時間格式來分隔，例如 2015-01-28T16：24：48.789Z。 如果裝置使用 HTTP/1 通訊協定來執行傳訊作業，則不會更新此值。 |
| moduleId |
string |
IoT 中樞 身分識別登錄中模組的唯一標識符。 這是區分大小寫的字串 (最多 128 個字元的 ASCII 7 位英數位元字元) ， 和下列特殊字元 {'-'、'：'、'.'、'+'、'%'、'_'、'#'、'*'、'？'、'！'、' ('、') '、'、'@'、'='、'@'、';'、'$'、'''}。 |
| parentScopes |
string[] |
如果適用，則為上層邊緣裝置的範圍。 僅適用於邊緣裝置。 |
| properties |
對應項的所需和報告屬性。 |
|
| status |
enum:
|
裝置的啟用狀態。 如果停用，裝置就無法連線到服務。 |
| statusReason |
string |
裝置目前狀態的原因，如果有的話。 |
| statusUpdateTime |
string |
上次更新裝置狀態的日期和時間。 |
| tags |
object |
由解決方案後端讀取和寫入索引鍵/值組的集合。 裝置應用程式看不到它們。 這些金鑰的長度為 UTF-8 編碼、區分大小寫且長度上限為 1 KB。 允許的字元排除 UNICODE 控制字元 (區段 C0 和 C1) 、'.'、'$' 和空格。 這些值為 JSON 對象，長度上限為 4KB。 |
| version |
integer |
裝置對應項的版本，包括標籤和所需屬性 |
| x509Thumbprint |
裝置的 X509 指紋。 |
TwinProperties
對應項的所需和報告屬性。 物件的深度上限為 10。
| 名稱 | 類型 | Description |
|---|---|---|
| desired |
object |
所需屬性索引鍵/值組的集合。 密鑰的長度為 UTF-8 編碼、區分大小寫和最多 1 KB。 允許的字元排除 UNICODE 控制字元 (區段 C0 和 C1) 、'.'、'$' 和空格。 所需的 porperty 值是 JSON 對象，長度上限為 4KB。 |
| reported |
object |
報告屬性索引鍵/值組的集合。 密鑰的長度為 UTF-8 編碼、區分大小寫和最多 1 KB。 允許的字元排除 UNICODE 控制字元 (區段 C0 和 C1) 、'.'、'$' 和空格。 報告屬性值為 JSON 對象，長度上限為 4 KB。 |
X509Thumbprint
| 名稱 | 類型 | Description |
|---|---|---|
| primaryThumbprint |
string |
X509 用戶端憑證主要指紋。 |
| secondaryThumbprint |
string |
X509 用戶端憑證次要指紋。 |