APIデバッグ機能を使用して問題をトラブルシューティングする方法 - API Gateway

API Gatewayでは、公開されたAPIをオンラインでデバッグできます。このトピックでは、APIデバッグ中に発生する問題をトラブルシューティングする方法について説明します。

1. 概要

API Gatewayコンソールでは、公開されたAPIをデバッグできます。デバッグプロセス中に問題が発生した場合は、エラー情報に基づいて問題を見つけて解決できます。このトピックでは、API Gatewayコンソールが提供するAPIデバッグ機能を使用して、その方法について説明します。

説明

APIデバッグ機能は、署名認証、簡易認証 (AppCode) 、および基本認証プラグイン (BasicAuthプラグイン) 認証の3つの認証方法をサポートしています。
APIデバッグ機能は、マルチパートおよびフォームデータをサポートします。デバッグページでファイルをアップロードできます。
デバッグページで使用されるリクエストパケットの最大サイズは512 KBです。リクエストパケットのサイズが512 KBを超える場合は、デバッグにSDKを使用することを推奨します。
インスタンスで構成するブラックリスト、ホワイトリスト、またはIPアドレスベースのスロットリングプラグインは、デバッグに使用するIPアドレスを許可する必要があります。 IPアドレスは、APIデバッグページの左下隅から取得できます。

2. エラー情報の取得

API Gatewayは、受信したリクエストごとにレスポンスを返します。レスポンスのヘッダーからAPI Gatewayから返された情報を表示できます。 X-Caで始まる属性は、API Gatewayによって返されます。次の情報に集中することを推奨します。

X-Ca-Error-Code: システムエラーコード。リクエストにエラーがあり、API Gatewayによって拒否された場合、この属性が返されます。
X-Ca-Request-Id: リクエストの一意のID。 API Gatewayがリクエストを受信すると、リクエストIDを生成し、X-Ca-request-IDヘッダーでリクエストIdを返します。トラブルシューティングとトレースの目的で、クライアントとバックエンドサービスの両方にリクエストIDを記録することを推奨します。
X-Ca-Error-Message: API Gatewayによって返されるエラーメッセージ。リクエストが失敗した場合、API GatewayはX-Ca-error-messageヘッダーでエラーメッセージを返します。

2.1 X-Ca-Request-Idを使用してより多くのAPI呼び出し情報を照会する

応答のX-Ca-Error-CodeおよびX-Ca-Error-Messageヘッダーから、呼び出し失敗に関する基本情報を取得できます。詳細が必要な場合は、X-Ca-Request-Idヘッダーを使用して、Simple Log Serviceのリクエストログを照会し、API Gatewayコンソールで結果をリクエストできます。 X-Ca-Request-Idヘッダーをテクニカルサポートエンジニアに提供して、さらにトラブルシューティングを行うこともできます。

API Gatewayコンソールで呼び出しログを照会するには、次の手順を実行します。

API Gatewayコンソールにログインします。
左側のナビゲーションウィンドウで、[APIの呼び出し] > [トラブルシューティング] を選択します。表示されるページで、APIのリージョンとX-Ca-Request-Idを指定し、[クエリ] をクリックして対応するログを表示します。

説明

ログのフィールドの詳細については、「Simple Log Serviceを使用してAPI呼び出しのログを管理する」をご参照ください。

2.1.1 API Gatewayによって報告されたエラー

X-Ca-Error-Codeヘッダーが空でない場合、リクエストはAPI Gatewayによって拒否されます。. エラーコードは6文字の文字列です。エラーコードとともに、エラーメッセージと簡単なエラー原因の説明も返されます (X-Ca-error-message) 。情報に基づいてエラーをトラブルシューティングできます。の詳細については、「エラーコード一覧」をご参照ください。

2.1.2 バックエンドサービスによって報告されたエラー

HTTPステータスコードが200でなく、X-Ca-Error-codeヘッダーが空の場合、API Gatewayはリクエストをバックエンドサービスに転送し、バックエンドサービスはリクエストを処理して非200ステータスコードを返します。この場合、バックエンドサービスのビジネスロジックを確認する必要があります。 Alibaba Cloud MarketplaceからAPIを購入した場合、Alibaba Cloud Marketplaceのサービスプロバイダーに連絡する必要があります。

2.1.3 成功

HTTPステータスコードが200の場合、API Gatewayはリクエストをバックエンドサービスに転送しており、バックエンドサービスはリクエストを処理した後に成功応答を返します。

3。トレースログの取得

[トレースの記録] を選択した場合、API Gatewayによって受信されたリクエスト、処理情報、API Gatewayによってバックエンドサービスに転送されたリクエスト、API Gatewayによって受信されたレスポンス、およびAPI Gatewayによってクライアントに転送されたレスポンスをトレースログで表示できます。

Resource Access Management (RAM) ユーザーまたはRAMロールを使用している場合は、Alibaba CloudアカウントによってAPIが存在するインスタンスのAcquireGatewayToken操作に対する権限が付与されていることを確認する必要があります。次のサンプルコードは、例を示します。詳細については、「RAMを使用したAPIリソースのアクセス許可の管理」をご参照ください。

{
 "Version": "1",
 "Statement": [
 {
 "Effect": "ALLOW",
 "Action": "apigateway:AcquireGatewayToken",
 "Resource": "acs:apigateway:{#regionId}:{#accountId}:instance/{#InstanceId}"
 }
 ]
}
# {#} indicates a variable that you must replace with an actual value.

4. 原因を分析する

[診断] タブの [呼び出し情報] セクションで、この呼び出しのログを表示できます。通話が失敗した場合、ログに基づいて問題をトラブルシューティングできます。次の2つのフィールドを使用して、課題をすばやく検索できます。

TotalLatency: API Gatewayがリクエストを受信してからクライアントがレスポンスを受信するまでの期間。
ServiceLatency: API Gatewayがリクエストを転送してから、API Gatewayがバックエンドサービスから応答を受信するまでの期間。

ServiceLatencyの値が0の場合、リクエストはAPI Gatewayによって拒否されます。 ServiceLatencyの値が0でない場合、リクエストはバックエンドサービスに転送されます。さらに、リクエストリンク全体の入出力 (I/O) 時刻がログに記録されます。

FrontRequestStart: API Gatewayがクライアント要求の受信を開始する時点
FrontRequestEnd: API Gatewayがクライアント要求の受信を完了した時点
BackendRequestStart: API Gatewayがバックエンドサービスへのリクエストの転送を開始した時点
BackendRequestEnd: API Gatewayがバックエンドサービスへのリクエストの転送を完了した時点
BackendResponseStart: API Gatewayがバックエンドサービスから応答を受信し始める時点
BackendResponseEnd: API Gatewayがバックエンドサービスからの応答の受信を完了した時点
FrontResponseStart: API Gatewayがクライアントに応答を送信し始める時点
FrontResponseEnd: API Gatewayがクライアントへの応答の送信を完了した時点

適切に使用されたログは、問題の迅速な解決に役立ちます。ログのフィールドの詳細については、「Simple Log Serviceを使用してAPI呼び出しのログを管理する」をご参照ください。