共用方式為

Azure 球體公用 API 概觀

  • 發行項

Azure 球體公用 API 是一組服務端點，支援 HTTP 營運，以建立和管理 Azure 球體資源，例如租使用者、產品、部署和裝置群組。 Azure 球體公用 API 使用 REST (REpresentational State Transfer) HTTP 通訊協定來傳送作業要求和回應。 在作業回應中傳回的資料會格式化為 JSON (JavaScript 物件標記法) 。 可用的作業會在 Azure 球體公用 API 參照中記錄。

客戶可能會偏好使用 Azure 球體命令列介面 (CLI) ，而不是使用公用 API 來執行資源管理工作。 CLI 透過摘要公開 API 的程式設計複雜度，簡化作業要求和回應的傳送和接收。 CLI 命令使用 Azure 球體公用 API 來執行工作，但 CLI 命令的簡單語法可讓您更容易使用。

有些客戶可能會想要建立自己的使用者介面 (UI) 以執行資源管理工作。 Azure 球體公用 API 可用來建立自訂 UI。 您無法使用 Azure 球體 CLI 建立自訂 UI。

REST API 要求的元件

REST API 要求包含下列三個元件：

  1. 下列表單中的要求 URI：

    VERB https://prod.core.sphere.azure.net/v{version}/{collection}/{id}…[{resourceId} | {collection}]

    參數：

    • 集合：一或多個集合。 支援多個巢狀集合，因此相對路徑可以包含 /collection/id/collection/id...

      例子： /v2/tenants/{tenantId}/devices/{deviceId}/images

    • resourceId：特定資源的識別碼，可存取集合內的特定資源。

      例子： /v2/tenants/{tenantId}/devicegroups/{devicegroupid}

    • 版本：API 版本，可識別 API 的版本。 每個 API 要求都應包含 api 版本，以避免您的應用程式或服務在 API 演進時中斷。

      例子： /v2

  2. HTTP 要求郵件標題欄位：

    • 必要的 HTTP 方法 (也稱為運算或動詞) ，它會告訴服務您要求的作業類型。
    • 根據指定的 URI 和 HTTP 方法所要求的其他頁首欄位。 具體來說，授權標題會提供包含要求之用戶端授權權杖的記事權杖。

  3. 選用的 HTTP 要求郵件內文欄位以支援 URI 和 HTTP 作業。

    • 針對 HTTP POST 或 PUT 操作，本文應在內容類型要求標頭以及應用程式/json 中指定。

REST API 回應的元件

REST API 回應包含下列兩個元件：

  1. HTTP 回復郵件標題欄位：

  2. 選用的 HTTP 回應郵件內文欄位：

    • MIME 編碼的回應物件可能會在 HTTP 回應內文中傳回，例如來自 GET 方法的回應，該方法會傳回資料。 這些物件一律會以結構化的 JSON 格式傳回，如 Content-Type 回應標頭所示。

要求的驗證

您的應用程式或服務必須先通過 Azure 球體公用 API 的驗證，才能提出有效的要求。 下表顯示您可以驗證的一些方式。

應用程式類型 描述 例子 驗證機制
互動式用戶端 GUI 型用戶端應用程式 列舉裝置的 Windows 應用程式 MICROSOFT Authentication Library (MSAL)
互動式 JavaScript GUI 型 JavaScript 應用程式 顯示裝置群組部署的 AngularJS 單一頁面應用程式。 MSAL
互動式網頁 GUI 型 Web 應用程式 顯示組建摘要的自訂 Web 儀表板 OAuth 2

注意

Azure Active Directory 平臺 正在演進到 Microsoft Identity 平臺。 如需詳細資訊，請參閱 Azure 球體的新增功能。

驗證文件庫值

