管理 Azure Digital Twins 模型

本文描述如何管理 Azure Digital Twins 執行個體中的模型。 管理作業包括模型的上傳、驗證、擷取和刪除。

必要條件

若要使用本文中的 Azure Digital Twins，您必須要有 Azure Digital Twins 執行個體，以及必要的使用權限。 如果您已經設定好 Azure Digital Twins 執行個體，您可以直接使用該執行個體，並跳至下一節。 否則，請依照設定執行個體和驗證中的指示進行。 指示中包含的資訊可協助您確認已成功完成每個步驟。

設定執行個體之後，請記下執行個體的主機名稱。 您可以在 Azure 入口網站中找到主機名稱。

開發人員介面

本文重點摘要如何使用 .NET (C#) SDK 來完成不同的管理作業。 您也可以使用 Azure Digital Twins API 和 SDK 中所述的其他語言 SDK 來製作這些相同的管理呼叫。

其他可用來完成這些作業的開發人員介面包括：

• Azure Digital Twins Explorer
• REST API 呼叫
• Azure CLI 命令

注意

目前，Azure Digital Twins Explorer 完全支援 DTDL v2 模型，並支援 DTDL v3 模型的有限功能。

您可以在 [模型] 面板中檢視 DTDL v3 模型，也可以檢視和編輯使用 DTDL v3 模型建立的對應項 (包括具有陣列屬性的對應項)。 不過，DTDL v3 模型不會顯示在 [模型圖表] 面板中，而且無法使用 Azure Digital Twins Explorer 匯入這些模型。 若要將 DTDL v3 模型匯入執行個體，請使用另一個開發人員介面，例如 API 和 SDK 或 Azure CLI。

視覺效果

Azure Digital Twins Explorer 是一種視覺工具，可探索您 Azure Digital Twins 圖表中的資料。 您可以使用總管來檢視、查詢及編輯模型、對應項和關聯性。

如需閱讀 Azure Digital Twins Explorer 工具的相關資訊，請參閱 Azure Digital Twins Explorer。 如需如何使用其功能的詳細步驟，請參閱使用 Azure Digital Twins Explorer。

以下是視覺效果的外觀：

建立模型

您可以從頭開始建立自己的模型，或使用適用於您產業的現有本體。

撰寫模型

Azure Digital Twins 的模型是以 DTDL 撰寫，並儲存為 JSON 檔案。 另外還有可供 Visual Studio Code 使用的 DTDL 延伸模組，其提供語法驗證和其他功能，讓您更輕鬆地撰寫 DTDL 文件。

請考慮醫院想要以數位方式代表其房間的範例。 每間房間都包含用於監視洗手的智慧給皂機，以及用於監視通過房間之流量的感應器。

解決方案的第一個步驟是建立模型來代表醫院的各個層面。 此案例中的病房可能會描述如下：

{
    "@id": "dtmi:com:contoso:PatientRoom;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Patient Room",
    "contents": [
      {
        "@type": "Property",
        "name": "visitorCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashPercentage",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "hasDevices"
      }
    ]
  }

注意

這是已定義並儲存模型的 JSON 檔案範例本文，可作為用戶端專案的一部分上傳。 另一方面，REST API 呼叫會採用與上面類似的模型定義陣列 (其對應至 .NET SDK 中的 IEnumerable<string>)。 因此，若要直接在 REST API 中使用此模型，請使用括弧將其括住。

此模型會定義病房的名稱和唯一識別碼，以及代表訪客計數和洗手狀態的屬性。 這些計數器將會從動作感應器和智慧給皂機進行更新，並一起用來計算 handwash percentage 屬性。 此模型也會定義關聯性 hasDevices，以用來根據此房間模型將任何數位對應項連線至實際裝置。

注意

Azure Digital Twins 目前不支援某些 DTDL 功能，包括屬性和關聯性的 writable 屬性，以及關聯性的 minMultiplicitymaxMultiplicity 屬性。 如需詳細資訊，請參閱服務特定 DTDL 備註。

遵循此方法，您可以定義醫院病房、區域或醫院本身的模型。

如果您的目標是建置描述您的產業領域的完整模型集，請考慮是否存在可用於簡化模型製作的現有產業本體。 下一節會更詳細地說明產業的本體。

使用現有的產業標準本體

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

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

驗證語法

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

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

上傳模型

建立模型之後，您可以將其上傳至 Azure Digital Twins 執行個體。

當您準備好上傳模型時，可以針對 .NET SDK 使用下列程式碼片段：

// 'client' is an instance of DigitalTwinsClient
// Read model file into string (not part of SDK)
// fileName is the name of the JSON model file
string dtdl = File.ReadAllText(fileName);
await client.CreateModelsAsync(new[] { dtdl });

上傳時，服務會驗證模型檔案。

您通常需要將多個模型上傳到該服務。 您可以透過數種方式在單一交易中同時上傳許多模型。 為了協助您選擇策略，請在繼續本節其餘部分時考慮模型集的大小。

上傳小型模型集

針對較小的模型集，您可以使用個別的 API 呼叫一次上傳多個模型。 您可以在 Azure Digital Twins 限制中檢查單一 API 呼叫中可以上傳的模型數的目前限制。

如果您要使用 SDK，則可以使用 CreateModels 方法來上傳多個模型檔案，如下所示：

var dtdlFiles = Directory.EnumerateFiles(sourceDirectory, "*.json");

var dtdlModels = new List<string>();
foreach (string fileName in dtdlFiles)
{
    // Read model file into string (not part of SDK)
    string dtdl = File.ReadAllText(fileName);
    dtdlModels.Add(dtdl);
}
await client.CreateModelsAsync(dtdlModels);

如果您要使用 REST API 或 Azure CLI，則可以將多個模型定義放在單一 JSON 檔案中以一起上傳，來上傳多個模型。 在此情況下，模型應該放在檔案內的 JSON 陣列中，如下列範例所示：

[
    {
      "@id": "dtmi:com:contoso:Planet;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    },
    {
      "@id": "dtmi:com:contoso:Moon;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    }
]

使用匯入作業 API 上傳大型模型集

針對大型模型集，您可以使用匯入作業 API，在單一 API 呼叫中一次上傳許多模型。 此 API 可以同時接受最多執行個體中模型數的 Azure Digital Twins 限制，如果需要解決模型之間的相依性問題，它會自動重新排序模型。 此方法需要使用 Azure Blob 儲存體，以及 Azure Digital Twins 執行個體中模型和大量作業的寫入權限。

提示

匯入作業 API 也允許在相同的呼叫中匯入對應項和關聯性，以一次建立圖表的所有部分。 如需此程序的詳細資訊，請參閱使用匯入作業 API 大量上傳模型、對應項和關聯性。

若要大量匯入模型，您必須將模型的結構 (以及大量匯入作業中所包含的任何其他資源) 建置為 NDJSON 檔案。 Models 區段緊接在 Header 區段之後，使其成為檔案中的第一個圖形資料區段。 您可以在匯入作業 API 簡介中檢視範例匯入檔案和範例專案，以建立這些檔案。

接下來，檔案必須上傳至 Azure Blob 儲存體中的附加 Blob。 如需如何建立 Azure 儲存體容器的指示，請參閱建立容器。 然後，使用您慣用的上傳方法來上傳檔案 (一些選項如 AzCopy 命令、Azure CLI 或 Azure 入口網站)。

將 NDJSON 文件案上傳至容器之後，請在 Blob 容器內取得其 URL。 您稍後會在大量匯入 API 呼叫的本文中使用此值。

以下螢幕擷取畫面顯示 Azure 入口網站中 Blob 檔案的 URL 值：

然後，您可以在匯入作業 API 呼叫中使用該檔案。 您將提供輸入檔的 Blob 儲存體 URL，以及新的 Blob 儲存體 URL，以指示您希望在服務建立輸出記錄時其儲存的位置。

擷取模型

您可以列出並擷取 Azure Digital Twins 執行個體上所儲存的模型。

您的選項包括：

• 擷取單一模型
• 擷取所有模型
• 擷取模型的中繼資料和相依性

以下是一些範例呼叫：

// 'client' is a valid DigitalTwinsClient object

// Get a single model, metadata and data
Response<DigitalTwinsModelData> md1 = await client.GetModelAsync("<model-Id>");
DigitalTwinsModelData model1 = md1.Value;

// Get a list of the metadata of all available models; print their IDs
AsyncPageable<DigitalTwinsModelData> md2 = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in md2)
{
    Console.WriteLine($"Type ID: {md.Id}");
}

// Get models and metadata for a model ID, including all dependencies (models that it inherits from, components it references)
AsyncPageable<DigitalTwinsModelData> md3 = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });

