Azure Digital Twins API 和 SDK
本文提供可用的 Azure Digital Twins API 概觀，以及與其互動的方法。 您可以直接使用 REST API 與其相關聯的 Swaggers（透過 Postman 之類的工具），或透過 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。
您也可以透過 Azure 入口網站 和 CLI 與 Azure Digital Twins 互動，以練習控制平面 API。
資料平面 API
數據平面 API 是用來管理 Azure Digital Twins 實例內元素的 Azure Digital Twins API。 它們包括建立路由、上傳模型、建立關聯性及管理對應項等作業，而且可廣泛分成下列類別：
DigitalTwinModels- DigitalTwinModels 類別包含 API 來管理 Azure Digital Twins 實例中的模型 。 管理活動包括上傳、驗證、擷取和刪除在 DTDL 中撰寫的模型。DigitalTwins- DigitalTwins 類別包含 API，可讓開發人員在 Azure Digital Twins 實例中建立、修改和刪除 數位 對應項及其關聯性。Query- 查詢類別可讓開發人員 跨關聯性，在對應項圖表 中尋找一組數字對應項。Event Routes- 事件路由類別包含 API，可 透過系統和下游服務來路由數據。Import Jobs- 匯入作業 API 可讓您管理長時間執行的異步動作，以 大量匯入模型、對應項和關聯性。Delete Jobs- 刪除作業 API 可讓您管理長時間執行的異步動作，以 刪除實例中的所有模型、對應項和關聯性。
若要直接呼叫 API，請參考數據平面 Swagger 存放庫中的最新 Swagger 資料夾。 此資料夾也包含顯示使用方式的範例資料夾。 您也可以檢視 數據平面 API 參考檔。
以下是 Azure Digital Twins 數據平面 API 目前可用的 SDK。
您也可以透過 CLI 與 Azure Digital Twins 互動，以練習數據平面 API。
使用方式和驗證注意事項
本節包含使用 API 和 SDK 的詳細資訊。
API 附注
以下是直接呼叫 Azure Digital Twins API 的一些一般資訊。
- 您可以使用 Postman 之類的 HTTP REST 測試工具來直接呼叫 Azure Digital Twins API。 如需此程式的詳細資訊，請參閱 使用 Postman 呼叫 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是服務呼叫的傳回對象的類別。 Response 類別會封裝服務傳回，並在其Value字段中呈現傳回值。 - 具有分頁結果的服務方法會傳回
Pageable<T>或AsyncPageable<T>做為結果。 如需 類別的詳細資訊Pageable<T>，請參閱其 參考檔;如需詳細資訊AsyncPageable<T>，請參閱其 參考檔。 - 您可以使用迴圈逐一
await foreach查看分頁結果。 如需此程式的詳細資訊，請參閱 在 C# 8 中使用 Async Enumerables 進行反覆運算。 - 服務方法會盡可能傳回強型別物件。 不過，由於 Azure Digital Twins 是以使用者於運行時間自定義的模型為基礎（透過上傳至服務的 DTDL 模型），因此許多服務 API 會採用並傳回 JSON 格式的對應項數據。
.NET （C#） SDK 中的串行化協助程式
串行化協助程式是 .NET （C#） SDK 中提供的協助程式函式，可用來快速建立或還原串行化對應項數據，以存取基本資訊。 由於核心 SDK 方法預設會以 JSON 形式傳回對應項數據，因此使用這些協助程式類別進一步細分對應項數據會很有説明。
可用的協助程式類別如下：
BasicDigitalTwin：一般表示數字對應項的核心數據BasicDigitalTwinComponent：泛型表示 屬性中的Contents元件BasicDigitalTwinBasicRelationship：一般表示關聯性的核心數據DigitalTwinsJsonPropertyName：包含字串常數，以用於自定義數位對應項類型的 JSON 串行化和還原串行化
使用匯入作業 API 大容量導入
匯 入作業 API 是數據平面 API ，可讓您在單一 API 呼叫中匯入一組模型、對應項和/或關聯性。 匯入作業 API 作業也隨附於 CLI 命令 和數據 平面 SDK 中。 使用匯入作業 API 需要使用 Azure Blob 儲存體。
檢查權限
若要使用匯入作業 API，您必須啟用本節中所述的許可權設定。
首先，您需要 Azure Digital Twins 實例的系統指派受控識別 。 如需設定實例系統受控識別的指示，請參閱 啟用/停用實例的受控識別。
您必須在 Azure Digital Twins 實體中具有 下列資料動作類別的寫入權限 ：
Microsoft.DigitalTwins/jobs/*- 您要包含在 Jobs 呼叫中的任何圖形元素。 這可能包括
Microsoft.DigitalTwins/models/*、Microsoft.DigitalTwins/digitaltwins/*和/ 或Microsoft.DigitalTwins/digitaltwins/relationships/*。
提供所有這些許可權的內建角色是 Azure Digital Twins 數據擁有者。 您也可以使用自定義角色，只授與所需數據類型的細微存取權。 如需 Azure Digital Twins 中角色的詳細資訊，請參閱 Azure Digital Twins 解決方案的安全性。
注意
如果您嘗試匯入作業 API 呼叫，而且遺漏您嘗試匯入之其中一個圖形專案類型的寫入許可權，作業將會略過該類型並匯入其他類型。 例如，如果您有模型和對應項的寫入許可權，但無法關聯性，則嘗試大容量導入這三種類型的專案只會成功匯入模型和對應項。 作業狀態會反映失敗，訊息會指出遺漏哪些許可權。
您也必須將下列 RBAC 許可權授與 Azure Digital Twins 實例的系統指派受控識別，以便它可以存取 Azure 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 時，請記住下列考慮：
- 匯入作業不是不可部分完成的作業。 在失敗、部分作業完成或使用 Cancel 作業的情況下，沒有任何復原。
- 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 要求計量。
下一步
瞭解如何使用 Postman 對 Azure Digital Twins API 提出直接要求：
或者，透過本教學課程建立用戶端應用程式來練習使用 .NET SDK：