了解數位對應項模型，以及如何在 Azure Digital Twins 中定義這些模型

發行項
05/15/2024

Azure Digital Twins 的主要特性是能夠定義自己的詞彙，並在您公司自行定義的詞彙中建置數位對應項圖表。這項功能是透過使用者提供的「模型」來提供。您可以在現實環境的描述中，將模型視為名詞。 Azure Digital Twins 模型會以 JSON-LD 為基礎的「數位對應項定義語言 (DTDL)」來表示。

模型類似於物件導向程式設計語言中的「類別」，可在實際工作環境中定義一個特定概念的資料圖形。模型有名稱 (例如 Room 或 TemperatureSensor)，而且包含屬性、元件和關聯性等元素，這些元素會描述您環境中這類實體的功能。稍後，您將使用這些模型來建立數位對應項，代表符合此類型描述的特定實體。

模型的數位對應項定義語言 (DTDL)

使用數位對應項定義語言 (DTDL) 定義 Azure Digital Twins 的模型。

您可以在 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 的擴充功能，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 文件的內容。模型應針對 DTDL v2 使用 `dtmi:dtdl:context;2`，或針對 DTDL v3 使用 `dtmi:dtdl:context;3`。 DTDL v3 模型也可以在此欄位中命名其他功能擴充。
`displayName`	[選擇性] 提供您選擇定義模型的自訂名稱。如果您未使用此欄位，模型將會使用其完整 DTMI 值。
`contents`	所有其餘的介面資料都會放在此處，做為屬性定義的陣列。每個屬性必須提供 `@type` (`Property`、`Relationship` 或 `Component`) 以定義其描述的介面資訊類型，以及定義實際屬性的屬性集合。下一節將詳細說明模型屬性。

以下是基本 DTDL 模型的範例。此模型描述 Home，其中包含識別碼的一個屬性。 Home 模型也會定義 Floor 模型的關聯性，可用來表示 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"
    }
  ]
}

模型屬性

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

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

屬性 - 屬性是可代表實體狀態的資料欄位 (例如許多物件導向程式設計語言的屬性)。屬性具有支援儲存體，而且可以隨時進行讀取。如需詳細資訊，請參閱下方的屬性。
關聯性 - 關聯性可讓您代表數位對應項如何與其他數位對應項相關。關聯性可以代表不同的語意意義，例如 contains (「樓層包含房間」)、cools (「hvac 冷卻室」)、isBilledTo (「向使用者收取壓縮程式費用」) 等。關聯性可讓解決方案提供相互關聯實體的圖表。關聯性也可以有自己的屬性。如需詳細資訊，請參閱下方關聯性。
元件 - 如果您想要的話，則元件可讓您將模型介面建置為其他介面的組件。元件的範例是 frontCamera 介面 (以及另一個元件介面 backCamera)，用於定義手機的模型。先定義 frontCamera 的介面，就像它是自己的模型一樣，然後在定義電話時予以參考。

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

提示

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

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

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

注意

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

屬性

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

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

注意

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

結構描述

根據 DTDL，屬性特性的結構描述可以是標準基本類型 (integer、double、string 和 boolean)，以及其他類型 (例如 dateTime 和 duration)。

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

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

也可以是語意類型，可讓您使用單位來標註值。 DTDL v2 原生支援語意類型；在 DTDL v3 中，您可以將其包含在功能擴充中。

基本屬性範例

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

{
  "@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 是物件，具有其專屬的街道、城市、州和郵遞區號欄位。

{
  "@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" 
    }
  ]
}

重要

「屬性」必須是 @type 陣列的第一個元素，接著是語意類型。否則，欄位可能不會顯示在 Azure Digital Twins Explorer 中。

關聯性

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

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

注意

Azure Digital Twins 目前不支援關聯性的 writable、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 模型上元件的基本範例。此範例示範使用控溫器模型作為元件的 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"
      }
    ]
  },
  {
    "@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」模型的子類型。先定義父模型 (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 模型以取得這些屬性。以下是擴充相同父介面的 Room 模型：

{
  "@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 擴充和註釋擴充的模型。

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

將功能擴充新增至模型之後，您就可以存取該擴充在模型中的「附加類型」。您可以將附加類型新增至 DTDL 元素的 @type 欄位，為元素提供額外功能。附加類型可能會將其他屬性新增至元素。

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

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

本節的其餘部分將更詳細地說明註釋擴充和其他 DTDL v3 功能擴充。

註釋擴充

註釋擴充可用來將自訂中繼資料新增至 DTDL v3 模型中的屬性元素。其內容指定名稱為 dtmi:dtdl:extension:annotation;1。

此擴充包含 ValueAnnotation 附加類型，可新增至 DTDL 屬性元素。 ValueAnnotation 類型會將一個欄位新增至元素 (annotates)，這可讓您為目前元素標註的另一個屬性命名。

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

歷史化擴充

歷史化擴充可用來將 DTDL v3 模型中的屬性指定為應列入歷程記錄的屬性 (這表示應該記錄其值的歷史序列，以及值變更的時間)。其內容指定名稱為 dtmi:dtdl:extension:historization;1。

此擴充包含 Historized 附加類型，可新增為 DTDL 屬性元素的 co-type，以指出服務應該保存元素的歷史值，讓這些值可供查詢和分析。 Historized 附加類型不會將任何欄位新增至元素。

如需此擴充的詳細資訊和範例，請參閱 DTDL v3 語言描述中的歷史化擴充。

覆寫擴充

覆寫擴充可用來將 DTDL V3 模型中的屬性覆寫為執行個體值。其會與註釋擴充搭配使用，內容指定名稱為 dtmi:dtdl:extension:overriding;1。

此擴充包含 Override 附加類型，可新增至「也」是 ValueAnnotation (來自註釋擴充) co-type 的 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 介面內內嵌定義介面；它們必須定義為具有自己的識別碼的個別最上層實體。然後，當另一個介面想要以元件形式或透過繼承將該介面納入時，可以參考其識別碼。

模型化工具和最佳作法

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

使用現有的產業標準本體

本體 (Ontology) 是一組完整描述特定領域的模型，例如製造業、建築物結構、IoT 系統、智慧城市、能源網路、Web 內容等等。

如果您的解決方案適用於使用任何建模標準類型的特定產業，請考慮從為您的產業設計的一組預先存在的模型開始，而不是從頭開始設計您的模型。 Microsoft 已與網域專家合作，根據業界標準建立 DTDL 模型本體，希望能最大程度地減少重新建立的必要性，並鼓勵產業解決方案越趨一致性和簡單。您可以透過什麼是本體？深入了解這些本體，包括使用方式，以及現在可以使用哪些本體。

考量查詢隱含式

設計模型以反映您環境中的實體，並可讓您事先查看並考量您設計的查詢隱含式。您可能會想以能避免圖形周遊出現大型結果集的方式來設計屬性。您也可能會想要建立關聯性模型，且需要在單一查詢中回答該模型，如同單一層級關聯性。

驗證模型

建立模型之後，建議您先離線驗證模型，再將模型上傳至 Azure Digital Twins 執行個體。

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

大量上傳和刪除模型

完成建立、延伸或選取模型之後，您需要將模組上傳至 Azure Digital Twins 執行個體，才能用於您的解決方案。

您可以使用匯入作業 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 模型
了解如何使用模型建立數位對應項：數位對應項和對應項圖表

共用方式為