Azure REST API リファレンス

[アーティクル]
04/01/2024

Azure REST API リファレンスドキュメントへようこそ。

Representational State Transfer (REST) API は、一連の HTTP 操作 (メソッド) をサポートするサービスエンドポイントであり、サービスのリソースに関する作成、取得、更新、削除アクセスが提供されます。この記事で説明する内容は次のとおりです。

curl を使用して Azure REST API を呼び出す方法
REST API の要求と応答のペアの基本コンポーネント。
REST 要求をセキュリティで保護するために、クライアントアプリケーションを Microsoft Entra ID に登録する方法。
REST 要求の作成と送信と応答の処理の概要。

ヒント

ほとんどの Azure サービス REST API には、Azure サービスを使用するためのネイティブインターフェイスを提供するクライアントライブラリがあります。

。ネット | Java | | Node.jsPython | 行く | C++

curl を使用して Azure REST API を呼び出す方法

次のブログ記事で説明されているプロセスは、 curl を使用して Azure REST API を呼び出す方法を示しています。無人スクリプトで curl を使用することを検討する場合があります。たとえば、DevOps 自動化シナリオの場合などです。

curl を使用した Azure REST API の呼び出し

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

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

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

クライアントアプリケーションを Microsoft Entra ID に登録する

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

統合Microsoft Entra認証を使用していない REST API を使用している場合、またはクライアントを既に登録している場合は、「要求の作成」セクションに進んでください。

前提条件

クライアントアプリケーションは、Microsoft Entra テナントに登録することで、実行時までに ID 構成をMicrosoft Entra IDに認識させる必要があります。クライアントをMicrosoft Entra IDに登録する前に、次の前提条件を考慮してください。

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

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

クライアントの登録

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

クライアントアプリケーションを Microsoft Entra ID に登録します。
クライアントが Azure Resource Manager API にアクセスできるようにアクセス許可要求を設定します。
クライアントを承認するための Azure Resource Manager Role-Based Access Control (RBAC) 設定を構成します。

クライアントが Azure Resource Manager API 以外の API にアクセスする場合は、次を参照してください。

Microsoft ID プラットフォームにアプリケーションを登録する
- [アプリケーションの登録] セクションで、クライアントアプリケーションをMicrosoft Entra IDに登録します。
- [資格情報の追加] セクションで(Web クライアントを登録している場合)、秘密鍵を作成します。
アプリケーションを構成して Web API を公開する
- Web API にアクセス許可を追加し、スコープとして公開する
Web API にアクセスするようにクライアントアプリケーションを構成する
- [Web API にアクセスするためのアクセス許可の追加] セクションで、API に定義されているスコープで必要に応じてアクセス許可要求を追加します。

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

要求を作成する

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

アクセストークンの取得

有効なクライアント登録を取得したら、アクセストークンを取得するために、Microsoft Entra IDと統合する 2 つの方法があります。

プラットフォームと言語に依存しない OAuth2 サービスエンドポイント。この記事で使用します。このセクションで説明する手順では、Microsoft Entra OAuth エンドポイントを使用する場合、クライアントのプラットフォームまたは言語/スクリプトについては何も想定しません。唯一の要件は、Microsoft Entra IDとの間で HTTPS 要求を送受信し、応答メッセージを解析できることです。
プラットフォームおよび言語固有の Microsoft 認証ライブラリ (MSAL) は、この記事の範囲外です。ライブラリは、OAuth2 エンドポイント要求の非同期ラッパーと、キャッシュや更新トークン管理などの堅牢なトークン処理機能を提供します。詳細については、 Microsoft 認証ライブラリ (MSAL) の概要に関するページを参照してください。

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

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

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

