Azure Digital Twins API 和 SDK

發行項
05/16/2024

本文提供可用的 Azure Digital Twins API 概觀，以及與其互動的方法。您可以直接使用 REST API 與其相關聯的 Swaggers，或透過 SDK。

Azure Digital Twins 配備了用於管理執行個體及其元素的控制平面 API、資料平面 API 和 SDK。

控制平面 API 是 Azure Resource Manager (ARM) API，並涵蓋建立和刪除執行個體等資源管理作業。
資料平面 API 是 Azure Digital Twins API，用於各種資料管理操作，例如管理模型、對應項和圖表。
SDK 會利用現有的 API，透過 Azure Digital Twins 輕鬆開發自訂應用程式。

控制平面 API

控制平面 API 是用來管理整個 Azure Digital Twins 執行個體的 ARM API，因此它們涵蓋了建立或刪除整個執行個體等操作。您還將使用這些 API 來建立和刪除端點。

若要直接呼叫 API，請參考控制平面 Swagger 存放庫中的最新 Swagger 資料夾。此資料夾也包含顯示使用量的範例資料夾。

以下是 Azure Digital Twins 控制平面 API 目前可用的 SDK。

SDK 語言	套件連結	參考文件	原始程式碼
.NET (C#)	NuGet 上的 Azure.ResourceManager.DigitalTwins	適用於 .NET 的 Azure DigitalTwins SDK 參考	GitHub 上適用於 .NET 的 Microsoft Azure Digital Twins 管理用戶端程式庫
Java	Maven 上的 azure-resourcemanager-digitaltwins	資源管理的參考 - Digital Twins	GitHub 上適用於 Java 的 Azure Resource Manager AzureDigitalTwins 用戶端程式庫
JavaScript	npm 上適用於 JavaScript 的 AzureDigitalTwinsManagement 用戶端程式庫		GitHub 上適用於 JavaScript 的 AzureDigitalTwinsManagement 用戶端程式庫
Python	PyPI 上的 azure-mgmt-digitaltwins		GitHub 上的 Microsoft Azure SDK for Python
Go	azure-sdk-for-go/services/digitaltwins/mgmt		GitHub 上的 Azure SDK for Go

您也可以透過 Azure 入口網站和 CLI 與 Azure Digital Twins 互動，以便執行控制平面 API。

資料平面 API

資料平面 API 是用來管理 Azure Digital Twins 執行個體內元素的 Azure Digital Twins API。它們包括建立路由、上傳模型、建立關聯性及管理對應項等作業，可廣泛分成下列類別：

DigitalTwinModels - DigitalTwinModels 類別包含用來管理 Azure Digital Twins 執行個體中模型的 API。管理活動包括上傳、驗證、擷取和刪除 DTDL 中撰寫的模型。
DigitalTwins - DigitalTwins 類別包含可讓開發人員在 Azure Digital Twins 執行個體中建立、修改和刪除數位對應項及其關聯性的 API。
Query - 查詢類別可讓開發人員跨多個關聯性，在對應項圖表中尋找數位對應項集合。
Event Routes - 事件路由類別包含可透過系統和下游服務來路由資料的 API。
Import Jobs - 匯入作業 API 可讓您管理長時間執行的非同步動作，以大量匯入模型、對應項和關聯性。
Delete Jobs - 刪除作業 API 可讓您管理長時間執行的非同步動作，以刪除執行個體中的所有模型、對應項和關聯性。

若要直接呼叫 API，請參考資料平面 Swagger 存放庫中的最新 Swagger 資料夾。此資料夾也包含顯示使用量的範例資料夾。您也可以檢視資料平面 API 參考文件。

以下是 Azure Digital Twins 資料平面 API 目前可用的 SDK。

SDK 語言	套件連結	參考文件	原始程式碼
.NET (C#)	NuGet 上的 Azure.DigitalTwins.Core	適用於 .NET 的 Azure IoT Digital Twins 用戶端程式庫參考	GitHub 上適用於 .NET 的 Azure IoT Digital Twins 用戶端程式庫
Java	Maven 上的 com.azure:azure-digitaltwins-core	適用於 Java 的 Azure Digital Twins SDK 參考	GitHub 上適用於 Java 的 Azure IoT Digital Twins 用戶端程式庫
JavaScript	npm 上適用於 JavaScript 的 Azure Azure Digital Twins Core 用戶端程式庫	Reference for @azure/digital-twins-core	GitHub 上適用於 JavaScript 的 Azure Azure Digital Twins Core 用戶端程式庫
Python	PyPI 上適用於 Python 的 Azure Azure Digital Twins Core 用戶端程式庫	azure-digitaltwins-core 的參考	GitHub 上適用於 Python 的 Azure Azure Digital Twins Core 用戶端程式庫

您也可以透過 CLI 與 Azure Digital Twins 互動，以便執行資料平面 API。

使用方式與驗證備註

本節包含使用 API 和 SDK 的詳細資訊。

API 備註

以下是直接呼叫 Azure Digital Twins API 的一些一般資訊。

您可以使用 HTTP REST 測試工具來直接呼叫 Azure Digital Twins API。如需此程式的詳細資訊，請參閱呼叫 Azure Digital Twins API。
Azure Digital Twins 目前不支援跨原始來源資源共用 (CORS)。如需影響和解決策略的詳細資訊，請參閱 Azure Digital Twins 的跨來源資源共享 (CORS)。

以下是 API 要求驗證的一些詳細資訊。

為 Azure Digital Twins API 要求產生持有人權杖的其中一種方式是使用 az account get-access-token CLI 命令。如需詳細指示，請參閱新增持有人令牌。
對 Azure Digital Twins API 提出要求時，使用者或服務主體必須屬於 Azure Digital Twins 執行個體所在的相同 Microsoft Entra ID 租用戶。為了防止惡意掃描 Azure Digital Twins 端點，從原始租用戶外部要求存取權杖會傳回「404 找不到子網域」錯誤訊息。即使使用者或服務主體已透過 Microsoft Entra B2B 共同作業獲得 Azure Digital Twins 資料擁有者或 Azure Digital Twins 資料讀者角色，也會傳回此錯誤。如需如何跨多個租用戶達成存取的資訊，請參閱撰寫應用程式驗證碼。

SDK 備註

Azure Digital Twins 的基礎 SDK 是 Azure.Core。如需 SDK 基礎結構和類型的參考，請參閱 Azure 命名空間文件。

以下是使用 SDK 驗證的一些詳細資訊。

從實例化 DigitalTwinsClient 類別開始。建構函式需要可透過 Azure.Identity 套件中不同類型驗證方法取得的認證。如需 Azure.Identity 的詳細資訊，請參閱其命名空間文件。
您或許會在開始使用時發現 InteractiveBrowserCredential 很有用，但還有數個其他選項，包括受控識別的認證，您可能會透過這些選項來驗證針對 Azure Digital Twins 的使用 MSI 設定 Azure 函式。如需 InteractiveBrowserCredential 的詳細資訊，請參閱其類別文件。

以下是有關函式和傳回資料的一些詳細資訊。

所有服務 API 呼叫都會公開為 DigitalTwinsClient 類別上的成員函式。
所有服務函式都存在於同步和非同步版本中。
所有服務函式都會針對任何傳回 400 以上的狀態擲回例外狀況。請務必將呼叫包裝至 try 區段，並至少攔截 RequestFailedExceptions。如需這類例外狀況的詳細資訊，請參閱其參考文件。
大部分的服務方法會傳回 Response<T> 或 Task<Response<T>> (適用於非同步呼叫)，T 則為服務呼叫的傳回物件類別。 [回應] 類別會封裝服務傳回，並在其 Value 欄位中顯示傳回值。
具有分頁結果的服務方法會傳回 Pageable<T> 或 AsyncPageable<T> 做為結果。如需 Pageable<T> 類別的詳細資訊，請參閱其參考文件；如需 AsyncPageable<T> 的詳細資訊，請參閱其參考文件。
您可以使用 await foreach 迴圈逐一查看分頁結果。如需此流程的詳細資訊，請參閱在 C# 8 中使用非同步 Enumerable 逐一查看。
服務方法會盡可能傳回強類型物件。不過，由於 Azure Digital Twins 是以執行階段使用者自訂設定的模型為基礎 (透過上傳至服務的 DTDL 模型)，因此許多服務 API 會採用 JSON 格式並傳回對應項資料。

.NET (C#) SDK 中的序列化協助程式

序列化協助程式是 .NET (C#) SDK 中提供的協助程式函式，可用來快速建立或還原序列化對應項資料，以存取基本資訊。由於核心 SDK 方法預設以 JSON 形式傳回對應項資料，因此使用這些協助程式類別來進一步細分對應項資料會非常實用。

可用的協助程式類別如下：

BasicDigitalTwin：通常代表數位對應項的核心資料
BasicDigitalTwinComponent：通常代表 BasicDigitalTwin 的 Contents 屬性中的某個元件
BasicRelationship：通常代表關聯性的核心資料
DigitalTwinsJsonPropertyName：包含字串常數，用於自訂數位對應項類型的 JSON 序列化和還原序列化

使用匯入作業 API 大量匯入

匯入作業 API 是一種資料平面 API，可讓您在單一 API 呼叫中匯入模型集合、對應項和/或關聯性。匯入作業 API 作業也包含在 CLI 命令和資料平面 SDK。使用匯入作業 API 需要使用 Azure Blob 儲存體。

檢查權限

若要使用匯入作業 API，您必須啟用本節中所述的權限設定。

首先，您需要為您的 Azure Digital Twins 執行個體提供系統指派的受控識別。如需執行個體的設定系統受控識別的指示，請參閱為執行個體啟用/停用受控識別。

您必須在 Azure Digital Twins 執行個體中擁有下列資料動作類別的寫入權限：

Microsoft.DigitalTwins/jobs/*
您要包含在作業呼叫中的任何圖表元素。這可能包括 Microsoft.DigitalTwins/models/*、Microsoft.DigitalTwins/digitaltwins/*，和/或 Microsoft.DigitalTwins/digitaltwins/relationships/*。

提供所有這些權限的內建角色是 Azure Digital Twins 資料擁有者。您也可以使用自訂角色來僅授與對所需資料類型的細微存取權限。如需 Azure Digital Twins 中角色的詳細資訊，請參閱 Azure Digital Twins 解決方案的安全性。

注意

如果您嘗試匯入作業 API 呼叫，但您遺漏對要匯入之圖表元素類型之一的寫入權限，則該作業將略過該類型並匯入其他類型。例如，如果您有模型和對應項的寫入權限，但無關聯性，則嘗試大量匯入所有三種類型的元素只會成功匯入模型和對應項。作業狀態會反映失敗，訊息會指出遺漏哪些權限。

您還需要向 Azure Digital Twins 執行個體的系統指派的受控識別授與以下 RBAC 權限，以便其可以存取 Blob 儲存體容器中的輸入和輸出檔案：

Azure 儲存體輸入 Blob 容器的儲存體 Blob 資料讀取器
Azure 儲存體輸出 Blob 容器的儲存體 Blob 資料參與者

最後，產生可在作業 API 的要求中使用的持有人權杖。如需指示，請參閱新增持有人令牌。

格式化資料

API 接受來自 NDJSON 檔案的圖表資訊輸入，該檔案必須上傳至 Azure Blob 儲存體容器。檔案開頭為 Header 區段，隨後接著選擇性區段 Models、Twins 和 Relationships。您不必在檔案中包含這三種類型的圖形資料，但存在的任何區段全都必須遵循該順序。使用此 API 建立的對應項和關聯性可以選擇性地包含其屬性的初始化。

以下是匯入 API 的範例輸入資料檔案：

{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}

提示

如需將模型、對應項和關聯性轉換成匯入 API 所支援的 NDJSON 範例專案，請參閱 Azure Digital Twins 大量匯入 NDJSON 產生器。範例專案是針對 .NET 所撰寫，可以下載或調整以協助您建立自己的匯入檔案。

建立檔案後，使用您慣用的上傳方法將其上傳至 Azure Blob 儲存體中的區塊 Blob (一些選項如 AzCopy 命令、Azure CLI 或 Azure 入口網站)。您將在匯入作業 API 呼叫主體中使用 NDJSON 檔案的 Blob 儲存體 URL。

執行匯入作業

現在，您可以繼續呼叫匯入作業 API。如需在一個 API 呼叫中匯入完整圖表的詳細指示，請參閱使用匯入作業 API 大量上傳模型、對應項和關聯性。您也可以使用匯入作業 API 獨立匯入每個資源類型。如需搭配個別資源類型使用匯入作業 API 的詳細資訊，請參閱模型、對應項和關聯性的匯入作業 API 指示。

在 API 呼叫的主體中，您將提供 NDJSON 輸入檔的 Blob 儲存體 URL。您也會提供新的 Blob 儲存體 URL，以指出您想要在服務建立輸出記錄之後儲存的位置。

重要

請確保 Azure Digital Twins 執行個體之系統指派的受控識別具有檢查權限一節中所述的儲存體 Blob RBAC 權限。

在匯入作業執行時，服務會產生結構化輸出記錄，並儲存為 Blob 容器中的新附加 Blob，其位於您在要求中為輸出 Blob 指定的 URL 位置。以下是成功匯入模型、對應項和關聯性之作業的輸出記錄範例：

{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}

作業完成後，您可以使用 BulkOperationEntityCount 計量來查看擷取的實體總數。

也可以使用匯入作業 API 中的取消作業來取消正在執行的匯入作業。作業取消且不再執行時，您就可以將其刪除。

限制和考量

在使用匯入作業 API 時，請記住下列考量：

匯入作業不是不可部分完成的作業。在失敗、部分作業完成或取消作業之使用的情況下，無法進行復原。
在 Azure Digital Twins 執行個體內，每次僅支援一次大量作業。您可以在 Azure Digital Twins 限制中檢視這項資訊和其他作業 API 的數值限制。

使用刪除作業 API 進行大量刪除

刪除作業 API 是一種資料平面 API，可讓您透過單一 API 呼叫刪除所有模型、對應項和/或關聯性。刪除作業 API 作業也可作為 CLI 命令。請瀏覽 API 文件，查看建立刪除作業並檢查其狀態的要求詳細資訊。

若要確保已刪除所有元素，請在使用刪除作業 API 時遵循這些建議：

如需如何產生持有人令牌以驗證 API 要求的指示，請參閱新增持有人令牌。
如果您近期將大量實體匯入至圖表，請等候一段時間，並確認圖表中的所有元素皆已同步處理，再開始進行刪除作業。
停止執行個體上的所有作業，特別是上傳作業，直到刪除作業完成為止。

視所刪除的圖表大小而定，刪除作業可能需要幾分鐘到數小時的時間。

刪除作業的預設逾時期間為 12 小時，可透過 API 上的查詢參數將其調整為 15 分鐘到 24 小時之間的任意值。這是刪除作業在逾時之前執行的時間量，如果作業尚未完成，則服務將嘗試停止該作業。

限制和其他考量

在使用刪除作業 API 時，請記住下列考量：

刪除作業不是不可部分完成的作業。在失敗、部分作業完成或作業逾時的情況下，無法進行復原。
在 Azure Digital Twins 執行個體內，每次僅支援一次大量作業。您可以在 Azure Digital Twins 限制中檢視這項資訊和其他作業 API 的數值限制。

監視 API 計量

您可以在 Azure 入口網站中檢視 API 計量，例如要求、延遲和失敗率等。

如需 Azure Digital Twins 計量檢視和管理的相關資訊，請參閱監視執行個體。如需 Azure Digital Twins 可用的 API 計量完整清單，請參閱 Azure Digital Twins API 要求計量。

下一步

瞭解如何對 Azure Digital Twins API 提出直接要求：

呼叫 Azure Digital Twins API

或者，透過本教學課程建立用戶端應用程式來練習使用 .NET SDK：

撰寫用戶端應用程式的程式碼

共用方式為