可擷取模型的 SDK 呼叫全都會傳回 DigitalTwinsModelData 物件。 DigitalTwinsModelData 包含 Azure Digital Twins 執行個體中所儲存模型的相關中繼資料，例如模型的名稱、DTMI 和建立日期。 DigitalTwinsModelData 物件也會選擇性地包括模型本身。 這表示，根據參數，您可以使用擷取呼叫來只擷取中繼資料 (例如，這在您想要顯示可用工具 UI 清單的案例中十分有用) 或整個模型。

RetrieveModelWithDependencies 呼叫不僅會傳回所要求的模型，也會傳回所要求模型所依據的所有模型。

模型不一定會使用上傳時所使用的那個文件表單來傳回。 Azure Digital Twins 只保證傳回表單具有相等語意。

更新模型

本節描述用於更新模型的考量和策略。

更新之前：在整個解決方案的內容中思考

更新模型之前，建議您先全面思考整個解決方案，以及您即將進行的模型變更的影響。 Azure Digital Twins 解決方案中的模型通常會互連，因此請務必注意串聯變更，其中，更新一個模型需要更新數個其他模型。 更新模型將會影響使用模型的對應項，也可能會影響輸入和處理程式碼、用戶端應用程式和自動化報表。

以下一些建議可協助您順暢地管理模型轉換：

