什麼是裝置範本？

發行項
05/30/2024

Azure IoT Central 中的裝置範本是藍圖，可定義連線至應用程式之裝置類型的特性與行為。例如，裝置範本會定義裝置傳送的遙測，讓 IoT Central 可以建立使用正確單位與資料類型的視覺效果。

解決方案產生器會將裝置範本新增至 IoT Central 應用程式。裝置開發人員會撰寫裝置程式碼，以實作裝置範本中定義的行為。若要深入了解裝置與 IoT Central 所交換的資料，請參閱遙測、屬性和命令承載。

裝置範本包含下列區段：

裝置模型。裝置範本的此部分會定義裝置與應用程式互動的方式。每個裝置模型都會有唯一識別碼。裝置開發人員會實作模型中所定義的行為。
- 根元件。每個裝置模型都有根元件。根元件的介面描述裝置模型特定的功能。
- 元件。 除了用於描述裝置功能的根元件之外，裝置模型也可能會包含元件。每個元件都有描述元件功能的介面。元件介面可能會在其他裝置模型中重複使用。例如，數個手機裝置模型可能會使用相同的相機介面。
- 繼承介面。裝置模型包含一或多個介面，可擴充根元件的功能。
檢視表。此部分的裝置範本可讓解決方案開發人員定義視覺效果，以檢視來自裝置的資料，以及用於管理及控制裝置的形式。檢視不會影響裝置開發人員撰寫可實作裝置模型的程式碼。

將裝置指派給裝置範本

若要讓裝置與 IoT Central 互動，必須將其指派給裝置範本。這項指派是使用四種方式之一來完成：

當您在 [裝置] 頁面上註冊裝置時，可以識別裝置應該使用的範本。
當您大量匯入裝置清單時，可以選擇清單上所有裝置都應該使用的裝置範本。
連線之後，您可以手動將未指派的裝置指派給裝置範本。
裝置第一次連線至您的應用程式時，您可以傳送模型識別碼，以將裝置自動指派給裝置範本。

自動指派

裝置連線時，IoT Central 可以自動將裝置指派給裝置範本。裝置應該會在連線時傳送模型識別碼。 IoT Central 會使用型號識別碼來識別該特定裝置型號的裝置範本。探索程序的運作方式如下：

如果已在 IoT Central 應用程式中發佈裝置範本，則會將裝置指派給裝置範本。
如果裝置範本尚未在IoT Central 應用程式中發佈，IoT Central會在公用裝置模型存放庫中尋找裝置模型。如果 IoT Central 找到型號，便會使用該型號來產生基本的裝置範本。
如果 IoT Central 在公開模型存放庫中找不到模型，則系統會將裝置標示為 [未指派]。操作員可以：
- 為裝置建立裝置範本，然後將未指派的裝置移轉到新的裝置範本。
- 根據裝置傳送的資料自動產生裝置範本。

下列螢幕擷取畫面顯示如何在 IoT Central 中檢視裝置範本的模型識別碼。在裝置範本中，選取元件，然後選取 [編輯身分識別]：

您可以在公用模型存放庫中檢視控溫器模型。模型識別碼定義看起來像這樣：

"@id": "dtmi:com:example:Thermostat;1"

使用下列 DPS 承載，以將裝置指派給裝置範本：

{
  "modelId":"dtmi:com:example:TemperatureController;2"
}

若要深入了解 DPS 承載，請參閱教學課程：建立用戶端應用程式並將其連線至 Azure IoT Central 應用程式中所使用的範例程式碼。

裝置型號

裝置模型會定義裝置如何與您的 IoT Central 應用程式互動。裝置開發人員必須確定裝置會實作裝置模型中所定義的行為，讓 IoT Central 可以監視及管理裝置。裝置模型是由一或多個「介面」所構成，而且每個介面都可以定義「遙測」類型、「裝置屬性」與「命令」集合。解決方案開發人員可以：

將定義完整裝置模型或個別介面的 JSON 檔案匯入到裝置範本中。
使用 IoT Central 中的 Web UI 來建立或編輯裝置模型。

注意

IoT Central 接受來自裝置的任何有效 JSON 承載，但僅當資料與裝置模型中的定義相符時，它才能使用資料進行視覺效果。您可匯出不符合定義的資料，請參閱使用 Blob 儲存體將 IoT 資料匯出至雲端目的地。

若要深入了解如何編輯裝置模型，請參閱編輯現有的裝置範本

解決方案開發人員也可以從包含完整裝置模型或個別介面的裝置範本來匯出 JSON 檔案。裝置開發人員可以使用此 JSON 文件來了解裝置應該如何與 IoT Central 應用程式通訊。

定義裝置模型的 JSON 檔案會使用數位對應項定義語言（DTDL） v2。 IoT Central 預期 JSON 檔案包含具有介面定義內嵌的裝置模型，而不是在個別的檔案中。在 IoT Central 中建立的模型已定義內容 dtmi:iotcentral:context;2，以指出該模型是在 IoT Central 中建立的：

"@context": [
  "dtmi:iotcentral:context;2",
  "dtmi:dtdl:context;2"
]

如要深入了解 DTDL 模型，請參閱 IoT 隨插即用模型化指南。

注意

IoT Central 定義了 DTDL v2 語言的一些延伸模組。若要深入了解，請參閱 IoT Central 延伸模組。

屬性