如果您呼叫 Microsoft 驗證庫 (MSAL) 取得要用於驗證的 Bearer Token，則必須提供四個值：

  • Azure 球體用戶端應用程式識別碼： 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F 成功驗證) 需要 (
  • 使用者的範圍： https://sphere.azure.net/api/user_impersonation
  • Azure 球體租使用者識別碼： 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
  • Azure 球體 API 端點： https://prod.core.sphere.azure.net/

如需驗證的詳細資訊，請參閱 Microsoft 驗證庫 (MSAL) 和 驗證流程。

提出要求

使用 Azure 球體驗證之後，您可以提出要求並接收回應。

下列 C# 範例使用 HttpClient 類別 提出要求。

namespace SpherePublicAPISample
{
    using System;
    using System.Collections.Generic;
    using System.Net.Http;
    using System.Net.Http.Headers;
    using System.Threading;
    using System.Threading.Tasks;
    // You install the Microsoft.Identity.Client reference by using Nuget,
    // starting at https://www.nuget.org/packages/Microsoft.Identity.Client.
    // Follow the instructions to install using Package Manager.
    using Microsoft.Identity.Client;

    class Program
    {
        // Azure Sphere Public API resource URI
        private readonly List<string> Scopes = new List<string>() { "https://sphere.azure.net/api/user_impersonation" };

        // Azure Sphere Public API client application ID.
        private const string ClientApplicationId = "0b1c8f7e-28d2-4378-97e2-7d7d63f7c87f";

        // Azure Sphere Tenant ID.
        public const string Tenant = "7d71c83c-ccdf-45b7-b3c9-9c41b94406d9";

        // Azure Sphere Public API URI
        private static readonly Uri AzureSphereApiUri = new Uri("https://prod.core.sphere.azure.net/");

        // Program entry-point.
        // returns Zero on success, otherwise non-zero.
        private static int Main()
        {
            try
            {
                CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();

                Program program = new Program();

                program.ExecuteAsync(cancellationTokenSource.Token)
                    .GetAwaiter()
                    .GetResult();

                Console.ReadLine();
            }
            catch (Exception ex)
            {
                Console.Error.WriteLine(ex.ToString());
                return -1;
            }
            return 0;
        } // end of main

        private async Task ExecuteAsync(CancellationToken cancellationToken)
        {
            IPublicClientApplication publicClientApp = PublicClientApplicationBuilder
                .Create(ClientApplicationId)
                .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
                .WithRedirectUri("http://localhost")
                .Build();

            AuthenticationResult authResult = await publicClientApp.AcquireTokenInteractive(Scopes)
                .ExecuteAsync();

            string accessToken = authResult.AccessToken;

            // Call the Azure Sphere API to get tenants available to the authenticated user.
            string result = await GetAsync(accessToken, "v2/tenants", cancellationToken);

            Console.WriteLine(result);
        } // end of ExecuteAsync method

        private async Task<string> GetAsync(string accessToken, string relativeUrl, CancellationToken cancellationToken)
        {
            using (HttpClient client = new HttpClient())
            {
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

                Uri uri = new Uri(AzureSphereApiUri, relativeUrl);

                using (HttpResponseMessage response = await client.GetAsync(uri, cancellationToken))
                {
                    response.EnsureSuccessStatusCode();
                    return await response.Content.ReadAsStringAsync();
                }
            }
        } // end of GetAsync method

    } // end of class Program
}

接收回應

每個通話都會以下列格式傳回 JSON 回應：

[{"Id":"{tenantId}","Name":"Contoso","Roles":null}]

Azure 球體公用 API 錯誤碼

Azure 球體公用 API 會傳回下列錯誤碼：

  • 400 - 錯誤要求
  • 404 - 找不到
  • 409 - 衝突
  • 410 - 消失
  • 429 - 太多要求
  • 500 - 內部伺服器錯誤

下一節提供處理錯誤的指導方針。 如需特定錯誤碼的詳細資訊，請參閱 RFC 7231。

錯誤處理指導方針

4xx 錯誤： 惡意表單要求可能會導致錯誤。 檢查您的要求語法及傳遞的資料。

429 個錯誤： 為了保護 Azure 球體服務不受 DDoS) 攻擊的分散式阻斷服務 (，我們會追蹤和節流撥打大量服務電話的裝置、使用者或租使用者。 429 錯誤訊息表示裝置、使用者或租使用者在短時間內嘗試撥打 Azure 球體服務太多次。 請稍候，然後再撥號給 Azure 球體服務。

500 個錯誤： 有時可能會發生暫時伺服器錯誤。 如果您收到伺服器錯誤，請重試幾次要求，看看錯誤是否消失。

CORS 支援

本版本不支援跨區域原始共用 (CORS) 。

相關內容