• 請考慮在適當時逐步形成整個模型集，以將模型和其關聯性一起保持最新狀態，而不是將模型視為個別實體。
• 將模型視為原始程式碼，並在原始檔控制中加以管理。 對套用至解決方案中其他程式碼的模型和模型變更，套用相同的嚴謹度和注意。

當您準備好繼續模型更新程序時，本節的其餘部分會描述可用來實作更新的策略。

模型更新策略

將模型上傳至您的 Azure Digital Twins 執行個體之後，模型介面即不可變，這表示不會有傳統的模型「編輯」功能。 Azure Digital Twins 也不允許在執行個體中已有相符的模型時重新上傳完全相同的模型。

相反地，如果您想要變更模型 (例如更新 displayName 或 description，或是新增和移除屬性)，則需要取代原始模型。

取代模型時，您可以選擇兩種策略：

• 策略 1：上傳新的模型版本：上傳含新版本號碼的模型，並更新您的對應項以使用該新模型。 除非您刪除模型，否則您的執行個體中會同時存取新版和舊版的模型。
  • 如果您只想要更新一些使用模型的對應項，或想要確保對應項符合其模型並可透過模型轉換寫入時，則請使用此策略。
• 策略 2：刪除舊模型並重新上傳：刪除原始模型，並在該處上傳具有相同名稱和識別碼的新模型 (DTMI 值)。 將舊模型完全取代為新模型。
  • 除了所有回應模型的程式碼之外，當您想要一次更新所有使用此模型的對應項時，請使用此策略。 如果您的模型更新包含模型更新的重大變更，則在您將對應項從舊模型轉換為新模型時，對應項會短暫地與其模型不一致，這表示除非上傳新模型而且對應項符合這個新模型，否則對應項將無法取得任何更新。

注意

不建議在開發外部對模型進行重大變更。

請繼續進行下列各節，以詳細閱讀每個策略選項。

策略 1：上傳新的模型版本

此選項涉及建立新版的模型，並將其上傳至您的執行個體。

此作業不會覆寫舊版的模型，因此除非您移除這些版本，否則您的執行個體中會有多個模型版本並存。 因為新的模型版本和舊的模型版本並存，所以對應項可以使用新版的模型或較舊的版本，這表示上傳新版的模型不會自動影響現有的對應項。 現有的對應項將會維持為舊模型版本的執行個體，而且您可以修補這些對應項以將其更新為新的模型版本。

若要使用此屬性，請遵循下面的步驟。

1.建立和上傳新的模型版本

若要建立新版的現有模型，請從原始模型的 DTDL 開始。 更新、新增或移除您想要變更的欄位。

接下來，更新模型的 id 欄位，以將此模型標示為較新版本的模型。 模型識別碼的最後一個區段 (在 ; 後面) 代表模型編號。 若要指出此模型現在是最近更新過的版本，請將 id 值結尾的數字增量為大於目前版本號碼的任何數字。