まず、クライアントはMicrosoft Entra IDから承認コードを要求する必要があります。エンドポイントへの HTTPS GET 要求 /authorize の形式と要求/応答メッセージの例の詳細については、「承認コードを要求する」を参照してください。 URI には、クライアントアプリケーションに固有の次のクエリ文字列パラメーターが含まれています。
- client_id: 登録時にクライアントアプリケーションに割り当てられた GUID (アプリケーション ID とも呼ばれます)。
- 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 ドキュメントまたはリソースアプリケーションの構成に関するページを参照してください。詳細については、Microsoft Graph API アプリケーションオブジェクトのプロパティを参照してくださいidentifierUris。
エンドポイントに対する /authorize 要求は、最初にサインインプロンプトをトリガーしてユーザーを認証します。返される応答は、で redirect_uri指定した URI へのリダイレクト (302) として配信されます。応答ヘッダーメッセージには location 、リダイレクト URI とそれに続くクエリパラメーターを含むフィールドが code 含まれています。パラメーターには code 、手順 2 で必要な承認コードが含まれています。
次に、クライアントがアクセストークンの承認コードを引き換える必要があります。エンドポイントへの HTTPS POST 要求の形式と要求/応答の /token 例の詳細については、「アクセストークンの要求」を参照してください。これは POST 要求であるため、アプリケーション固有のパラメーターを要求本文にパッケージ化します。前述のパラメーターの一部 (他の新しいパラメーターと共に) に加えて、次のパラメーターを渡します。
- code: このクエリパラメーターには、手順 1 で取得した承認コードが含まれています。
- client_secret: このパラメーターは、クライアントが Web アプリケーションとして構成されている場合にのみ必要です。これは、クライアント登録で前に生成したのと同じシークレット/キー値です。

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

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

この許可のクライアントとリソースの相互作用は、承認コード付与の手順 2 と似ています。エンドポイントに対する /token HTTPS POST 要求の形式と要求/応答の例の詳細については、Microsoft ID プラットフォームおよび OAuth 2.0 クライアント資格情報フローの「トークンの取得」セクションを参照してください。

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

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

要求 URI

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

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

要求ヘッダー

要求 URI は、サービスの REST API 仕様と HTTP 仕様で必要な追加フィールドと共に、要求メッセージヘッダーにバンドルされています。要求には、次の共通ヘッダーフィールドが必要な場合があります。

Authorization: Microsoft Entra IDから前に取得した要求をセキュリティで保護するための 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/.../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/...",
        "subscriptionId":"...",
        "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/.../resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

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

非同期操作、調整、ページング

この記事で説明する作成/送信/プロセス応答パターンは同期であり、すべての REST メッセージに適用されます。ただし、一部のサービスでは非同期パターンもサポートされています。これには、非同期要求を監視または完了するために応答ヘッダーの追加処理が必要です。詳細については、「Track asynchronous Azure operations (非同期の Azure 操作の追跡)」を参照してください。

Resource Managerは、アプリケーションが送信する要求が多くなりすぎないように、1 時間あたりの読み取り要求と書き込み要求の数に制限を適用します。アプリケーションがこれらの制限を超えると、要求は調整されます。応答ヘッダーには、スコープの残りの要求の数が含まれます。詳細については、「Resource Manager の要求のスロットル」を参照してください。

一部のリスト操作では、応答本文でというプロパティ nextLink が返されます。このプロパティは、結果が大きすぎて 1 つの応答で返しきれなすぎる場合に表示されます。通常、リスト操作で 1,000 個を超える項目が返される場合、応答には nextLink プロパティが含まれます。 nextLink が結果に存在しない場合、返される結果は完了です。 nextLink に URL が含まれている場合、返される結果は結果セット全体の一部に過ぎません。

応答の形式は次のとおりです。

{
  "value": [
    <returned-items>
  ],
  "nextLink": "https://management.azure.com/{operation}?api-version={version}&%24skiptoken={token}"
}

結果の次のページを取得するには、nextLink プロパティの URL に GET 要求を送信します。 URL には、結果のどこにいるかを示す継続トークンが含まれています。返された結果に URL が含まれないまで、nextLink URL に要求を送信し続けます。

Azure API の回復性

Azure REST API は、回復性と継続的可用性のために設計されています。 REST API のコントロールプレーン操作 (management.azure.com に送信される要求) は次のとおりです。

リージョン間に分散されます。一部のサービスはリージョン固有です。
複数の可用性ゾーンを含む場所では、可用性ゾーン (リージョン) 間で分散されます。
単一の論理データセンターに依存しません。
メンテナンスのために休止することはありません。

これで終了です。 Microsoft Entra アプリケーションを登録し、アクセストークンを取得し、HTTP 要求を処理するためのモジュール式の手法を使用すると、コードをレプリケートして新しい REST API を利用することが非常に簡単になります。アプリケーションの登録とMicrosoft Entraプログラミングモデルの詳細については、Microsoft ID プラットフォームドキュメントを参照してください。

HTTP 要求/応答のテストの詳細については、次を参照してください。

Fiddler。 Fiddler は、REST 要求をインターセプトできる無料の Web デバッグプロキシであり、HTTP 要求/応答メッセージの診断が容易になります。
JWT.ms。これにより、ベアラートークンに要求をすばやく簡単にダンプして、その内容を検証できます。