alibabacloud-error-troubleshoot

Alibaba Cloud OpenAPI のトラブルシューティング

Aliyun CLI コマンドとして公開されている OpenAPI Explorer のトラブルシューティング API を使用して、Alibaba Cloud OpenAPI の呼び出し失敗を診断できるようユーザーを案内します。これらの CLI コマンドは、OpenAPI Diagnostic Portal と同じバックエンドを呼び出します。

---

前提条件

Aliyun CLI のインストール

aliyun version を実行し、バージョンが >= 3.4.0 であることを確認します。インストールされていない場合、またはバージョンが古い場合は、references/cli-installation-guide.md に従ってください。

OpenAPI Explorer プラグインのインストール（最初に必ず実施）

このスキルは、次の 3 つの必須 CLI コマンドを提供する aliyun-cli-openapiexplorer プラグインに依存します。 openapiexplorer get-own-request-log、openapiexplorer get-request-log、openapiexplorer get-error-code-solutions。

プラグイン名は aliyun-cli-openapiexplorer です（openapiexplorer ではありません）。 インストールコマンドでは --names を使用します。

aliyun configure set --auto-plugin-install true
aliyun plugin install --names aliyun-cli-openapiexplorer
aliyun plugin update

トラブルシューティングコマンドを実行する前に、利用可能であることを確認します。

aliyun plugin list | grep openapiexplorer
aliyun openapiexplorer get-own-request-log --help

コマンド形式のルール（必須）。 このスキルのすべてのトラブルシューティングコマンドでは、openapiexplorer プラグイン配下の kebab-case 形式をそのまま使用する必要があります。

• aliyun openapiexplorer get-own-request-log ...
• aliyun openapiexplorer get-request-log ...
• aliyun openapiexplorer get-error-code-solutions ...

PascalCase のサブコマンドは厳禁です。 代替として aliyun <product> <PascalCaseApi> 形式の呼び出しを作成したり、試したりしないでください。トラブルシューティングコマンドが not a valid api を返した場合は、openapiexplorer プラグインが不足しています。ActionTrail、ウェブ検索、または元の失敗した API の再呼び出しに切り替えるのではなく、上記のインストールコマンドを再実行してください。これら 3 つのコマンドは openapiexplorer プラグインでのみ利用でき、コア製品のサブコマンドに相当するものはありません。

Alibaba Cloud 認証情報の確認

aliyun configure list を実行して、認証情報が設定されていることを確認します。 有効なプロファイルが表示されない場合は、中止して、ユーザーにこのセッションの外で aliyun configure を実行するよう依頼してください。

セキュリティルール：

• AK/SK の値を読み取ったり、エコーしたり、表示したりすることは絶対にしないでください
• ユーザーに会話内で AK/SK を貼り付けるよう求めることは絶対にしないでください
• 認証情報の状態の確認には aliyun configure list のみを使用してください
• 結果を提示する際は、ログ出力内の機密フィールド（authenticationInfo.ak、トークンなど）をマスキングしてください

---

オブザーバビリティ（すべての aliyun コマンドで必ず遵守）

このスキルの読み込み時に、セッション全体で使用するランダムなセッション ID を一度だけ生成します。

• 形式： 32 文字の小文字の 16 進数文字列（例：a1b2c3d4e5f6789012345678901234ab）
• タイミング： セッション開始時に一度だけ生成し、このセッション内のすべてのクラウド API 呼び出しで同じ値を再利用します
• プレースホルダー： 以下のすべてのコマンドで {session-id} として使用します

ルール：クラウド API を呼び出すすべての aliyun CLI コマンドに --user-agent フラグを含める必要があります。

ローカルユーティリティコマンド（例：configure、plugin、version）はこのフラグをサポートしないため、対象外とします。

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

---

シナリオの説明

ユーザーが次のことを希望する場合に、このスキルを使用します。

