Azure Sphere パブリック API の概要

[アーティクル]
08/09/2023

Azure Sphere パブリック API は、テナント、製品、デプロイ、デバイスグループなどの Azure Sphere リソースを作成および管理するための HTTP 操作をサポートする一連のサービスエンドポイントです。 Azure Sphere パブリック API は、REST (REpresentational State Transfer) HTTP プロトコルを使用して、操作の要求と応答を送信します。操作応答で返されるデータは JSON (JavaScript オブジェクト表記) で書式設定されます。使用可能な操作については、「 Azure Sphere パブリック API リファレンス」を参照してください。

お客様は、リソース管理タスクを実行するために、パブリック API の代わりに Azure Sphere コマンドラインインターフェイス (CLI) を使用することをお勧めします。 CLI は、パブリック API のプログラムによる複雑さの大部分を抽象化することで、操作の要求と応答の送受信を簡素化します。 CLI コマンドでは、Azure Sphere パブリック API を使用してタスクを実行しますが、CLI コマンドの単純な構文を使用すると、使用がはるかに簡単になります。

一部のお客様は、リソース管理タスクを実行するために独自のユーザーインターフェイス (UI) を構築したい場合があります。 Azure Sphere パブリック API を使用して、カスタム UI を構築できます。 Azure Sphere CLI を使用してカスタム UI を構築することはできません。

REST API 要求のコンポーネント

REST API 要求には、次の 3 つのコンポーネントがあります。

要求 URI を次の形式で指定します。

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

パラメーター：
- collection: 1 つ以上のコレクション。複数の入れ子になったコレクションがサポートされているため、相対パスには /collection/id/collection/id ..を含めることができます。
  
  例： /v2/tenants/{tenantId}/devices/{deviceId}/images
- resourceId: コレクション内の特定のリソースへのアクセスを可能にする、特定のリソースの ID。
  
  例： /v2/tenants/{tenantId}/devicegroups/{devicegroupid}
- version: API のバージョンを識別する API バージョン。 API の進化に伴ってアプリまたはサービスが中断されないように、すべての API 要求に API バージョンを含める必要があります。
  
  例： /v2
HTTP 要求メッセージヘッダーフィールド:
- 要求する操作の種類をサービスに伝える必要な HTTP メソッド (操作または動詞とも呼ばれます)。
- 指定された URI および HTTP メソッドで必要に応じて、追加のヘッダーフィールド。具体的には、要求のクライアント承認トークンを含むベアラートークンを提供する承認ヘッダーです。
URI および HTTP 操作をサポートするためのオプションの HTTP 要求メッセージ本文フィールド。
- HTTP POST または PUT 操作の場合、本文は Content-Type 要求ヘッダーと application/json で指定する必要があります。

REST API 応答のコンポーネント

REST API 応答には、次の 2 つのコンポーネントがあります。

HTTP 応答メッセージヘッダーフィールド:
- HTTP 状態コード。成功した呼び出しは 2xx コードを返します。4xx コードと 5xx コードはエラー状態です。詳細については、「 Azure Sphere パブリック API エラーコード」セクションを参照してください。または、 Azure Sphere パブリック API リファレンスで指定されているように、サービス定義の状態コードが返される場合があります。
- 要求への応答をサポートするために必要なオプションの追加ヘッダーフィールド (Content-Type 応答ヘッダーなど)。
オプションの HTTP 応答メッセージ本文フィールド:
- MIME でエンコードされた応答オブジェクトは、データを返す GET メソッドからの応答など、HTTP 応答本文で返される場合があります。これらのオブジェクトは、Content-Type 応答ヘッダーで示されているように、常に構造化された JSON 形式で返されます。

要求の認証

有効な要求を行う前に、アプリケーションまたはサービスを Azure Sphere パブリック API で認証する必要があります。次の表に、認証方法をいくつか示します。

アプリケーションの種類	説明	例	認証メカニズム
対話型クライアント側	GUI ベースのクライアント側アプリケーション	デバイスを列挙する Windows アプリ	Microsoft Authentication Library (MSAL)
対話型 JavaScript	GUI ベースの JavaScript アプリケーション	デバイスグループのデプロイを表示する AngularJS シングルページアプリ。	MSAL
対話型 Web	GUI ベースの Web アプリケーション	ビルドの概要を表示するカスタム Web ダッシュボード	OAuth 2

メモ

Azure Active Directory プラットフォームは、Microsoft Identity プラットフォームに進化しています。詳細については、「 Azure Sphere の新機能」を参照してください。

認証ライブラリの値

認証に使用するベアラートークンを取得するために Microsoft 認証ライブラリ (MSAL) を呼び出す場合は、次の 4 つの値を指定する必要があります。

Azure Sphere クライアントアプリケーション ID: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (認証を成功させるために必要)
ユーザーのスコープ: https://sphere.azure.net/api/user_impersonation
Azure Sphere テナント ID: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
Azure Sphere API エンドポイント: https://prod.core.sphere.azure.net/

認証の詳細については、 Microsoft Authentication Library (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 - 見つかりません
409 - 競合
410 - Gone
429 - 要求が多すぎます
500 - 内部サーバーエラー

エラーを処理するためのガイダンスは、次のセクションで提供されます。特定のエラーコードの詳細については、 RFC 7231 を参照してください。

エラー処理ガイダンス

4xx エラー: 形式が正しくない要求では、エラーが発生する可能性があります。要求の構文と渡されるデータを確認します。

429 エラー: 分散型サービス拒否 (DDoS) 攻撃から Azure Sphere サービスを保護するために、サービスを大量に呼び出すデバイス、ユーザー、またはテナントを追跡および調整します。 429 エラーメッセージは、デバイス、ユーザー、またはテナントが短時間で Azure Sphere サービスを何度も呼び出そうとしたことを示します。 Azure Sphere サービスを再度呼び出す前にお待ちください。

500 エラー: 一時的なサーバーエラーが発生することがあります。サーバーエラーが発生した場合は、要求を数回再試行して、エラーが消えたかどうかを確認します。

CORS のサポート

リージョン間配信元共有 (CORS) は、このリリースではサポートされていません。