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

[アーティクル]
03/03/2025

適用対象: すべての API Management レベル

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

ヒント

API チームは、ワークスペースでこの機能を使用できます。ワークスペースは、API と独自の API ランタイム環境への分離された管理アクセスを提供します。

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

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

前提条件

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

重要

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

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

ポータルのテストコンソールで API 要求をトレースするには、次の手順に従います。この例は、前のチュートリアルでサンプル API をインポートしたことを前提としています。インポートした別の API で同様の手順に従うことができます。

Azure portal にサインインし、API Management インスタンスに移動します。
[API]>[API] を選択します。
API の一覧から [Petstore API] を選択します。
[テスト] タブを選びます。
Find pet by ID 操作を選択します。
[petId][クエリパラメーター] で、「1」と入力します。
必要に応じて、"目" アイコンを選択して、要求で使用される Ocp-Apim-Subscription-Key ヘッダーの値を確認します。

ヒント

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

トレース情報を確認する

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

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

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

curl、REST クライアント拡張機能を含む Visual Studio Code などの REST クライアント、またはクライアントアプリを使用する場合に、API Management に対する要求のトレースを有効にするには、次の大まかな手順が必要です。現在、これらの手順は、API Management REST API を使用して実行する必要があります。

トレース用のデバッグトークンを取得します。
Apim-Debug-Authorization 要求ヘッダーのトークン値を API Management ゲートウェイに追加します。
Apim-Trace-Id 応答ヘッダーでトレース ID を取得します。
トレース ID に対応するトレースを取得します。

詳細な手順は次のとおりです。

Note

次の手順には、API Management REST API バージョン 2023-05-01-preview 以降が必要です。 REST API を呼び出すには、API Management インスタンスに対する共同作成者以上のロールが自分に割り当てられている必要があります。
REST API への認証の詳細については、Azure REST API リファレンスを参照してください。

デバッグトークンを取得する - API Management ゲートウェイの List debug credentials API を呼び出します。 URI には、クラウド内のインスタンスのマネージドゲートウェイの場合は「managed」、セルフホステッドゲートウェイの場合はゲートウェイ ID を入力します。たとえば、インスタンスのマネージドゲートウェイのトレース資格情報を取得するには、次のような要求を使用します。
```
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": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
    "purposes": ["tracing"]
}
```
Note

apiId は、ポータルに表示される名前ではなく、完全なリソース ID からのみプルできます。

apiId を取得します:
```
az apim api list --resource-group <resource-group> --service-name <service-name> -o table
```
デバッグ資格情報は、応答で次のように返されます。
```
{
      "token": "aid=api-name&......."
}
```
要求ヘッダーにトークン値を追加する - API Management ゲートウェイへの要求のトレースを有効にするには、Apim-Debug-Authorization ヘッダーでトークン値を送信します。たとえば、前のチュートリアルでインポートした Petstore API の呼び出しをトレースするには、次のような要求を使用します。
```
curl -v https://apim-hello-world.azure-api.net/pet/1 HTTP/1.1 \
    -H "Ocp-Apim-Subscription-Key: <subscription-key>" \
    -H "Apim-Debug-Authorization: aid=api-name&......."
```
応答を評価する - 応答には、デバッグトークンの状態に応じて、次のいずれかのヘッダーを含めることができます。
- デバッグトークンが有効な場合、応答には、値がトレース ID である次のような Apim-Trace-Id ヘッダーが含まれます。
```
Apim-Trace-Id: 0123456789abcdef....
```
- デバッグトークンの有効期限が切れている場合、応答には、有効期限に関する情報を含む 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": "0123456789abcdef...."
}
```
応答本文には、ゲートウェイに対する前の API 要求のトレースデータが含まれます。このトレースは、ポータルのテストコンソールで呼び出しをトレースすることで確認できるトレースに似ています。

VS Code REST クライアント拡張機能の `.http` ファイルの例

Visual Studio Code REST クライアント拡張機能を使用してこれらの手順を自動化するには、次のサンプル .http ファイルを使用します。

@subscriptionId = // Your subscription ID
@resourceGroup = // Your resource group
@apimName = // Your API Management service name
@clientId = // Client ID from an app registration for authentication
@clientSecret = // Client secret from app registration
@externalHost = // The host name of the App Gateway or the fully qualified gateway URL
@subscriptionKey = // API Management subscription key
@apiEndPoint = // API URL
@requestBody = // Data to send
@tenantId = // Tenant ID
 
POST https://login.microsoftonline.com/{{tenandId}}/oauth2/token
content-type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_id={{clientId}}&client_secret={{clientSecret}}&resource=https%3A%2F%2Fmanagement.azure.com%2F
 
###
@authToken = {{login.response.body.$.access_token}}
###
# @name listDebugCredentials
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
Authorization: Bearer {{authToken}}
Content-Type: application/json
{
    "credentialsExpireAfter": "PT1H",
    "apiId": "/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/apis/{{apiId}}",
    "purposes": ["tracing"]
}
 
###
@debugToken = {{listDebugCredentials.response.body.$.token}}
 
###
# @name callApi
curl -k -H "Apim-Debug-Authorization: {{debugToken}}" -H 'Host: {{externalHost}}' -H 'Ocp-Apim-Subscription-Key: {{subscriptionKey}}' -H 'Content-Type: application/json' '{{apiEndPoint}}' -d '{{requestBody}}'
 
###
@traceId = {{callApi.response.headers.Apim-Trace-Id}}
 
###
# @name getTrace
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listTrace?api-version=2024-06-01-preview
Authorization: Bearer {{authToken}}
Content-Type: application/json
 
{
    "traceId": "{{traceId}}"
}

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

次のステップ

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

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

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

リビジョンの使用

次の方法で共有

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

前提条件

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

トレース情報を確認する

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

VS Code REST クライアント拡張機能の `.http` ファイルの例

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

前提条件

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

トレース情報を確認する

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

VS Code REST クライアント拡張機能の .http ファイルの例

次のステップ

フィードバック

その他のリソース

VS Code REST クライアント拡張機能の `.http` ファイルの例