• Request ID（API のレスポンスまたはエラーに含まれる UUID）からリクエストログの詳細を検索する
• API 呼び出しが失敗した理由（HTTP ステータス、エラーコード、呼び出し元の ID、リクエストパラメーター）を把握する
• 特定のエラーコードに対する公式の診断ソリューションを取得する
• OpenAPI 呼び出しにおける権限／RAM／スロットリング／パラメーターの問題をトラブルシューティングする

---

RAM 権限の要件

API	CLI コマンド	目的
GetOwnRequestLog	get-own-request-log	現在のアカウントが実行した API 呼び出しのログを照会します
GetRequestLog	get-request-log	同じ親アカウント配下の Request ID のログを照会します。メインアカウントと、そのすべてのサブアカウントが対象です
GetErrorCodeSolutions	get-error-code-solutions	エラーコードの診断ソリューションを取得します

最小限の RAM ポリシー JSON については、references/ram-policies.mdを参照してください。

権限エラーが発生した場合の処理： 呼び出しで Unauthorized または AccessDenied が返された場合は処理を中止し、references/ram-policies.mdを提示してください。明示的なユーザー確認なしに、別のアカウントで再試行してはいけません。

---

基本的な診断ワークフロー

次の判断フローに従ってください。詳細については、references/troubleshooting-workflow.mdを参照してください。

User has Request ID?
├── YES → Step 1: Query request log
│         ├── Default: get-own-request-log (current account only)
│         └── Request ID from sibling sub-account or main account: get-request-log
│         ├── Step 1 returns NotFound.RequestLog (404)?
│         │     └── TERMINATE: do NOT call get-error-code-solutions with `NotFound.RequestLog`.
│         │        Report log-unavailable cause (expired / wrong scope / no permission),
│         │        ask user for a fresh Request ID or the original error code, end the run.
│         ├── Step 2: Extract errorCode, errorMessage, product from logInfo.basicInfo
│         └── Step 3: If errorCode present → get-error-code-solutions
│            → Step 4: Summarize root cause + solutions + next steps
└── NO, only error code/message
    └── Step 3 directly: get-error-code-solutions (provide product if known)

⛔ ログが NotFound の場合は必ず停止： NotFound.RequestLog は「ログを利用できない」ことを示す troubleshoot-API 独自のステータスであり、ユーザーの失敗した呼び出しにおけるビジネスエラーコードではありません。これを get-error-code-solutions に渡すと、無関係または空の結果が返るため、厳禁です。必ず NotFound 分岐でワークフローを終了し、ユーザー向けの復旧メッセージを提示してください。

ステップ 1：Request ID でリクエストログを照会する

Request ID の形式： UUID、大文字（例：BE7C768F-946F-5B46-80D4-F22FCFAF67C0）。

適切なコマンドを選択してください：

コマンド	範囲	使用する状況
get-own-request-log	現在のアカウント自身による API 呼び出しのみ	デフォルト — ユーザーが自身の失敗した API 呼び出しをトラブルシューティングする場合
get-request-log	同じ親アカウント配下のみ — メインアカウントと、その配下にあるすべてのサブアカウント	サブアカウントからメインアカウントまたは兄弟サブアカウントの Request ID を照会する場合。無関係なアカウントにはアクセスできません

まずは get-own-request-log を優先してください。これは OpenAPI Diagnostic Portal の動作と同じです（GetOwnRequestLog が GetRequestLog より先に試行されます）。

# Default: current account
aliyun openapiexplorer get-own-request-log \
  --log-request-id <REQUEST_ID> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

# Same parent account — main account or sibling sub-accounts
aliyun openapiexplorer get-request-log \
  --log-request-id <REQUEST_ID> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

logInfo から重要なフィールドを抽出します（--cli-query を使用して必要な項目を取得してください）。

aliyun openapiexplorer get-own-request-log \
  --log-request-id <REQUEST_ID> \
  --cli-query 'logInfo.basicInfo.{product:product,api:api,errorCode:errorCode,errorMessage:errorMessage,httpStatusCode:httpStatusCode,regionId:regionId,logRequestId:logRequestId}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

