次の方法で共有

Azure REST API リファレンス

  • [アーティクル]

Azure REST API リファレンスへようこそ。

Representational State Transfer (REST) API は、サービスのリソースへの作成/取得/更新/削除アクセスを提供する一連の HTTP 操作 (メソッド) をサポートするサービス エンドポイントです。 以下のセクションでは、以下の手順について説明します。

  • REST API の要求と応答のペアの基本的なコンポーネント
  • REST 要求をセキュリティで保護するために、クライアント アプリケーションを Azure Active Directory (Azure AD) に登録する方法
  • REST 要求の作成と送信と応答の処理の概要

注意

ほとんどの Azure サービス REST API には、クライアント コードの大部分を処理する対応するクライアント SDK ライブラリがあります。 参照トピック

Azure .NET SDK
Azure Java SDK
Azure CLI 2.0 SDK

REST API の要求/応答のコンポーネント

REST API の要求と応答のペアは、5 つのコンポーネントに分けることができます。

  1. 要求 URI。{URI-scheme} :// {URI-host} / {resource-path} ? {query-string} で構成されます。 ほとんどの言語/フレームワークでは要求メッセージとは別に渡す必要がありますが、実際には要求メッセージ ヘッダーに含まれているので、ここではこれを個別に呼び出しています。
    • URI スキーム: 要求の送信に使用されるプロトコルを示します。 たとえば、http または https です。
    • URI ホスト: REST サービス エンドポイントがホストされているサーバーのドメイン名または IP アドレス (例: graph.microsoft.com
    • リソース パス: リソースまたはリソース コレクションを指定します。リソースの選択を決定する際にサービスによって使用される複数のセグメントを含めることができます。 たとえば、 を beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners 使用して、アプリケーション コレクション内の特定のアプリケーションの所有者の一覧に対してクエリを実行できます。
    • クエリ文字列 (省略可能): API のバージョン、リソースの選択条件など、追加の単純なパラメーターを指定するために使用されます。
  2. HTTP 要求メッセージ ヘッダー フィールド
    • 要求している操作の種類をサービスに伝える必要な HTTP メソッド (操作または動詞とも呼ばれます)。 Azure REST API では、GET、HEAD、PUT、POST、PATCH の各メソッドがサポートされています。
    • 指定した URI および HTTP メソッドで必要な追加ヘッダー フィールド (省略可能)。 たとえば、要求のクライアント承認情報を含むベアラー トークンを提供する Authorization ヘッダーです。
  3. 省略可能な HTTP 要求メッセージ本文のフィールド。URI および HTTP 操作をサポートするためのものです。 たとえば、POST 操作には、複雑なパラメーターとして渡される MIME でエンコードされたオブジェクトが含まれます。 本文の MIME エンコードの種類は、POST/PUT 操作の要求ヘッダーでも指定 Content-type する必要があります。 一部のサービスでは、 などの application/json特定の MIME の種類を使用する必要があることに注意してください。
  4. HTTP 応答メッセージ ヘッダー フィールド
    • 2xx 成功コードから 4xx/5xx エラー コードまでの HTTP 状態コード。 または、API のドキュメントに記載されているように、サービスで定義された状態コードが返されることもあります。
    • 要求の応答 (応答ヘッダーなど) をサポートするために必要なオプションの Content-type 追加ヘッダー フィールド。
  5. オプションの HTTP 応答メッセージ本文 フィールド
    • MIME でエンコードされた応答オブジェクトは、データを返す GET メソッドからの応答など、HTTP 応答本文で返される場合があります。 通常、これらは、応答ヘッダーで示されているように、JSON または XML として構造化形式で Content-type 返されます。 たとえば、Azure AD からアクセス トークンを要求すると、応答本文で要素として access_token 返されます。これは、データ コレクション内のいくつかの名前と値のペアのオブジェクトのいずれかです。 この例では、 の Content-Type: application/json 応答ヘッダーも含まれます。

Azure AD にクライアント アプリケーションを登録する

ほとんどの Azure サービス (Azure Resource Manager プロバイダーや従来の Service Management API など) では、サービスの API を呼び出す前に、有効な資格情報で認証するクライアント コードが必要です。 認証は、認証/承認の証明としてクライアントに アクセス トークン を提供する Azure AD によってさまざまなアクター間で調整されます。 その後、トークンは、後続のすべての REST API 要求の HTTP 承認ヘッダーで Azure サービスに送信されます。 トークンの 要求 はサービスに情報を提供し、クライアントを検証し、必要な承認を実行できるようにします。

統合 Azure AD 認証を使用していない REST API を使用している場合、またはクライアントを既に登録している場合は、「 要求の作成 」セクションに進むことができます。

前提条件

クライアント アプリケーションは、Azure AD テナントに登録することで、実行時前に Id 構成を Azure AD に認識させる必要があります。 クライアントを Azure AD に登録する前に考慮する必要がある項目の一覧を次に示します。

  • Azure AD テナントがまだない場合は、「Azure Active Directory テナントを取得する方法」を参照してください。
  • OAuth2 承認フレームワークに従って、Azure AD では 2 種類のクライアントがサポートされます。 それぞれの理解は、シナリオに最も適した方法を決定するのに役立ちます。
    • Web/機密 クライアント (Web サーバー上で実行) は、独自の ID (サービス/デーモン) でリソースにアクセスすることも、サインインしているユーザーの ID (つまり Web アプリ) の下でリソースにアクセスするための委任された承認を取得することもできます。 アクセス トークンを取得するために、Azure AD 認証中に独自の資格情報を安全に維持して提示できるのは、Web クライアントのみです。
    • ネイティブ/パブリック クライアント (デバイスにインストールまたは実行) は、サインインしているユーザーの ID を使用してユーザーに代わってアクセス トークンを取得し、委任された承認の下でのみリソースにアクセスできます。
  • 登録プロセスでは、アプリケーションが登録されている Azure AD テナントに 2 つの関連オブジェクト (アプリケーション オブジェクトとサービス プリンシパル オブジェクト) が作成されます。 これらのコンポーネントの背景と実行時の使用方法の詳細については、「 Azure Active Directory のアプリケーション およびサービス プリンシパル オブジェクト」を参照してください。

これで、クライアント アプリケーションを Azure AD に登録する準備ができました。

クライアントの登録

Azure Resource Manager REST API にアクセスするクライアントを登録するには、「ポータルを使用して、リソースにアクセスできる Active Directory アプリケーションとサービス プリンシパルを作成する」を参照してください。 この記事 (登録を自動化するために PowerShell と CLI のバージョンでも利用可能) では、次の方法について説明します。

  • クライアント アプリケーションを Azure AD に登録する
  • クライアントが Azure Resource Manager API にアクセスできるようにアクセス許可要求を設定する
  • クライアントを承認するための Azure Resource Manager のロール ベースのAccess Control (RBAC) 設定を構成する

その他のすべてのクライアントについては、「 アプリケーションと Azure Active Directory の統合」を参照してください。 この記事では、次の操作方法について説明します。

  • [アプリケーションの追加] セクションで、クライアント アプリケーションを Azure AD に登録する
  • (Web クライアントを登録している場合)、"アプリケーションの更新" セクションで秘密キーを作成する
  • [アプリケーションの更新] セクションで、API で必要に応じてアクセス許可要求を追加する

クライアント アプリケーションの登録が完了したので、クライアント コードに移動できます。ここで、REST 要求を作成して応答を処理します。

要求を作成する

このセクションでは、前に説明した 5 つのコンポーネントの最初の 3 つについて説明します。 まず、要求メッセージ ヘッダーのアセンブルに使用する Azure AD からアクセス トークンを取得する必要があります。

アクセス トークンの取得

有効なクライアント登録を取得すると、基本的に 2 つの方法で Azure AD と統合してアクセス トークンを取得できます。

  • Azure AD のプラットフォーム/言語に依存しない OAuth2 サービス エンドポイント。これが使用されます。 使用している Azure REST API エンドポイントと同様に、このセクションで説明する手順では、Azure AD エンドポイントを使用する場合、クライアントのプラットフォームまたは言語/スクリプトに関する前提条件は行われません。Azure AD との間で HTTPS 要求を送受信し、応答メッセージを解析できるだけです。
  • プラットフォーム/言語固有の Microsoft 認証ライブラリ (MSAL)。 ライブラリは、OAuth2 エンドポイント要求の非同期ラッパーと、キャッシュや更新トークン管理などの堅牢なトークン処理機能を提供します。 リファレンス ドキュメント、ライブラリのダウンロード、サンプル コードなど、詳細については、「 Microsoft 認証ライブラリ」を参照してください。

クライアントの認証とアクセス トークンの取得に使用する 2 つの Azure AD エンドポイントは、OAuth2 /authorize とエンドポイントと /token 呼ばれます。 使用方法は、アプリケーションの登録と、実行時にアプリケーションをサポートするために必要な OAuth2 承認許可フロー の種類によって異なります。 この記事では、クライアントが承認コードまたはクライアント資格情報のいずれかの承認許可フローを使用することを前提としています。 シナリオに最も適した手順に従って、残りのセクションで使用するアクセス トークンを取得します。

承認コードの付与 (対話型クライアント)

この許可は、Web クライアントとネイティブ クライアントの両方で使用できます。クライアント アプリケーションにリソース アクセスを委任するには、サインインしているユーザーからの資格情報が必要です。 エンドポイントを /authorize 使用して(ユーザーのサインイン/同意に応じて) 承認コードを取得し、その後エンドポイントで /token アクセス トークンの承認コードを交換します。

  1. 最初に、クライアントは Azure AD に承認コードを要求する必要があります。 エンドポイントへの HTTPS GET 要求の形式と要求/応答メッセージの例については、「 承認コード を /authorize 要求する」を参照してください。 URI には、クライアント アプリケーションに固有の次のようなクエリ文字列パラメーターが含まれます。

    • client_id - これはアプリケーション ID とも呼ばれ、上記のセクションに登録したときにクライアント アプリケーションに割り当てられた GUID です

    • redirect_uri - クライアント アプリケーションの登録中に指定された [いずれかの] 応答/リダイレクト URI の URL エンコードバージョン。 渡す値は、登録と正確に一致している必要があることに注意してください。

    • resource - 呼び出している REST API によって指定された URL エンコード識別子 URI。 Web/REST API (リソース アプリケーションとも呼ばれます) は、構成で 1 つ以上のアプリケーション ID URI を公開できます。 次に例を示します。

      • Azure Resource Manager プロバイダー (および従来のサービス管理) API では、https://management.core.windows.net/
      • その他のリソースについては、Azure portalの API ドキュメントまたはリソース アプリケーションの構成を参照してください。 詳細については、identifierUrisAzure AD アプリケーション オブジェクトの プロパティも参照してください。

    エンドポイントに対する /authorize 要求によって、最初にサインイン プロンプトがトリガーされ、エンド ユーザーが認証されます。 返される応答は、 で redirect_uri指定した URI へのリダイレクト (302) として配信されます。 応答ヘッダー メッセージにはフィールドが含 location まれます。このフィールドには、リダイレクト URI の後にクエリ パラメーターが続き code 、手順 2 に必要な承認コードが含まれます。

  2. 次に、クライアントはアクセス トークンの認証コードを引き換える必要があります。 エンドポイントへの HTTPS POST 要求の形式と要求/応答メッセージの例の詳細については、「 認証コードを使用してアクセス トークン を要求する /token 」を参照してください。 これは POST 要求であるため、今回はアプリケーション固有のパラメーターを要求本文にパッケージ化します。 (他の新しいものと共に) 上記のいくつかに加えて、 を渡します。

    • code - これは、手順 1 で取得した承認コードを含むクエリ パラメーターです。
    • client_secret - このパラメーターは、クライアントが Web アプリケーションとして構成されている場合にのみ必要です。 これは、 クライアント登録で前に生成したのと同じシークレット/キー値です。

クライアント資格情報の付与 (非対話型クライアント)

この許可は Web クライアントのみが使用でき、アプリケーションは、登録時に提供されるクライアント独自の資格情報を使用してリソースに直接アクセスできます (ユーザー委任なし)。 これは通常、デーモン/サービスとして実行されている非対話型クライアント (UI なし) によって使用され、アクセス トークンを /token 取得するためにエンドポイントのみが必要です。

この許可のクライアントとリソースの相互作用は、承認コード付与の手順 2 とよく似ています。 エンドポイントへの HTTPS POST 要求の形式と要求/応答メッセージの例の詳細については、「 クライアント資格情報を使用したサービス間呼び出し 」の「アクセス トークンの要求」セクションを /token 参照してください。

要求メッセージをアセンブルする

ほとんどのプログラミング言語/フレームワークとスクリプト環境では、要求メッセージを簡単に組み立てて送信できます。 通常、要求の作成/書式設定を抽象化する Web/HTTP クラスまたは API が提供されるため、クライアント コード (たとえば、.NET Frameworkの HttpWebRequest クラス) を簡単に記述できます。 簡潔にするために、要求の重要な要素のみを取り上げる予定です。そのほとんどはユーザーに代わりに処理されます。

要求 URI

すべてのセキュリティで保護された REST 要求には、URI スキームの HTTPS プロトコルが必要です。機密情報が送受信されるという事実により、要求と応答にセキュリティで保護されたチャネルが提供されます。 この情報 (つまり、Azure AD 承認コード、アクセス/ベアラー トークン、機密性の高い要求/応答データ) は、メッセージのプライバシーを確保するために、下位トランスポート層によって暗号化されます。

サービスの要求 URI の残りの部分 (ホスト、リソース パス、および必要なクエリ文字列パラメーター) は、関連する REST API 仕様によって決定されます。 たとえば、Azure Resource Manager プロバイダー API では を使用https://management.azure.com/し、従来の Azure Service Management API では を使用https://management.core.windows.net/します。どちらもクエリ文字列パラメーターを必要api-versionとします。

要求ヘッダー

要求 URI は、サービスの REST API 仕様と HTTP 仕様によって決定される追加フィールドと共に、要求メッセージ ヘッダーにバンドルされます。 要求で必要になる可能性がある一般的なヘッダー フィールドを次に示します。

  • Authorization: Azure AD から前に取得したように、要求をセキュリティで保護するための OAuth2 ベアラー トークンが含まれています
  • Content-Type: 通常は "application/json" (JSON 形式の名前と値のペア) に設定され、要求本文の MIME の種類を指定します。
  • Host: これは、REST サービス エンドポイントがホストされているサーバーのドメイン名または IP アドレスです

要求本文

前述のように、要求する特定の操作とそのパラメーター要件に応じて、要求メッセージ本文は省略可能です。 必要に応じて、要求するサービスの API 仕様でエンコードと形式も指定されます。

要求本文はヘッダーから空の行で区切られます。ヘッダー フィールドごとに書式設定する Content-Type 必要があります。 "application/json" 形式の本文の例を次に示します。

{
  "<name>": "<value>"
}

要求を送信する

サービスの要求 URI を取得し、関連する要求メッセージヘッダー/本文を作成したら、REST サービス エンドポイントに要求を送信する準備ができました。

たとえば、Azure Resource Manager プロバイダーの HTTPS GET 要求メソッドは、次のような要求ヘッダー フィールドを使用して送信される場合がありますが、要求本文が空であることに注意してください。

GET /subscriptions?api-version=2014-04-01-preview HTTP/1.1
Authorization: Bearer <bearer-token>
Host: management.azure.com

<no body>

また、Azure Resource Manager プロバイダーの HTTPS PUT 要求メソッドは、次のような要求ヘッダーと本文フィールドを使用して送信される場合があります。

PUT /subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourcegroups/ExampleResourceGroup?api-version=2016-02-01  HTTP/1.1
Authorization: Bearer <bearer-token>
Content-Length: 29
Content-Type: application/json
Host: management.azure.com

{
  "location": "West US"
}

要求を行うと、応答メッセージ ヘッダーとオプションの本文が返されます。

応答メッセージの処理

次に、5 つのコンポーネントのうち最後の 2 つを終了します。

応答を処理するには、応答ヘッダーと(要求に応じて) 必要に応じて応答本文を解析する必要があります。 上記の HTTPS GET の例では、/subscriptions エンドポイントを使用して、ユーザーのサブスクリプションの一覧を取得しました。 応答が成功したと仮定すると、次のような応答ヘッダー フィールドを受け取る必要があります。

HTTP/1.1 200 OK
Content-Length: 303
Content-Type: application/json;

と 応答本文。次のような JSON 形式でエンコードされた Azure サブスクリプションとその個々のプロパティの一覧が含まれます。

{
    "value":[
        {
        "id":"/subscriptions/04f09293-ce69-583a-a091-z06ea46dfb8c",
        "subscriptionId":"04f09293-ce69-583a-a091-z06ea46dfb8c",
        "displayName":"My Azure Subscription",
        "state":"Enabled",
        "subscriptionPolicies":{
            "locationPlacementId":"Public_2015-09-01",
            "quotaId":"MSDN_2014-05-01",
            "spendingLimit":"On"}
        }
    ]
}

同様に、HTTPS PUT の例では、次のような応答ヘッダーを受け取り、"ExampleResourceGroup" を追加する PUT 操作が成功したことを確認する必要があります。

HTTP/1.1 200 OK
Content-Length: 193
Content-Type: application/json;

と 応答本文。次のような JSON 形式でエンコードされた新しく追加されたリソース グループの内容を確認します。

{
    "id":"/subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

要求と同様に、ほとんどのプログラミング言語/フレームワークでは、応答メッセージを簡単に処理できます。 通常、この情報は要求に従ってアプリケーションに返され、型指定された/構造化された形式で処理できます。 主に、応答ヘッダーで HTTP 状態コードを確認し、成功した場合は API 仕様 (または および 応答ヘッダー フィールド) に従って応答本文をContent-TypeContent-Length解析することに関心があります。

これで完了です。 Azure AD アプリケーションを登録し、アクセス トークンを取得し、HTTP 要求を作成および処理するためのコンポーネント化された手法を使用すると、コードをレプリケートして新しい REST API を利用するのが非常に簡単になります。

関連コンテンツ

  • アプリケーションの登録と Azure AD プログラミング モデルの詳細については、「Microsoft ID プラットフォーム (開発者向け Azure Active Directory)」を参照してください。これには、HowTo と QuickStart に関する記事の包括的なインデックス、サンプル コードが含まれます。
  • HTTP 要求/応答をテストする場合は、チェックアウトします
    • Fiddler。 Fiddler は、REST 要求をインターセプトできる無料の Web デバッグ プロキシであり、HTTP 要求と応答メッセージを簡単に診断できます。
    • JWT デコーダー と JWT.io。これにより、ベアラー トークンに要求をすばやく簡単にダンプできるため、その内容を検証できます。

この記事に続く LiveFyre コメント セクションを使用して、フィードバックを提供し、コンテンツの調整と整形に役立ててください。