Azure Digital Twins Swagger 參考文件
重要
已發行新版本的 Azure Digital Twins 服務。 在新的服務擴充功能中，本檔集) 中所述的原始 Azure Digital Twins 服務 (已淘汰。
若要檢視新服務的檔，請流覽使用中的 Azure Digital Twins 檔。
每個已佈建的 Azure Digital Twins 執行個體都包含本身自動產生的 Swagger 參考文件。
Swagger \(英文\) (或 OpenAPI \(英文\)) 會將複雜的 API 資訊結合至可互動且與語言無關的參考資源。 若要對 API 執行作業，Swagger 會針對要使用的 JSON 承載、HTTP 方法和特定端點提供重要的參考資料。
Swagger 摘要
Swagger 會提供可互動的 API 摘要，包括：
- API 和物件模型資訊。
- REST API 端點，會指定必要的要求承載、標頭、參數、內容路徑和 HTTP 方法。
- API 功能測試。
- 用於驗證和確認 HTTP 回應的範例回應資訊。
- 錯誤碼資訊。
Swagger 是一個很便利的工具，可協助您開發和測試對 Azure Digital Twins 管理 API 所發出的呼叫。
提示
Swagger 搶先預覽中有 API 功能集的示範。 這些內容位在 docs.westcentralus.azuresmartspaces.net/management/swagger。
您可以在以下位置存取自己產生的管理 API Swagger 文件：
https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
| 名稱 | 更換為 |
|---|---|
| YOUR_INSTANCE_NAME | Azure Digital Twins 執行個體的名稱 |
| YOUR_LOCATION | 裝載您執行個體的伺服器區域 |
參考資料
自動產生的 Swagger 參考資料提供重要概念的快速概觀、可用的管理 API 端點，以及每個物件模型的說明，以協助執行開發和測試工作。
透過簡單摘要來說明 API。
此外，也會列出管理 API 物件模型。
您可以選取每個列出的物件模型，以取得更詳細的主要屬性摘要。
產生的 Swagger 物件模型方便讀取所有可用的 Azure Digital Twins 物件和 API。 開發人員可在於 Azure Digital Twins 上建置解決方案時使用此資源。
端點摘要
Swagger 也提供管理 API 中所有端點的整體概觀。
每個列出的端點也會包含必要的要求資訊，例如：
- 必要參數。
- 必要參數資料類型。
- 要存取資源的 HTTP 方法。
選取每個資源以顯示其其他內容，以取得更詳細的概觀。
使用 Swagger 來測試端點
Swagger 所提供的強大功能之一是直接透過文件 UI 來測試 API 端點。
選取特定端點之後，將會顯示 [ 試用] 按鈕。
展開該區段後，即會顯示每個必要和選擇性參數的輸入欄位。 輸入正確的值，然後選取 [執行]。
當您執行測試之後，就可以驗證回應資料。
Swagger 回應資料
每個列出的端點也會包含回應主體資料，可用來驗證您的開發和測試。 這些範例包括成功 HTTP 要求的狀態碼和 JSON。
範例也會包含錯誤碼，可用來協助偵錯或改善失敗的測試。
Swagger OAuth 2.0 授權
注意
- 建立 Azure Digital Twins 資源的使用者主體會有空間管理員角色指派，而且能夠為其他使用者建立其他角色指派。 這些使用者及其角色可以獲授權來呼叫 API。
請遵循 快速入門 中的步驟來建立及設定 Azure Active Directory 應用程式。 或者，您可以重複使用現有的應用程式註冊。
將下列 重新導向 URI 新增至您的 Azure Active Directory 應用程式註冊：
https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html名稱 更換為 例如 YOUR_SWAGGER_URL 您在入口網站中找到的管理 REST API 檔 URL https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger選取 [隱含授>與存取權杖] 核取方塊，以允許使用 OAuth 2.0 隱含授與流程。 選取 [ 設定]，然後 選取 [儲存]。
複製 Azure Active Directory 應用程式的 用戶端識別碼 。
完成 Azure Active Directory 註冊之後：
選取 Swagger 頁面上的 [ 授權] 按鈕。
將應用程式識別碼貼到 [client_id ] 欄位中。
然後，系統會將您重新導向至下列成功強制回應。
若要深入瞭解以互動方式測試受 OAuth 2.0 保護的要求，請閱讀 官方檔。
後續步驟
若要深入了解 Azure Digital Twins 物件模型和空間智慧圖表，請參閱了解 Azure Digital Twins 物件模型。
若要了解如何使用管理 API 進行驗證，請參閱使用 API 進行驗證。