フィールドパス	意味
logInfo.basicInfo.product	製品コード（ソリューションの検索に必要）
logInfo.basicInfo.api	API アクション名
logInfo.basicInfo.errorCode	失敗した呼び出しのエラーコード
logInfo.basicInfo.errorMessage	エラーメッセージ
logInfo.basicInfo.httpStatusCode	HTTP ステータス（ビジネスエラーを伴う 200 か、4xx/5xx か）
logInfo.basicInfo.regionId	リージョン
logInfo.callerInfo	呼び出し元のアカウント、IP、呼び出し元の種類（メイン／サブ／STS）
logInfo.parameters	API に送信されたリクエストパラメーター
logInfo.responses.responseBody	生のレスポンス本文（ネストされたエラーの詳細が含まれる場合があります）

ステップ 2：ログを分析する

ソリューションを取得する前に、ログを解釈してください。

0. NotFound.RequestLog（照会自体から返された HTTP 404） — ログを利用できません。ここで停止してください。 ステップ 3 に進んではいけません。上記の「ログが NotFound の場合は必ず停止」と、以下の「CLI エラーのトラブルシューティング → 6」を参照してください。
1. HTTP 200 ＋ 空の errorCode — 呼び出しは成功しています。ユーザーが誤った Request ID を確認しているか、下流で問題が発生している可能性があります。
2. HTTP 4xx/5xx または空でない errorCode — ステップ 3 に進みます。
3. スロットリング — basicInfo.throttlingResult を確認します（例：FC.PASS とスロットリングコードを比較）。
4. RAM／権限エラー — errorCode またはレスポンス本文で AccessDenied、NoPermission、Forbidden.RAM を探します。callerInfo.callerType と、STS ロールが関係しているかどうかを確認してください。
5. パラメーターエラー — logInfo.parameters を basicInfo.apiDoc にリンクされている API ドキュメントと照合してください。

ステップ 3：エラーコードの解決策を取得する

troubleshoot-server の sdkAgentService.getErrorCodeSolutions → OpenAPI の GetErrorCodeSolutions に対応します。

⛔ 前提条件 — errorCode は、正常に取得したログの logInfo.basicInfo.errorCode（またはユーザーから最初に報告されたエラー）から取得する必要があります。 ルックアップ自体のメタステータスコード（get-*-request-log 呼び出し自体が返す NotFound.RequestLog、Unauthorized、AccessDenied）を --error-code に指定しないでください。ステップ 1 で NotFound が返された場合、ワークフローはすでに終了しています。ステップ 3 に進まないでください。

aliyun openapiexplorer get-error-code-solutions \
  --error-code <ERROR_CODE> \
  --product <PRODUCT_CODE> \
  --error-message "<ERROR_MESSAGE>" \
  --accept-language zh-CN \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

パラメーター	必須	備考
--error-code	はい	ログの basicInfo.errorCode またはユーザーのエラー報告から取得します
--product	推奨	ログの basicInfo.product から取得します。一致する解決策を絞り込みます
--error-message	任意	同じコードに対して複数の解決策がある場合、一致精度が向上します
--accept-language	任意	zh-CN（デフォルト）または en-US。英語のコンテンツがない場合は空にします

プロダクトコードの取得元：

• ステップ 1 の logInfo.basicInfo.product（推奨）
• OpenAPI ポータルの URL：https://api.aliyun.com/product/<ProductCode> → ProductCode は /product/ の後に続くセグメントです

各解決策の title／content を明確に提示してください。solutions 配列が空の場合、用意された解決策はありません。ログの分析と API ドキュメントを参照してください。

ステップ 4：診断結果を提示する

必ず次の内容を含めてください。

1. 発生したこと — API、プロダクト、リージョン、HTTP ステータス、エラーコード／メッセージ
2. 呼び出し元 — 呼び出し元のアカウント種別と ID（AK は伏せてください）
3. 根本原因 — ログ分析と解決策に基づく内容
4. 推奨する対応 — 解決策の内容と、特定されたパラメーター／RAM の修正
5. 使用した CLI コマンド — コピーしてそのまま実行できる完全なコマンド（シークレットは伏せてください）

