了解對應項模型以及如何在 Azure Digital Twins 中定義它們

發行項
02/06/2024

Azure Digital Twins 的主要特性是能夠定義自己的詞彙，並以您企業自我定義的詞彙建置對應項圖形。這項功能是透過使用者提供的模型來提供。您可以將模型視為您世界描述中的名詞。 Azure Digital Twins 模型會以 JSON-LD 為基礎的 數字對應項定義語言（DTDL） 來表示。

模型類似於 面向物件程式設計語言中的類別 ，在實際工作環境中定義特定概念的數據圖形。模型具有名稱（例如 Room 或 TemperatureSensor），並包含屬性、元件和關聯性等元素，可描述您環境中這類實體的功能。稍後，您將使用這些模型來建立數字對應項，代表符合此類型描述的特定實體。

模型的數字對應項定義語言（DTDL）

Azure Digital Twins 的模型是使用 Digital Twins 定義語言（DTDL）來定義。

您可以在 GitHub： DTDL 第 3 版語言描述中檢視 DTDL v3 的完整語言描述。此頁面包含 DTDL 參考詳細數據和範例，可協助您開始撰寫自己的 DTDL 模型。

DTDL 是以 JSON-LD 為基礎，而且與程式設計語言無關。 DTDL 不專屬於 Azure Digital Twins。它也可用來代表其他IoT服務中的裝置數據，例如 IoT 隨插即用。

本文的其餘部分摘要說明如何在 Azure Digital Twins 中使用語言。

支援的 DTDL 版本

Azure Digital Twins 支援 DTDL 第 2 版和 3 版（分別在文件中縮短為 v2 和 v3）。 V3 是建議選擇根據 Azure Digital Twins 中的擴充功能進行模型化，包括：

DTMI 版本放寬
屬性的陣列支援
增加模型繼承的限制
功能延伸模組
- 使用語意類型裝飾自訂介面架構的能力（隨附於 QuantitativeTypes 擴充功能）

在文件中討論這些功能時，它們會伴隨一則附註，指出它們只能在 DTDL v3 中使用。如需 DTDL v2 與 v3 之間差異的完整清單，請參閱 DTDL v3 語言描述：版本 2 的變更。

Azure Digital Twins 也支援在同一個實例內混合使用 v2 和 v3 模型。同時使用這兩個版本的模型時，請記住下列限制：

v2 介面無法擴充 v3 介面，或具有 v3 介面作為架構的元件。
相反地，v3 介面可以擴充 v2 介面，而 v3 介面可以有具有 v2 介面作為架構的元件。
關聯性可以指向任一方向，從 v2 模型來源到 v3 模型目標，反之亦然，從 v3 模型來源到 v2 模型目標。

您也可以將現有的 v2 模型移轉至 v3。如需如何執行這項操作的指示，請參閱將 v2 模型轉換為 v3。

注意

目前，Azure Digital Twins Explorer 完全支援 DTDL v2 模型，並支援 DTDL v3 模型的有限功能。在 Azure Digital Twins Explorer 中，DTDL v3 模型可以在 [模型] 面板中檢視，並使用 DTDL v3 模型建立的對應項可以檢視和編輯（包括具有數位屬性的模型）。不過，DTDL v3 模型不會顯示在 [模型圖形] 面板中，而且 無法使用 Azure Digital Twins Explorer 匯入 它們。若要將 DTDL v3 模型匯入您的實例，請使用另一個開發人員介面，例如 API 和 SDK 或 Azure CLI。

模型概觀

對應項類型模型可以在任何文字編輯器中撰寫。 DTDL 語言遵循 JSON 語法，因此您應該使用擴充 功能來儲存模型.json。使用 JSON 副檔名可讓許多程式設計文字編輯器為您的 DTDL 文件提供基本的語法檢查和醒目提示。另外還有適用於 Visual Studio Code 的 DTDL 擴充功能。

以下是模型介面內的欄位：