例如，如果先前的模型識別碼看起來像這樣：

"@id": "dtmi:com:contoso:PatientRoom;1",

此模型的第 2 版可能看起來像這樣：

"@id": "dtmi:com:contoso:PatientRoom;2",

接著，將新版的模型上傳至您的執行個體。

因此，您的執行個體中將會提供此版本的模型，做為數位對應項之用。 這不會覆寫舊版的模型，因此您的執行個體中會有多個模型版本並存。

2.視需要更新圖形元素

接下來，更新執行個體中的對應項和關聯性，以使用新版的模型，而不是舊版本。

您可以使用下列指示來更新對應項以及更新關聯性。 可更新對應項模型的修補作業看起來會像這樣：

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo;1"
  }
]

重要

更新對應項時，請使用相同的修補程式，以將模型識別碼更新為新的模型版本，以及更新任何必須在對應項上變更的欄位，使其符合新的模型。

您也可能需要更新關聯性以及執行個體中參考此模型的其他模型，使其參考新的模型版本。 您需要執行另一個模型更新作業才能達到此目的，因此請返回本節的開頭，並針對任何需要更新的模型重複此程序。

3.(選用) 解除委任或刪除舊模型版本

如果您不想要使用舊的模型版本，則可以解除委任較舊的模型。 此動作可讓模型保留在執行個體中，但無法用來建立新的數位對應項。

如果您根本不想要舊模型存在於執行個體中，則也可以將其完全刪除。

上面所連結的各節包含解除委任和刪除模型的範例程式碼和考量。

策略 2：刪除舊模型並重新上傳

您可以完全刪除模型，並將編輯過的模型重新上傳至執行個體，而不是遞增模型版本。

Azure Digital Twins 不會記得曾上傳過舊模型，因此此動作會像上傳全新的模型一樣。 使用模型的對應項一旦可用，就會自動切換至新的定義。 根據新定義與舊定義的差異，這些對應項可能會有符合已刪除定義的屬性和關聯性，而這些屬性和關聯性不適用於新定義，因此您可能需要對其進行修補，以確保其保持有效。

若要使用此屬性，請遵循下面的步驟。

1.刪除舊模型

因為 Azure Digital Twins 不允許兩個模型具有相同的識別碼，所以請從執行個體中刪除原始模型開始。

注意

如果您有其他與此模型相依的模型 (透過繼承或元件)，則需要先移除這些參考，才能刪除模型。 您可以先更新這些相依模型以暫時移除參考，或刪除相依模型，並在稍後的步驟中將其重新上傳。

使用下列指示來刪除原始模型。 此動作會讓使用該模型的對應項暫時「孤立」，因為對應項現在正在使用已不存在的模型。 當您重新上傳更新過的模型時，將會在下一個步驟中修復此狀態。

2.建立和上傳新的模型

從原始模型的 DTDL 開始。 更新、新增或移除您想要變更的欄位。

然後，上傳模型至執行個體，就像模型是第一次上傳的新模型一樣。

3.視需要更新圖形元素

既然您已上傳新模型來取代舊模型，圖形中的對應項就會在執行個體中的快取過期並重設之後，自動開始使用新的模型定義。 根據圖形的大小，此程序可能需要 10-15 分鐘或更長的時間。 之後，應該可以存取您模型上的新和已變更的屬性，而且無法再存取已移除的屬性。

注意

如果您先前移除其他相依模型以刪除原始模型，則請在重設快取之後立即將其重新上傳。 如果您已更新相依模型以暫時移除原始模型的參考，則可以再次對其進行更新，以放回參考。

接下來，更新執行個體中的對應項和關聯性，使其屬性符合新模型所定義的屬性。 完成此步驟之前，仍然可以讀取不符合其模型的對應項，但無法對其進行寫入。 如需沒有有效模型之對應項狀態的詳細資訊，請參閱沒有模型的對應項。

有兩種方式可以更新新模型的對應項和關聯性，以再次對其進行寫入：

