Azure Sphere 公用 API 概觀

發行項
09/27/2024

重要

這是 Azure Sphere （舊版）檔。 Azure Sphere（舊版）將於 2027 年 9 月 27 日淘汰，且使用者此時必須移轉至 Azure Sphere（整合式）。 使用位於 TOC 上方的版本選取器來檢視 Azure Sphere （整合式）檔。

Azure Sphere 公用 API 是一組服務端點，可支援 HTTP 作業來建立和管理 Azure Sphere 資源，例如租使用者、產品、部署和裝置群組。 Azure Sphere 公用 API 會使用 REST （REpresentational State Transfer） HTTP 通訊協定來傳送作業要求和回應。作業回應中傳回的數據會以 JSON （JavaScript 物件表示法）格式化。可用的作業記載於 Azure Sphere 公用 API 參考中。

客戶可能偏好使用 Azure Sphere 命令行介面（CLI）而不是公用 API 來執行資源管理工作。 CLI 藉由抽象化公用 API 的大部分程式設計複雜度，簡化作業要求和回應的傳送和接收。 CLI 命令會使用 Azure Sphere 公用 API 來執行工作，但 CLI 命令的簡單語法可讓它們更容易使用。

有些客戶可能會想要建置自己的使用者介面（UI），以執行資源管理工作。 Azure Sphere 公用 API 可用來建置自定義 UI。無法使用 Azure Sphere CLI 建置自定義 UI。

REST API 要求的元件

REST API 要求具有下列三個元件：

要求 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}
- version：識別 API 版本的 API 版本。每個 API 要求都應該包含 API 版本，以避免隨著 API 演進而中斷您的應用程式或服務。
  
  範例: /v2
HTTP 要求訊息標頭欄位：
- 必要的 HTTP 方法 (也稱為作業或動詞)，這會告知服務所要求的作業類型。
- 指定的 URI 和 HTTP 方法需要的其他標頭欄位。具體而言，提供持有人令牌的授權標頭，其中包含要求的用戶端授權令牌。
選擇性的 HTTP 要求訊息本文字段，以支援 URI 和 HTTP 作業。
- 針對 HTTP POST 或 PUT 作業，本文應該在 Content-Type 要求標頭以及 application/json 中指定。

REST API 回應的元件

REST API 回應具有下列兩個元件：

HTTP 回應訊息標頭欄位：
- HTTP 狀態代碼。成功呼叫會傳回 2xx 代碼;4xx 和 5xx 代碼是錯誤狀態—如需詳細資訊，請參閱 Azure Sphere 公用 API 錯誤碼一節。或者，服務定義的狀態代碼可能會傳回，如 Azure Sphere 公用 API 參考中所指定。
- 支援要求回應所需的選擇性其他標頭字段，例如 Content-Type 回應標頭。
選擇性的 HTTP 回應訊息主體欄位：
- MIME 編碼的回應物件可能會在 HTTP 回應本文中傳回，例如來自傳回數據的 GET 方法的回應。這些物件一律會以結構化 JSON 格式傳回，如 Content-Type 回應標頭所指示。

要求的驗證

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

應用程式類型	描述	範例	驗證機制
互動式用戶端	以 GUI 為基礎的用戶端應用程式	Windows 應用程式列舉裝置	Microsoft 驗證程式庫 (MSAL)
互動式 JavaScript	以 GUI 為基礎的 JavaScript 應用程式	AngularJS 單頁應用程式，顯示裝置群組的部署。	MSAL (部分機器翻譯)
互動式 Web	以 GUI 為基礎的 Web 應用程式	顯示組建摘要的自定義 Web 儀錶板	OAuth 2

注意

Azure Active Directory 平臺正在演變成 Microsoft身分識別平臺。如需詳細資訊，請參閱 Azure Sphere 的新功能。

驗證連結庫值

如果您呼叫 Microsoft 驗證連結庫（MSAL）來取得要用於驗證的持有人令牌，則必須提供四個值：

Azure Sphere 用戶端應用程式識別碼： 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F （成功驗證的必要專案）
使用者的範圍： https://sphere.azure.net/api/user_impersonation
Azure Sphere 租使用者標識符： 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
Azure Sphere API 端點： https://prod.core.sphere.azure.net/

如需驗證的詳細資訊，請參閱 Microsoft驗證連結庫（MSAL）和驗證流程。

發出要求

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

下列 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 Sphere 公用 API 錯誤碼

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

400 - 不正確的要求
404 - Not Found
409 - 衝突
410 - 消失
429 - 要求太多
500 - 內部伺服器錯誤

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

錯誤處理指引

4xx錯誤： 格式不正確的要求可能會導致錯誤。檢查您的要求語法和所傳遞的數據。

429 錯誤： 為了保護 Azure Sphere 服務免於分散式阻斷服務（DDoS）攻擊，我們會追蹤並節流對服務進行大量呼叫的裝置、使用者或租使用者。 429 錯誤訊息表示裝置、使用者或租用戶嘗試在短時間內呼叫 Azure Sphere 服務太多次。請稍候再呼叫 Azure Sphere 服務。

500 錯誤： 偶爾會發生暫時性伺服器錯誤。如果您收到伺服器錯誤，請重試要求幾次，以查看錯誤是否消失。

CORS 支援

此版本不支援跨區域原始來源共用（CORS）。

共用方式為

Azure Sphere 公用 API 概觀

REST API 要求的元件

REST API 回應的元件

要求的驗證

驗證連結庫值

發出要求

接收回應

Azure Sphere 公用 API 錯誤碼

錯誤處理指引

CORS 支援

意見反應

其他資源

共用方式為

Azure Sphere 公用 API 概觀

REST API 要求的元件

REST API 回應的元件

要求的驗證

驗證連結庫值

發出要求

接收回應

Azure Sphere 公用 API 錯誤碼

錯誤處理指引

CORS 支援

相關內容

意見反應

其他資源