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 テナントに登録することで、実行時前に Azure AD に ID 構成を認識させる必要があります。 クライアントを Azure AD に登録する前に考慮する必要がある項目の一覧を次に示します。

  • Azure AD テナントがまだない場合は、「Azure Active Directory テナントを取得する方法」を参照してください。
  • OAuth2 承認フレームワークごとに、Azure AD は 2 種類のクライアントをサポートします。 それぞれについて理解することは、シナリオに最も適したシナリオを決定するのに役立ちます。
    • Web/Confidential クライアント (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_uriURI へのリダイレクト (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;

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

{
    "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 とクイック スタートに関する記事の包括的なインデックス、サンプル コードが含まれます。
  • HTTP 要求/応答をテストする場合は、〘
    • Fiddler。 Fiddler は、REST 要求をインターセプトして HTTP 要求と応答メッセージを簡単に診断できる無料の Web デバッグ プロキシです。
    • JWT デコーダーJWT.io。ベアラー トークンに要求をすばやく簡単にダンプして、その内容を検証できるようにします。

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