• 視需要修補對應項和關聯性，使其符合新的模型。 您可以使用下列指示來更新對應項以及更新關聯性。
  • 如果您已新增屬性：不需要更新對應項和關聯性來具有新的值，因為遺漏新值的對應項仍然是有效的對應項。 您可以對其進行修補，但您想要新增新屬性的值。
  • 如果您已移除屬性：需要修補對應項，才能移除現在不適用於新模型的屬性。
  • 如果您已更新屬性：需要修補對應項，才能更新適用於新模型的已變更屬性值。
• 刪除可使用模型的對應項和關聯性，然後將其重新建立。 您可以使用下列指示來刪除對應項和重新建立對應項，以及刪除關聯性和重新建立關聯性。
  • 如果您要對模型進行許多變更，而且很難更新現有的對應項以符合模型，則建議您執行此作業。 不過，如果您有許多透過許多關聯性互連的對應項，則重新建立可能會很複雜。

移除模型

您可以透過下列兩種方式之一，從服務中移除模型：

• 解除委任：一旦解除委任模型，您將無法再使用模型建立新的數位對應項。 已使用此模型的現有數位對應項不會受到影響，因此您仍然可以利用如屬性變更以及新增或刪除關聯性的方式更新現有數位對應項。
• 刪除：此作業將會從解決方案中完全移除模型。 使用此模型的任何對應項都不再與任何有效的模型相關聯，因此這些對應項會被視為完全沒有模型。 您仍然可以讀取這些對應項，但除非將其重新指派至不同的模型，否則將無法對其進行任何更新。

即使這些方式可以一起使用以逐漸移除模型，這些作業還是個別的功能而且不會彼此影響。

注意

如果您想要一次刪除執行個體中的所有模型、對應項和關聯性，請使用刪除作業 API。

解除委任

若要解除委任模型，您可以從 SDK 中使用 DecommissionModel 方法：

// 'client' is a valid DigitalTwinsClient
await client.DecommissionModelAsync(dtmiOfPlanetInterface);
// Write some code that deletes or transitions digital twins
//...

您也可以使用 REST API 呼叫 DigitalTwinModels Update 來解除委任模型。 decommissioned 屬性是唯一可取代為此 API 呼叫的屬性。 JSON 修補程式文件看起來會像這樣：

[
  {
    "op": "replace",
    "path": "/decommissioned",
    "value": true
  }
]

模型的解除委任狀態包括在模型擷取 API 所傳回的 ModelData 記錄中。

刪除

您可以一次刪除執行個體中的所有模型，也可以個別執行。

如需如何同時刪除所有模型的範例，請參閱 GitHub 中的 Azure Digital Twins 存放庫的端對端範例。 CommandLoop.cs 檔案包含 CommandDeleteAllModels 函數，而此函數具有程式碼可刪除執行個體中的所有模型。

若要刪除個別模型，請遵循本節其餘部分的指示和考量。

刪除之前：刪除需求

一般而言，模型可以隨時刪除。

例外狀況是因 extends 關聯性或作為元件而與其他模型相依的模型。 例如，如果 ConferenceRoom 模型是 Room 模型的延伸，而且有 ACUnit 模型做為元件，則您無法刪除 Room 或 ACUnit，直到 ConferenceRoom 移除這些各自的參考為止。

您可以更新相依模型來移除相依性，或完全刪除相依模型來執行此動作。

刪除期間：刪除程序

即使模型符合需求可立即刪除，您可能想要先完成幾個步驟，以避免留下的對應項造成非預期的結果。 以下是一些可以協助您管理程序的步驟：

1. 首先，解除委任模型
2. 等候幾分鐘，確定服務已處理完解除委任之前最後一刻所傳送的任何對應項建立要求
3. 依模型查詢對應項，查看正在使用目前已解除委任模型的所有對應項
4. 如果您不再需要這些對應項，請刪除對應項，或視需要將這些對應項修補為新模型。 您也可以選擇不理會這些對應項，在此情況下，一旦模型遭到刪除，這些對應項會變成沒有模型的對應項。 若要了解此狀態的含意，請參閱下一節。
5. 請再稍候幾分鐘，確保變更已逐漸傳開
6. 刪除模型

若要刪除模型，您可以使用 DeleteModel SDK 呼叫：

// 'client' is a valid DigitalTwinsClient
await client.DeleteModelAsync(IDToDelete);

您也可以使用 DigitalTwinModels Delete REST API 呼叫來刪除模型。

刪除之後：沒有模型的對應項

