チュートリアル:要求トレースを使用して API をデバッグする

[アーティクル]
05/10/2024

適用対象: Consumption | Developer | Basic | Standard | Premium

このチュートリアルでは、Azure API Management で要求処理を検査 (トレース) する方法について説明します。トレースは、API のデバッグとトラブルシューティングに役立ちます。

このチュートリアルでは、次の作業を行う方法について説明します。

テストコンソールで呼び出しの例をトレースする
要求プロセスのステップを確認する
API のトレースを有効にする

Note

現時点では、API 要求のトレースは Basic v2 および Standard v2 レベルではサポートされていません。

前提条件

Azure API Management の用語について学習します。
次のクイックスタートを完了すること:Azure API Management インスタンスを作成する。
次のチュートリアルを完了すること: 最初の API のインポートと発行。

重要

要求で Ocp-Apim-Trace ヘッダーを設定し、応答で Ocp-Apim-Trace-Location ヘッダーの値を使用してトレースを取得することによって API Management 要求トレースを有効にすることはできなくなりました。
セキュリティを強化するために、API Management REST API を使用して時間制限付きトークンを取得し、要求内でそのトークンをゲートウェイに渡すことで、個々の API レベルでトレースを有効にできるようになりました。詳細については、このチュートリアルで後述します。
トレースを有効にするときは、トレースデータ内の機密情報が公開される可能性があるため、注意してください。トレースデータを保護するための適切なセキュリティ対策が整っていることを確認します。

ポータルで呼び出しをトレースする

Azure portal にサインインし、API Management インスタンスに移動します。
[API] を選択します。
API の一覧で [Demo Conference API](デモ会議 API) を選択します。
[テスト] タブを選びます。
[GetSpeakers] 操作を選択します。
必要に応じて、"目" アイコンを選択して、要求で使用される Ocp-Apim-Subscription-Key ヘッダーの値を確認します。

ヒント

ポータルで別のサブスクリプションのキーを取得することで、Ocp-Apim-Subscription-Key の値をオーバーライドできます。 [サブスクリプション] を選択し、別のサブスクリプションのコンテキストメニュー (...) を開きます。 [キーの表示/非表示] を選択し、いずれかのキーをコピーします。必要に応じて、キーを再生成することもできます。次に、テストコンソールで [ヘッダーの追加] を選択し、新しいキー値を含む Ocp-Apim-Subscription-Key ヘッダーを追加します。
[トレース] を選択します。

トレース情報を確認する

呼び出しが完了したら、[HTTP 応答] の [トレース] タブに移動します。
詳細なトレース情報に移動するには、リンク ([受信]、[バックエンド]、[送信]、[エラー時]) を選択します。
- [受信] - API Management が呼び出し元から受信した元の要求と、その要求に適用されているポリシーが表示されます。たとえば、「チュートリアル: API を変換および保護する」のポリシーを追加した場合、ここに表示されます。
- [バックエンド] - API Management が API バックエンドに送信した要求と、受信した応答が表示されます。
- [送信] - 呼び出し元に送り返される前に応答に適用されるポリシーが表示されます。
- [エラー時] - 要求の処理中に発生したエラーと、エラーに適用されたポリシーが表示されます。
ヒント

各ステップには、API Management が要求を受信してからの経過時間も表示されます。

API のトレースを有効にする

API Management に対する要求を行う場合は、curl、REST クライアント拡張機能を含む Visual Studio Code などの REST クライアント、またはクライアントアプリを使用して、API のトレースを有効にすることができます。

API Management REST API の呼び出しを使用して、次の手順でトレースを有効にします。

Note

次の手順には、API Management REST API バージョン 2023-05-01-preview 以降が必要です。 REST API を呼び出すには、API Management インスタンスに対する共同作成者以上のロールが自分に割り当てられている必要があります。

List debug credentials API を呼び出してトレース資格情報を取得します。 URI でゲートウェイ ID を渡すか、クラウド内のインスタンスのマネージドゲートウェイの場合は "managed" を使用します。たとえば、マネージドゲートウェイのトレース資格情報を取得するには、次のような呼び出しを使用します。
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
```
要求本文で、トレースする API の完全なリソース ID を渡し、次のように purposes を tracing と指定します。既定では、応答で返されたトークン資格情報は 1 時間後に期限切れになりますが、ペイロードに別の値を指定できます。
```
{
    "credentialsExpireAfter": PT1H,
    "apiId": "<API resource ID>",
    "purposes: ["tracing"]
}
```
トークン資格情報は、応答で次のように返されます。
```
{
      "token": "aid=api-name&p=tracing&ex=......."
}
```
API Management ゲートウェイへの要求のトレースを有効にするには、Apim-Debug-Authorization ヘッダーでトークン値を送信します。たとえば、demo conference API の呼び出しをトレースするには、次のような呼び出しを使用します。
```
curl -v GET https://apim-hello-world.azure-api.net/conference/speakers HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&p=tracing&ex=......."
```
トークンに応じて、応答にはさまざまなヘッダーが含まれます。
- トークンが有効な場合、応答には、値がトレース ID である Apim-Trace-Id ヘッダーが含まれます。
- トークンの有効期限が切れている場合、応答には、有効期限に関する情報を含む Apim-Debug-Authorization-Expired ヘッダーが含まれます。
- 間違った API のトークンが取得された場合、応答にはエラーメッセージを含む Apim-Debug-Authorization-WrongAPI ヘッダーが含まれます。
トレースを取得するには、前の手順で取得したトレース ID をゲートウェイの List trace API に渡します。たとえば、マネージドゲートウェイのトレースを取得するには、次のような呼び出しを使用します。
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
```
要求本文で、前の手順で取得したトレース ID を渡します。
```
{
    "traceId": "<trace ID>"
}
```
応答本文には、ゲートウェイに対する前の API 要求のトレースデータが含まれます。このトレースは、ポータルのテストコンソールで呼び出しをトレースすることで確認できるトレースに似ています。

トレース情報のカスタマイズについては、トレースポリシーを参照してください。

次のステップ

このチュートリアルでは、以下の内容を学習しました。

呼び出しの例をトレースする
要求プロセスのステップを確認する
API のトレースを有効にする

次のチュートリアルに進みます。

リビジョンの使用