欄位	描述
`@id`	模型的數字對應項模型識別碼（DTMI）格式`dtmi:<domain>:<unique-model-identifier>;<model-version-number>`為。在 DTDL v3 中，可以省略版本號碼，或結構化為兩部分版本`<major>.<minor>`號碼。
`@type`	識別所描述的資訊類型。對於介面，類型為 `Interface`。
`@context`	設定 JSON 檔的內容。模型應該用於 `dtmi:dtdl:context;2` DTDL v2 或 `dtmi:dtdl:context;3` DTDL v3。 DTDL v3 模型也可以在此欄位中命名其他功能延伸模組。
`displayName`	[選擇性]可讓您選擇為模型定義易記名稱。如果您未使用此欄位，模型將會使用其完整的 DTMI 值。
`contents`	所有其餘的介面資料都會放在此處，做為屬性定義的陣列。每個屬性都必須提供 `@type` （`Property`、 `Relationship`或 `Component`）來識別其描述的介面資訊排序，然後提供一組定義實際屬性的屬性。下一節將詳細說明模型屬性。

以下是基本 DTDL 模型的範例。此模型描述 Home，其中包含標識碼的一個屬性。 Home 模型也會定義與 Floor 模型的關聯性，可用來指出家用對應項已連線到特定 Floor 對應項。

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

模型屬性

模型的主要資訊是由其屬性所提供，這些屬性定義於模型介面的區段內 contents 。

以下是 Azure Digital Twins 中支援的 DTDL 中可用的屬性。用於 Azure Digital Twins 的 DTDL 模型介面可能包含下列每個欄位的零、一或多個：

屬性 - 屬性是代表實體狀態的數據欄位（例如許多面向物件程式設計語言中的屬性）。屬性具有支援儲存體，而且可以隨時進行讀取。如需詳細資訊，請參閱下方的屬性。
關聯性 - 關聯性可讓您代表數字對應項如何與其他數字對應項相關。關聯性可以代表不同的語意意義，例如 contains （“floor contains room”）， cools （“hvac cools room”）， isBilledTo （“壓縮機計費給使用者”），等等。關聯性可讓解決方案提供相互關聯的實體圖表。關聯性也可以有自己的屬性。如需詳細資訊，請參閱下面的關聯性。
元件 - 如果您想要的話，元件可讓您將模型介面建置為其他介面的元件。元件的範例是用於定義手機模型的 front 相機介面（以及另一個元件介面 back 相機）。先定義 front 的介面相機就好像它是自己的模型，然後在定義電話時參考它。

使用元件來描述一些事項，而這些事項是您解決方案不可或缺的部分，但不需要個別的身分識別，也不需要在對應項圖表中獨立建立、刪除或重新排列。如果您想要實體在對應項圖形中具有獨立存在，請以不同模型的不同數字對應項來表示它們，並以關聯性連接。

提示

元件也可用於組織，以將模型介面內的相關屬性集合分組。在此情況下，您可以將每個元件視為介面內的命名空間或「folder」。

如需詳細資訊，請參閱下面的元件。

DTDL v3 語言描述也會定義命令和遙測，但兩者都未用於 Azure Digital Twins。不支援命令，雖然在模型定義中允許遙測，但在 Azure Digital Twins 模型化中沒有唯一的使用案例。您應該使用 DTDL 屬性來儲存對應項狀態資訊，而不是使用 DTDL 遙測。

注意

雖然不需要在 DTDL 模型中定義遙測欄位來儲存傳入的裝置數據，但 Azure Digital Twins 可以使用 SendTelemetry API 發出事件作為遙測。這會觸發事件處理程式可接收的數字對應項遙測訊息事件，以在其他對應項上採取動作，或觸發下游服務。

屬性

本節將詳細說明 DTDL 模型中的屬性 。

如需可能顯示為屬性一部分之字段的完整資訊，請參閱 DTDL v3 語言描述中的屬性。

注意

writable Azure Digital Twins 目前不支援屬性的 DTDL 屬性。它可以新增至模型，但 Azure Digital Twins 不會強制執行它。如需詳細資訊，請參閱服務特定的 DTDL 附注。

結構描述

