Azure Sphere パブリック API の概要

[アーティクル]
09/27/2024

重要

これは Azure Sphere (レガシ) のドキュメントです。 Azure Sphere (レガシ) は 2027 年 9 月 27 日に再提供されておりユーザーは現時点で Azure Sphere (統合) に移行する必要があります。 TOC の上にある Version セレクターを使用して、Azure Sphere (統合) のドキュメントを表示します。

Azure Sphere パブリック API は、テナント、製品、デプロイ、デバイスグループなどの Azure Sphere リソースを作成および管理するための HTTP 操作をサポートする一連のサービスエンドポイントです。 Azure Sphere パブリック API は、REST (REpresentational State Transfer) HTTP プロトコルを使用して操作の要求と応答を送信します。操作応答で返されるデータは JSON (JavaScript Object Notation) で書式設定されます。使用可能な操作については、 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

Note

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

認証ライブラリの値

認証に使用するベアラートークンを取得するために Microsoft Authentication Libraries (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) と Authentication フローを参照してください。

要求を行う

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) はサポートされていません。

次の方法で共有

Azure Sphere パブリック API の概要

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

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

要求の認証

認証ライブラリの値

要求を行う

応答を受信する

Azure Sphere パブリック API のエラーコード

エラー処理ガイダンス

CORS サポート

フィードバック

その他のリソース

次の方法で共有

Azure Sphere パブリック API の概要

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

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

要求の認証

認証ライブラリの値

要求を行う

応答を受信する

Azure Sphere パブリック API のエラー コード

エラー処理ガイダンス

CORS サポート

関連コンテンツ

フィードバック

その他のリソース

Azure Sphere パブリック API のエラーコード