什麼是裝置範本？

發行項
02/07/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擴充功能。

屬性

根據預設，屬性是唯讀的。唯讀屬性表示裝置會向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 秒內執行，而且當命令送達時，裝置必須連線。如果裝置有及時回應，或裝置未連線，則命令會失敗。

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

離線命令

如果裝置目前離線，您可以選擇佇列命令，方法是在裝置範本中啟用 命令的 [如果離線 ] 選項。

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

注意

離線命令會標示為 durable 將模型導出為 DTDL。

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

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

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

來自裝置模型的下列代碼段會顯示命令的定義。此指令具有具有 datetime 欄位和列舉的物件參數：

{
  "@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交換的數據。