根據 DTDL，屬性屬性的架構可以是標準基本類型、、、和 boolean，以及其他類型，例如 dateTime 和。 stringdoubleintegerduration

除了基本類型之外，屬性欄位也可以有下列複雜類型：

Object
Map
Enum
Array，僅限 DTDL v3。 Array DTDL v2 不支援屬性的類型。

它們也可以是語意類型，可讓您以單位標註值。在 DTDL v2 中，原生支援語意類型;在 DTDL v3 中，您可以將它們包含在功能延伸模組中。

基本屬性範例

以下是 DTDL 模型上屬性的基本範例。此範例顯示 Home 的 ID 屬性。

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

複雜物件類型範例

屬性可以是複雜類型，包括 Object 類型。

下列範例顯示另一個版本的 Home 模型，其位址有屬性。 address 是物件，其專屬欄位用於街道、城市、州和 zip。

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

DTDL v2 語意類型範例

語意類型是用來以單位表示值。 Azure Digital Twins 的屬性可以使用 DTDL 所支援的任何語意類型。

在 DTDL v2 中，原生支援語意類型。如需 DTDL v2 中語意類型的詳細資訊，請參閱 DTDL v2 語言描述中的語意類型。若要瞭解 DTDL v3 中的語意類型，請參閱 QuantitativeTypes DTDL v3 功能延伸模組。

下列範例顯示 DTDL v2 感測器模型，其語意類型屬性為濕度和溫度。

{
  "@id": "dtmi:com:adt:dtsample:v2sensor;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "displayName": "Sensor (v2 model)",
  "contents": [
    {
      "@type": ["Property", "Temperature"],
      "name": "Temperature",
      "schema": "double",
      "unit": "degreeFahrenheit"    
    },
    {
      "@type": ["Property", "Humidity"],
      "name": "Humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre" 
    }
  ]
}

重要

“Property” 必須是陣列的第 @type 一個專案，後面接著語意類型。否則，欄位可能無法顯示在 Azure Digital Twins Explorer 中。

關聯性

本節將詳細說明 DTDL 模型中的關聯 性。

如需可能顯示為關聯性一部分之字段的完整清單，請參閱 DTDL v3 語言描述中的關聯性。

注意

writableAzure Digital Twins 目前不支持關聯性的、 minMultiplicity和 maxMultiplicity DTDL 屬性。它們可以新增至模型，但 Azure Digital Twins 不會強制執行它們。如需詳細資訊，請參閱服務特定的 DTDL 附注。

基本關聯性範例

以下是 DTDL 模型上關聯性的基本範例。此範例顯示 Home 模型上的關聯性，可讓它連線到 Floor 模型。

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

注意

對於關聯性， @id 是選擇性欄位。 @id如果未提供，數字對應項介面處理器將會指派一個。

目標和非目標關聯性

關聯性可以使用或沒有 目標來定義。目標會指定關聯性可以到達的對應項類型。例如，您可能會包含一個目標，以指定 Home 模型只能與 Floor 對應項的對應項有 rel_has_floors 關聯性。

有時候，您可能想要定義沒有特定目標的關聯性，讓關聯性可以連線到許多不同類型的對應項。