---

コマンド早見表

パラメーター一覧と例については、references/api-reference.md を参照してください。

CLI	API	説明
aliyun openapiexplorer get-own-request-log	GetOwnRequestLog	現在のアカウントのリクエストログ
aliyun openapiexplorer get-request-log	GetRequestLog	同じ親アカウント配下のリクエストログ
aliyun openapiexplorer get-error-code-solutions	GetErrorCodeSolutions	エラーコード診断の解決策

---

全般的なルール

• Request ID がメインアカウント、または同じ親アカウント配下の別のサブアカウントに属する場合を除き、常に get-own-request-log を優先してください
• Request ID は大文字の UUID である必要があります — 呼び出し前に正規化してください
• ログから取得できる場合は、必ず get-error-code-solutions に --product を指定してください
• プロダクトコードを推測しないでください — ログまたは OpenAPI ポータルの URL から取得してください
• ログには有効期限があります — NotFound.RequestLog が返された場合、ログの有効期限が切れている（通常、約 3 日間保存）か、呼び出し元に権限がない可能性があります
• 有用な場合は、OpenAPI トラブルシューティングポータルへのリンクを記載してください：https://api.aliyun.com/troubleshoot?q=<ErrorCode>&product=<Product>

---

CLI エラーのトラブルシューティング

ユーザーからエラーの報告があった場合は、次の順に確認してください。

1. CLI のバージョン — aliyun version は 3.4.0 以上ですか？
2. プラグインがインストールされているか — aliyun plugin list | grep openapiexplorer を実行します。
3. 認証情報 — aliyun configure list に有効なプロファイルが表示されていますか？
4. リクエスト ID の形式 — 大文字の UUID ですか？
5. スコープに合わないコマンド — メインアカウントまたは兄弟サブアカウントのリクエスト ID に対して get-own-request-log を実行し、404 が返されましたか？ 同じ親アカウントの場合に限り、get-request-log を再試行してください。それでも 404 の場合、そのリクエスト ID は無関係なアカウントのものか、期限切れ、または無効です。
6. NotFound.RequestLog（404） — ログの期限切れ、誤ったリクエスト ID、または権限不足が原因です。メッセージ："The log related to this logRequestId does not exist, has expired, or you do not have permission to view it."
   • 厳守事項： ここで診断ワークフローを終了してください。--error-code NotFound.RequestLog（または get-*-request-log の呼び出しで発生した Unauthorized／AccessDenied など、検索処理自体のメタステータスコード）を指定して get-error-code-solutions を呼び出さないでください。これらはユーザーの失敗した呼び出しではなく、トラブルシューティング API 自体のステータスコードです。解決策の検索結果は無関係なものになるか、空になります。
   • ユーザーへの標準的な復旧メッセージ： ログを利用できない理由（約 3 日で期限切れになる／リクエスト ID が現在のアカウントのスコープ外である／GetRequestLog 権限がない）を説明し、（a）現在のアカウントで最近失敗した呼び出しによって生成された新しいリクエスト ID、または（b）ユーザーのアプリケーションログに記録された元のエラーコードのいずれかを提示するよう依頼して、このターンを終了してください。
7. Unauthorized／AccessDenied — references/ram-policies.md を参照してください。
8. 解決策が空 — キュレーション済みの解決策はありません。代わりにログのフィールドと API ドキュメントを分析してください。

詳細な手順書：references/troubleshooting-workflow.md。

---

リファレンスドキュメント

ドキュメント	説明
references/cli-installation-guide.md	CLI 3.4.0 以上のインストール、プラグインの設定、認証情報
references/api-reference.md	3 つの API すべてを対象とした CLI コマンドの完全なリファレンス
references/troubleshooting-workflow.md	例を含む、エンドツーエンドの診断手順書
references/ram-policies.md	トラブルシューティング API に必要な最小限の RAM ポリシー