一旦刪除模型，先前使用該模型的任何數位對應項現在都會被視為沒有模型。 沒有查詢可提供您所有處於此狀態的對應項清單，雖然您仍然可以依已刪除的模型來查詢對應項，以了解哪些對應項受到影響。

若您使用沒有模型的對應項，可執行和不可執行的動作概觀如下。

您可以執行的動作：

• 查詢對應項
• 讀取屬性
• 讀取傳出關聯性
• 新增和刪除傳入關聯性 (如同其他對應項仍然可以與此對應項形成關聯性)
  • 關聯性定義中的 target 仍然可以反映已刪除模型的 DTMI。 此處也可以使用無定義目標的關聯性。
• 刪除關聯
• 刪除對應項

您不可以執行的動作：

• 編輯傳出關聯性 (如同從這個對應項到其他對應項的關聯性)
• 編輯屬性

刪除之後：重新上傳模型

刪除模型之後，您可以決定稍後上傳新模型，新模型的識別碼與您已刪除的模型相同。 以下是這種案例會發生的情況。

• 從解決方案存放區的觀點來看，此作業與上傳全新模型相同。 服務不會記住先前上傳的舊模型。
• 如果圖形中有任何剩餘的對應項參考已刪除的模型，則這些對應項不再是孤立狀態；這個模型識別碼會以新的定義再次變為有效。 不過，如果模型的新定義與已刪除的模型定義不同，這些對應項可能會有屬性和關聯性符合已刪除的定義，因而對新定義而言是無效的。

Azure Digital Twins 不會防止此狀態，因此請小心適當地修補對應項，以確保對應項在模型定義參數切換之後仍然有效。

將 v2 模型轉換為 v3

Azure Digital Twins 支援 DTDL 第 2 版和第 3 版 (在文件中分別縮寫為 v2 和 v3)。 V3 是根據其擴充功能的建議選擇。 本節說明如何將現有的 DTDL v2 模型更新為 DTDL v3。

1. 更新內容。 將模型識別為 v2 或 v3 的主要功能是介面上的 @context 欄位。 若要將模型從 v2 轉換成 v3，請將 dtmi:dtdl:context;2 內容值變更為 dtmi:dtdl:context;3。 對於許多模型，這將是唯一需要的變更。
   1. v2 中的值："@context": "dtmi:dtdl:context;2"
   2. v3 中的值："@context": "dtmi:dtdl:context;3"。
2. 如有需要，請更新語意類型。 在 DTDL v2 中，原生支援語意類型。 在 DTDL v3 中，它們隨附於 QuantitativeTypes 功能延伸模組。 因此，如果您的 v2 模型使用語意類型，則必須在將模型轉換成 v3 時新增功能延伸模組。 若要這樣做，請先將介面上的 @context 欄位從單一值變更為值陣列，然後新增 dtmi:dtdl:extension:quantitativeTypes;1 值。
   1. v2 中的值："@context": "dtmi:dtdl:context;2"
   2. v3 中的值："@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
3. 如有需要，請考慮大小限制。 v2 和 v3 有不同的大小限制，因此如果您的介面非常大，您可能會想要檢閱 DTDL v2 與 v3 之間的差異限制。

經過這些變更後，先前的 DTDL v2 模型已轉換為 DTDL v3 模型。

您可能還會想要考慮 DTDL v3 的新功能 (例如陣列類型屬性、版本放寬和其他功能擴充)，以查看其中是否有任何有益的新增功能。 如需 DTDL v2 與 v3 之間差異的完整清單，請參閱 DTDL v3 語言描述中第 2 版的變更。

注意

目前，Azure Digital Twins Explorer 完全支援 DTDL v2 模型，並支援 DTDL v3 模型的有限功能。

您可以在 [模型] 面板中檢視 DTDL v3 模型，也可以檢視和編輯使用 DTDL v3 模型建立的對應項 (包括具有陣列屬性的對應項)。 不過，DTDL v3 模型不會顯示在 [模型圖表] 面板中，而且無法使用 Azure Digital Twins Explorer 匯入這些模型。 若要將 DTDL v3 模型匯入執行個體，請使用另一個開發人員介面，例如 API 和 SDK 或 Azure CLI。

下一步

瞭解如何根據您的模型來建立和管理數位對應項：

• 管理數位對應項