以下是沒有目標的 DTDL 模型上關聯性的範例。在此範例中，關聯性是用來定義 Room 可能擁有的感測器，而關聯性可以連線到任何類型。

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": ["Property", "Humidity"],
      "name": "humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre"
    },
    {
      "@type": "Component",
      "name": "thermostat",
      "schema": "dtmi:com:adt:dtsample:thermostat;1"
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
      "name": "rel_has_sensors",
      "displayName": "Room has sensors"

關聯性的屬性

DTDL 也允許關聯性有自己的屬性。當您在 DTDL 模型中定義關聯性時，關聯性可以有自己的 properties 欄位，您可以在其中定義自訂屬性來描述關聯性特定狀態。

下列範例顯示另一個版本的 Home 模型，其中 rel_has_floors 關聯性具有屬性，代表上次佔用相關 Floor 的時間。

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

元件

本節將 詳細說明 DTDL 模型中的元件 。

如需可能顯示為元件一部分之欄位的完整清單，請參閱 DTDL v3 語言描述中的元件。

基本元件範例

以下是 DTDL 模型上元件的基本範例。此範例示範使用控溫器模型作為元件的會議室模型。

[
  {
    "@id": "dtmi:com:adt:dtsample:room;1",
    "@type": "Interface",
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "displayName": "Room",
    "extends": "dtmi:com:adt:dtsample:core;1",
    "contents": [
      {
        "@type": ["Property", "Humidity"],
        "name": "humidity",
        "schema": "double",
        "unit": "gramPerCubicMetre"
      },
      {
        "@type": "Component",
        "name": "thermostat",
        "schema": "dtmi:com:adt:dtsample:thermostat;1"
      },
      {
        "@type": "Relationship",
        "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
        "name": "rel_has_sensors",
        "displayName": "Room has sensors"
      }
    ]
  },
  {
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "@id": "dtmi:com:adt:dtsample:thermostat;1",
    "@type": "Interface",
    "displayName": "thermostat",
    "contents": [
      {
        "@type": ["Property", "Temperature"],
        "name": "temperature",
        "schema": "double",
        "unit": "degreeFahrenheit"
      }
    ]
  }
]

如果此解決方案中的其他模型也應該包含控溫器，他們可以參考與自己定義中的元件相同的控溫器模型，就像 Room 一樣。

重要

元件介面（上述範例中的控溫器）必須定義在與使用它的任何介面相同的數位中（上述範例中的 Room），才能找到元件參考。

模型繼承

有時候，您可能想要進一步特製化模型。例如，擁有一般模型 Room 和特殊化的變體 ConferenceRoom 和 Gym 可能很有用。為了表示特製化，DTDL 支持繼承。介面可以繼承自一或多個其他介面。您可以藉由將欄位新增 extends 至模型來執行此動作。

區 extends 段是介面名稱或介面名稱數位（允許擴充介面繼承自多個父模型）。單一父代可作為多個擴充介面的基底模型。

注意

在 DTDL v2 中，每個介面 extends 最多可以列出兩個介面。在 DTDL v3 中，的即時值 extends數目沒有限制。

在 DTDL v2 和 v3 中，階層的總深度限制 extends 為 10。

下列範例會將舊版 DTDL 範例中的 Home 模型重新想像為較大「核心」模型的子類型。父模型（Core）會先定義，然後使用來建 extends置子模型（Home）。

{
    "@id": "dtmi:com:adt:dtsample:core;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Core",
    "contents": [
        {
            "@type": "Property",
            "name": "id",
            "schema": "string"
        },
        {
            "@type": "Property",
            "name": "name",
            "schema": "string"
        }
    ]
}

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {

在此情況下，Core 會將標識碼和名稱提供給 Home。其他模型也可以擴充 Core 模型，以取得這些屬性。以下是擴充相同父介面的會議室模型：

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",

套用繼承之後，延伸介面會公開來自整個繼承鏈結的所有屬性。

擴充介面無法變更父介面的任何定義;它只能新增至它們。它也無法重新定義在其任何父介面中已定義的功能（即使功能定義為相同）。例如，如果父介面定義 double 屬性 mass，則擴充介面不能包含的 mass宣告，即使它也是 double。

DTDL v3 功能延伸模組

DTDL v3 可讓語言延伸模組定義其他中繼模型類別，讓您可用來撰寫更豐富的模型。本節描述 可用來將非核心功能新增至 DTDL v3 模型的功能擴充 類別。

每個功能延伸模組都是由其 內容規範來識別，這是唯一的數字對應項模型標識碼（DTMI）值。若要在模型中啟用功能延伸，請將延伸模組的內容規範新增至模型的 @context 欄位（以及的 dtmi:dtdl:context;3一般 DTDL 內容規範）。您可以將多個功能延伸模組新增至相同的模型。

以下是該 @context 欄位可能與功能延伸模組外觀的範例。下列摘錄來自使用QuantitativeTypes延伸模組和Annotation延伸模組的模型。

  "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1",
      "dtmi:dtdl:extension:annotation;1"
  ]

將功能延伸模組新增至模型之後，您就可以存取該延伸模組在模型中的 輔助類型 。您可以將附加類型新增至 @type DTDL 元素的欄位，以提供元素的額外功能。臨機類型可能會將其他屬性新增至專案。

例如，以下是使用註釋延伸模組之模型的摘錄。此延伸模組具有稱為 ValueAnnotation的附加類型，其會在下列範例中新增至屬性元素。將這個附加類型新增至屬性元素可讓元素具有額外的 annotates 欄位，用來指出這個元素所標註的另一個屬性。

{
  "@type": [ "Property", "ValueAnnotation" ],
  "name": "currentTempAccuracy",
  "annotates": "currentTemp",
  "schema": "double"
  },

本節的其餘部分將更詳細地說明註釋延伸模組和其他 DTDL v3 功能延伸模組。

註釋延伸模組

Annotation 延伸模組可用來將自定義元數據新增至 DTDL v3 模型中的屬性元素。內容規範為 dtmi:dtdl:extension:annotation;1。

此延伸模組包含 ValueAnnotation 附加類型，可新增至 DTDL 屬性專案。此 ValueAnnotation 類型會將一個字段新增至元素， annotates這可讓您為目前項目標註的另一個屬性命名。

如需此延伸模組的詳細資訊和範例，請參閱 DTDL v3 語言描述中的註釋延伸模組。

歷程記錄延伸

Historization 延伸是用來將 DTDL v3 模型中的屬性指定為應該歷程記錄的屬性（這表示應該記錄其值的歷史序列，以及值變更的時間）。內容規範為 dtmi:dtdl:extension:historization;1。

此延伸模組包含 Historized 附加類型，可新增為 DTDL 屬性元素的共型別，以指出服務應該保存元素的歷史值，並讓它們可供查詢和分析。臨 Historized 機類型不會將任何欄位新增至專案。

如需此延伸模組的詳細資訊和範例，請參閱 DTDL v3 語言描述中的 Historization 擴充功能。

覆寫延伸模組

覆 寫延伸模組 是用來以實例值覆寫 DTDL V3 模型中的屬性。它與註解延伸模組搭配使用，其內容規範為 dtmi:dtdl:extension:overriding;1。

此延伸模組包含Override附加類型，可新增至也與一起ValueAnnotation型別的 DTDL 屬性（從註釋延伸模組）。此 Override 類型會將一個字段新增至元素， overrides這可讓您將批注專案上的欄位命名為由目前元素的值覆寫。

如需此延伸模組的詳細資訊和範例，請參閱 DTDL v3 語言描述中的覆寫延伸模組。

QuantitativeTypes 擴充功能

QuantitativeTypes 擴充功能可用來啟用 DTDL v3 模型中的語意類型、單位類型和單位。內容規範為 dtmi:dtdl:extension:quantitativeTypes;1。

此延伸模組可讓您使用許多語意類型做為輔助類型，這些類型可以新增至 CommandRequest、Field、MapValue 或 DTDL v3 中的屬性。語意類型會將一個字段新增至專案， unit這個欄位會接受對應至語意類型的有效單位。

如需延伸模組的詳細資訊，包括範例和支援語意類型和單位的完整清單，請參閱 DTDL v3 語言描述中的 QuantitativeTypes 擴充功能。

服務特定的 DTDL 附注

並非使用 DTDL 的所有服務都會實作與 DTDL 完全相同的功能。 Azure Digital Twins 目前不支援某些 DTDL 功能，包括：

DTDL 命令
writable屬性或關聯性上的屬性。雖然此屬性可以根據 DTDL 規格來設定，但 Azure Digital Twins 不會使用此值。相反地，這些屬性一律會由具有 Azure Digital Twins 服務一般寫入許可權的外部用戶端視為可寫入。
關聯 minMultiplicity 性的和 maxMultiplicity 屬性。雖然這些屬性可以根據 DTDL 規格來設定，但 Azure Digital Twins 不會強制執行這些值。

若要讓 DTDL 模型與 Azure Digital Twins 相容，也必須符合下列需求：

模型中的所有最上層 DTDL 元素都必須是類型 Interface。此需求的原因是 Azure Digital Twins 模型 API 可以接收代表介面或介面陣列的 JSON 物件。因此，最上層不允許其他 DTDL 元素類型。
Azure Digital Twins 的 DTDL 不得定義任何命令。
Azure Digital Twins 只允許單一層級的元件巢狀，這表示做為元件使用的介面本身不能有任何元件。
不能在其他 DTDL 介面內內嵌定義介面；它們必須定義為具有自己的識別碼的個別最上層實體。然後，當另一個介面想要以元件形式或透過繼承將該介面納入時，可以參考其識別碼。

模型化工具和最佳做法

本節說明模型化的其他考慮和建議。

使用現有的業界標準待辦專案

內部學是一組模型，可全面描述特定領域，例如製造、建築結構、IoT 系統、智慧城市、能源電網、Web 內容等等。

如果您的解決方案適用於使用任何類型的模型標準的特定產業，請考慮從為業界設計的預先存在的模型集開始，而不是從頭開始設計模型。 Microsoft 已與領域專家合作，根據業界標準建立 DTDL 模型，以協助將重塑降到最低，並鼓勵跨產業解決方案的一致性和簡單性。您可以在什麼是本體學？中深入了解這些待辦專案，包括如何使用它們，以及現在有哪些待辦專案可供使用？

考慮查詢含意

在設計模型以反映您環境中的實體時，查看並考慮設計之查詢含意會很有用。您可能想要以避免圖形周游的大型結果集的方式來設計屬性。您也可以將單一查詢中需要回答的關聯性模型化為單一層級關聯性。

驗證模型

建立模型之後，建議您先脫機驗證模型，再將其上傳至 Azure Digital Twins 實例。

為了協助您驗證模型，NuGet： DTDLParser 上會提供 .NET 用戶端 DTDL 剖析連結庫。您可以直接在 C# 程式代碼中使用剖析器連結庫。您也可以檢視 GitHub 中 DTDLParserResolveSample 中剖析器範例的使用。

大量上傳和刪除模型

完成建立、擴充或選取模型之後，您必須將它們上傳至您的 Azure Digital Twins 實例，使其可用於您的解決方案。

您可以使用匯入作業 API API，在單一 API 呼叫中上傳許多模型。 API 可以同時接受實例中模型數目的 Azure Digital Twins 限制，並視需要自動重新排序模型以解析它們之間的相依性。如需使用此 API 的詳細指示和範例，請參閱模型的大容量導入指示。

「匯入作業 API」的替代方法是模型上傳程式範例，它會使用個別模型 API 一次上傳多個模型檔案。此範例也會實作自動重新排序來解析模型相依性。它目前僅適用於 DTDL 第 2 版。

如果您需要一次刪除 Azure Digital Twins 實例中的所有模型，您可以使用模型刪除器範例。這是包含遞歸邏輯的專案，可透過刪除程序處理模型相依性。它目前僅適用於 DTDL 第 2 版。

或者，如果您想要藉由刪除所有模型以及所有對應項和關聯性來清除實例中的數據，您可以使用刪除作業 API。

將模型可視化

將模型上傳至 Azure Digital Twins 實例之後，您可以使用 Azure Digital Twins Explorer 來檢視模型。總管包含實例中所有模型的清單，以及 說明它們彼此關聯方式的模型圖形 ，包括任何繼承和模型關聯性。

注意

以下是模型圖形看起來可能的樣子範例：

如需 Azure Digital Twins Explorer 中模型體驗的詳細資訊，請參閱探索模型和模型圖形。

下一步

瞭解如何根據業界標準本體建立模型：什麼是本體學？
深入瞭解使用 API 作業管理模型：管理 DTDL 模型
瞭解模型如何用來建立數字對應項：數字對應項和對應項圖表