屬性預設為唯讀。唯讀屬性表示裝置會向您的 Azure IoT Central 應用程式報告屬性值更新。您的 IoT Central 應用程式無法設定唯讀屬性的值。

您也可以在介面上將屬性標示為可寫入。裝置可以從您的 IoT Central 應用程式接收可寫入屬性的更新，並向您的應用程式報告屬性值更新。

裝置不需要連線，即可設定屬性值。裝置下次連線至應用程式時，會傳送已更新的值。此行為同時適用於唯讀和可寫入屬性。

請不要使用屬性以從您的裝置傳送遙測。例如，temperatureSetting=80 這類唯讀屬性應該表示裝置溫度已設定為 80，而裝置正在嘗試達到或保持此溫度。

針對可寫入屬性，裝置應用程式會傳回所需狀態的狀態碼、版本和描述，以指出是否接收和套用屬性值。

雲端屬性

您也可以將雲端屬性新增至模型的根元件。雲端屬性可讓您指定要儲存在 IoT Central 應用程式中的任何裝置中繼資料。雲端屬性值會儲存在 IoT Central 應用程式中，且永遠不會與裝置同步處理。雲端屬性不會影響裝置開發人員撰寫可實作裝置模型的程式碼。

解決方案開發人員可以將雲端屬性新增至裝置檢視和表單，以及新增裝置屬性，以讓操作員管理連線至應用程式的裝置。解決方案開發人員也可以使用雲端屬性作為規則定義的一部分，讓操作員可以編輯閾值。

下列 DTDL 程式碼片段顯示了範例雲端屬性定義：

{
    "@id": "dtmi:azureiot:Thermostat:CustomerName",
    "@type": [
        "Property",
        "Cloud",
        "StringValue"
    ],
    "displayName": {
        "en": "Customer Name"
    },
    "name": "CustomerName",
    "schema": "string"
}

遙測

IoT Central 可讓您在裝置檢視和圖表中檢視遙測，並使用規則以在達到閾值時觸發動作。 IoT Central 會使用裝置模型中的資訊 (例如資料類型、單位和顯示名稱)，來判斷如何顯示遙測值。您也可以在應用程式和個人儀表板上顯示遙測值。

您可以使用 IoT Central 資料匯出功能，以將遙測串流至其他目的地 (例如儲存體或事件中樞)。

命令

命令預設必須在 30 秒內執行，而且命令到達時，必須連線裝置。如果裝置及時回應，或未連線裝置，則命令會失敗。

命令可以有要求參數，並傳回回應。

離線命令

您可以為裝置範本中的命令啟用 [離線時排入佇列] 選項，以在裝置目前處於離線狀態時選擇佇列命令。

離線命令是從解決方案到裝置的單向通知。離線命令可以有要求參數，但不會傳回回應。

注意

如果您將模型匯出為 DTDL，則離線命令會標示為 durable。

離線命令會使用 IoT 中樞雲端到裝置的訊息來將命令和承載傳送至裝置。

裝置收到的訊息承載是參數的原始值。名為 method-name 的自訂屬性會儲存 IoT Central 命令的名稱。下表顯示某些範例承載：

IoT Central 要求結構描述	裝置收到的範例承載
沒有要求參數	`@`
Double	`1.23`
String	`sample string`
Object	`{"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}`

下列裝置模型的程式碼片段顯示命令的定義。命令有物件參數，其中包含日期時間欄位和列舉：

{
  "@type": "Command",
  "displayName": {
    "en": "Generate Diagnostics"
  },
  "name": "GenerateDiagnostics",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "Payload"
    },
    "name": "Payload",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "StartTime"
          },
          "name": "StartTime",
          "schema": "dateTime"
        },
        {
          "displayName": {
            "en": "Bank"
          },
          "name": "Bank",
          "schema": {
            "@type": "Enum",
            "displayName": {
              "en": "Enum"
            },
            "enumValues": [
              {
                "displayName": {
                  "en": "Bank 1"
                },
                "enumValue": 1,
                "name": "Bank1"
              },
              {
                "displayName": {
                  "en": "Bank2"
                },
                "enumValue": 2,
                "name": "Bank2"
              },
              {
                "displayName": {
                  "en": "Bank3"
                },
                "enumValue": 3,
                "name": "Bank3"
              }
            ],
            "valueSchema": "integer"
          }
        }
      ]
    }
  }
}

如果您針對先前程式碼片段中的命令，在裝置範本 UI 中啟用 [離線時排入佇列] 選項，則裝置收到的訊息會包含下列屬性：

屬性名稱	範例值
`custom_properties`	`{'method-name': 'GenerateDiagnostics'}`
`data`	`{"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}`

檢視

解決方案開發人員會建立可讓操作員監視和管理已連線裝置的檢視。檢視是裝置範本的一部分，因此檢視會與特定裝置類型相關聯。檢視可以包括：

繪製遙測的圖表。
顯示唯讀裝置屬性的圖格。
讓操作員編輯可寫入裝置屬性的圖格。
讓操作員編輯雲端屬性的圖格。
讓操作員呼叫命令的圖格，包括預期有承載的命令。
顯示標籤、影像或 Markdown 文字的圖格。

下一步

既然您已了解裝置範本，建議的下一步是閱讀遙測、屬性和命令承載，以深入了解裝置與 IoT Central 所交換的資料。

共用方式為