application-integration-troubleshooting

Application Integration のトラブルシューティング

失敗したり、停止したり、何も起きていないように見えたりする Google Cloud Application Integration の実行を診断し、復旧します。このスキルでは、実行状態の確認、タスクごとの失敗の調査、Cloud Logging と Cloud Monitoring の確認、Integration Connectors のヘルスチェック、サスペンションの解決、IAM やクォータの確認について説明します。

ツールと対象範囲

• インターフェースは REST です。 gcloud integrations コマンドグループも、Google が管理する Application Integration 用 MCP サーバーもありません。gcloud auth print-access-token と curl を使用するか、ディスカバリーベースの Python クライアント（googleapiclient.discovery.build("integrations", "v1") と build("connectors", "v1")。pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3" でインストール）を使用してください。
• 汎用の gcloud コマンドを使用できます。 認証（gcloud auth）、API の有効化（gcloud services）、IAM の確認（gcloud projects get-iam-policy、gcloud iam service-accounts get-iam-policy）、ログのクエリ（gcloud logging read）に適用されます。
• リージョンの対象範囲。 インテグレーション、実行、接続、実行ログは、単一の Google Cloud リージョン（LOCATION。例：us-central1）に存在します。誤ったリージョンをクエリすると、結果は空になります。
• 関連するスキル：
  • 製品の概念、API の有効化、リージョンのプロビジョニング、初期 IAM ロール、サービス上限については、application-integration-basics を使用してください。
  • ドラフトの作成、タスクとトリガーの編集、構成変数、公開、:execute と :schedule のペイロード、CI/CD のエクスポート／インポートについては、application-integration-authoring を使用してください。

安全性と確認のルール

• 読み取り専用の確認は自由に実行できます： executions.list、suspensions.list、connections.get、connectionSchemaMetadata の get 呼び出し、ランタイム v2 の actions.list／entityTypes.list、gcloud logging read、および v2 の executions:troubleshoot。
• 状態を変更する操作には、ユーザーの明示的な確認が必要です。 実行のキャンセルや再実行、サスペンションの解除や解決、コネクタのスキーマメタデータの更新、コネクタのイベント機能の修復、バージョンの公開または公開解除、IAM バインディングの変更を行う前に、コマンド全体を提示し、ユーザーの承認を待ってください。
• 破壊的なスクリプトをまとめて実行しないでください。 ユーザーから明示的な依頼がない限り、トラブルシューティング中にインテグレーション、バージョン、接続、認証プロファイルを削除しないでください。

前提条件とセットアップの確認

API をクエリする前に、環境に認証情報と有効な API があり、対象リージョンが正しく設定されていることを確認してください。

# Verify active identity and project
gcloud config get-value account
gcloud config get-value project

# Check that required APIs are enabled on PROJECT_ID
gcloud services list --enabled --project="PROJECT_ID" \
  --filter="config.name:(integrations.googleapis.com OR connectors.googleapis.com OR secretmanager.googleapis.com)"

• API が有効になっていない場合は、gcloud services enable integrations.googleapis.com connectors.googleapis.com secretmanager.googleapis.com --project="PROJECT_ID" を実行する前に、ユーザーに確認してください。
• PROJECT_ID に有効な請求先アカウントが関連付けられていることを確認してください（使用量が月間無料枠内でも必要です。Application Integration の料金ページを参照してください）。
• Python ディスカバリークライアント（pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3" でインストール）または ADK（ApplicationIntegrationToolset）を使用する場合は、gcloud auth application-default login と gcloud auth application-default set-quota-project PROJECT_ID で認証してください。

診断の判断フロー

インテグレーションが失敗した、何も起きなかった、または停止しているとユーザーから報告された場合は、常に以下の手順を順番に進めてください。

ステップ 1：実行が行われたことを確認し、実際の状態を確認する

:execute の HTTP 200 ステータスだけを、すべてのタスクが成功した証拠として扱わないでください（注：v1 REST API には integrations:test もありますが、必須の TestIntegrationsRequest.clientId の値は公開ドキュメントに記載されていないため、値を推測しないでください。非本番環境のプロジェクトに公開し、:execute を呼び出してテストしてください）。診断のルールとして、常にレスポンスのペイロードと実行レコードを確認してください。

• 必須の確認対象は、executions.list?filter=execution_id="EXECUTION_ID" で取得する実行レコードです。executionDetails.state、各タスクの taskExecutionState、および responseParameters 内の ErrorInfo を調べてください（サポートされている公開シグナルではない、レガシーの非推奨フィールド executionFailed に頼らないでください）。
• 呼び出し元が :execute に "doNotPropagateError": true を渡した場合、API は executionId を含む HTTP 200 を返し、HTTP エラーを返す代わりに、イベントパラメーター内にエラーの詳細を格納します。
• :execute または :schedule で重複した requestId を指定すると、新しい実行を行わず、以前の実行のレスポンスを返します。
• タスクの失敗ポリシー（IGNORE と NONE）により、個々のタスクが失敗していても、統合は別の分岐で処理を続行または完了し、SUCCEEDED になる場合があります。

統合の実行を一覧表示します（すべての統合をリージョン横断で検索するには、INTEGRATION_NAME に - を使用します。ディスカバリドキュメントには orderBy=create_time の並べ替え順が昇順か降順か記載されていないため、必要に応じて CreateTimestamp フィルターを追加するか、pageToken でページネーションしてください）。

curl -sS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/executions?pageSize=10&orderBy=create_time&snapshotMetadataWithoutParams=true"

EXECUTION_ID を取得したら、完全な ExecutionDetails とタスクごとの状態を取得します（executions.list では filter、snapshotMetadataWithoutParams=true、および readMask を使用してください。非推奨の truncateParams［UI 専用］や filterParams.*［内部専用］パラメーターは使用しないでください）。

curl -sS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/executions?filter=execution_id%3D%22EXECUTION_ID%22"

executions.list を状態でフィルタリングするには、ExecutionDetails.state の値を引用符で囲まずに state フィールド（= または !=）を使用します（例：filter=state=FAILED、filter=state!=SUCCEEDED、filter=state=CANCELLED、または filter=state=FAILED OR state=CANCELLED。URL エンコードする場合は filter=state%3DFAILED または filter=state%3DFAILED%20OR%20state%3DCANCELLED）。REST リファレンスページに記載されている eventExecutionState や、API リファレンスのフィルター説明にある event_execution_state ではなく、state を使用してください。また、サポートされているフィルターキー（execution_id、state、update_time、workflow_name、trigger_id、CreateTimestamp、parameter_type）を使用してください。ドキュメントの例に記載されているものがあっても、executionId などのキャメルケースの表記はサポートされていません。

ステップ 2：実行記録が存在しない場合

executions.list で一致する実行が返されない場合、トリガーが発火しなかったと判断する前に、次の 5 つの原因を確認してください。

原因	症状	確認する内容
リージョンが違う	LOCATION の一覧が空	https://console.cloud.google.com/integrations を確認するか、他のリージョンでインテグレーションの一覧を取得してください。
API トリガーが 403	呼び出し元に HTTP 403 PERMISSION_DENIED が返された	API トリガーの認証拒否は実行の作成前に発生するため、実行ログには何も記録されません。呼び出し元の IAM と、実行サービスアカウントに対する roles/iam.serviceAccountUser を確認してください。
API トリガーのペイロードが 8 MB 超	呼び出し元にエラーが返された	API トリガーの入力変数の合計が 8 MB の上限を超えているため、インテグレーションが開始されません。
ローカルロギングが無効	インテグレーションは実行されたが、ログが空	IntegrationVersion.databasePersistencePolicy を確認してください（DATABASE_PERSISTENCE_DISABLED = Disable、DATABASE_PERSISTENCE_POLICY_UNSPECIFIED = Enable (sync)（API のデフォルト）、DATABASE_PERSISTENCE_ASYNC = Enable (async)（コンソールのデフォルト））。また、インテグレーションデータの合計が 10 MB を超える場合（上限は 30 MB）、ローカルロギングは自動的に無効になります。
バージョンが ACTIVE ではない	トリガーが発火しない	トリガーから実行されるのは、ACTIVE（公開済み）のバージョンのみです。公開後も、結果整合性のため、古いバージョンが最大 10 分間引き続き処理を行う場合があります。

ステップ 3：実行状態（ExecutionDetails.state）に応じて分岐する

状態の全リファレンス、タスクレベルの状態（TaskExecutionDetails.taskExecutionState）、フィルター構文、キャンセル／再実行のルールについては、実行状態を参照してください。

ExecutionDetails.state	コンソールのステータス	意味と次の手順
FAILED	失敗	responseParameters の ErrorInfo（message、code）を確認し、失敗したタスクの taskExecutionState（FAILED または FATAL）を調べ、ステップ 4（:troubleshoot と Cloud Logging）を実行してください。
SUCCEEDED	成功	期待した処理が行われなかった場合は、taskExecutionDetails を調べ、SKIPPED（エッジ条件が false）または FAILED（IGNORE または NONE の再試行戦略によってマスクされた）のタスクを確認してください。
CANCELLED	キャンセル済み	ユーザーが実行をキャンセルした、実行が一時停止中に新しいインテグレーションバージョンが公開された、SYNC 実行が 2 分のタイムアウトに達した、または再実行された実行が 10 分の期限に達した状態です。
SUSPENDED	一時停止中	Approval タスク（Cloud コンソールの UI または suspensions:resolve で解決可能）または Suspend タスク（suspensions:lift で再開可能）を待機しています。一時停止を参照してください。
RETRY_ON_HOLD	再試行待ち	タスクまたはインテグレーションが一時的なエラーで失敗し、バックオフ再試行キューで待機しています。
PROCESSING	処理中	現在実行中です。ASYNC 実行が 10 分のタイムアウトに近づいていないか確認してください。
PENDING	保留中	スケジュール済み、または一時停止中で、トリガーされるのを待っています。

ステップ 4：ログ、AI による根本原因、サブシステムの健全性を調べる

1. 失敗した実行に対して AI Troubleshoot（v2 REST API）を実行し、構造化された根本原因の概要を取得します（integrations.executions.get が必要です）。

   curl -sS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://integrations.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/executions/EXECUTION_ID:troubleshoot"
   

2. バージョンで Cloud Logging が有効になっている場合は、Cloud Logging をクエリします。Cloud Logging はデフォルトで無効であり、ローカルロギングが無効の場合は何も書き込みません。有効化方法、重大度の動作、正確なクエリについては、ロギングとモニタリングを参照してください。

   gcloud logging read \
     'resource.type="integrations.googleapis.com/IntegrationVersion" AND jsonPayload.executionId="EXECUTION_ID"' \
     --project="PROJECT_ID" --limit=20 --format=json
   

3. Connectors タスクが失敗した場合は、コネクタと IAM のどちらに問題があるかを推測しないでください。接続リソース（connections.get）とそのスキーマメタデータ（state と errorMessage については GET .../connections/CONNECTION_NAME/connectionSchemaMetadata、一覧表示についてはランタイム v2 の GET .../v2/.../connections/CONNECTION_NAME/actions および .../entityTypes）を調べます。v1 の connectionSchemaMetadata:listActions と :listEntityTypes には filter が必要で、フィルターなしの呼び出しは拒否されます。接続の状態、スキーマメタデータの確認、ノードのスロットリング（HTTP 429）については、Connectors の健全性を参照してください。

   curl -sS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_NAME?view=FULL"
   

4. IAM（403）、実行ユーザーのサービスアカウント、タイムアウト、またはクォータのエラーが発生した場合は、呼び出し元のロールと、インテグレーションの実行ユーザーのサービスアカウントの両方を確認してください。2026 年 10 月 15 日以降に作成されたインテグレーションは、API トリガーまたは Private トリガー以外のトリガー（Schedule、Cloud Scheduler、Cloud Pub/Sub、Salesforce、Connector Event など）が設定されている場合、runAsServiceAccount が設定されていないとテストも公開もできません。Private トリガーは API トリガーと同様に例外であり、唯一のトリガーが Private であるサブインテグレーションは、runAsServiceAccount を設定せずに公開できます。runAsServiceAccount が設定されている場合は、バージョンを公開またはテストするユーザーに、そのサービスアカウントに対する roles/iam.serviceAccountUser が必要です。両側の 403 チェックリスト、エラーコード、タスク制限、ADK ApplicationIntegrationToolset のエラーについては、よくあるエラーを参照してください。

よくある診断シナリオ

シナリオ A：Connectors タスクの失敗（接続の健全性と呼び出し元の IAM）

1. view=FULL を指定して connections.get を実行し（上記のコマンド）、status.state と status.status を確認します。
2. **status.state が ERROR または AUTHORIZATION_REQUIRED の場合：**接続自体が対象のバックエンドに到達できないか、認証できません。Secret Manager または Cloud コンソール（https://console.cloud.google.com/connectors/connections）で接続の認証情報を修正します。接続で別のプロジェクトのサービスアカウントを使用している場合は、[email protected] に、そのプロジェクトで roles/iam.serviceAccountTokenCreator が付与されていることを確認します。
3. **status.state が ACTIVE の場合：**接続は正常です。タスクを実行する ID（インテグレーションの runAsServiceAccount、または未設定の場合は service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com）に、接続のプロジェクトで必要な Integration Connectors ロール（roles/connectors.invoker や roles/connectors.admin など）があるか確認します。
4. **タスクが HTTP 429 で失敗した場合：**接続がプロビジョニング済みのノード数を超えています。接続の最小ノード数と最大ノード数を増やし、タスクに再試行戦略（EXPONENTIAL_BACKOFF）を追加します。
5. Cloud Logging でコネクタの試行を正確に追跡します（接続でコネクタのロギングが有効になっている場合）。

   gcloud logging read \
     'resource.type="connectors.googleapis.com/Connection" AND jsonPayload.integration_connectors_trace_id="EXECUTIONID_TASKID_ATTEMPTNUMBER"' \
     --project="PROJECT_ID" --limit=20 --format=json
   

シナリオ B：SUSPENDED のまま停止している（承認タスクと一時停止タスク）

1. taskExecutionDetails から実行を一時停止したタスクを特定し、保留中の一時停止を一覧表示します（読み取り専用。integrations.suspensions.list が必要で、roles/integrations.suspensionResolver に含まれます）。SUSPENSION_ID と taskId を確認します。roles/integrations.suspensionResolver だけでは実行レコードを読み取れない点に注意してください（integrations.executions.list と integrations.executions.get がないため、executions.list と v2 の :troubleshoot は HTTP 403 を返します）。taskExecutionDetails を調べる（または :troubleshoot を実行する）には、roles/integrations.integrationViewer も付与してください（または、実行 ID とタスク ID が含まれる承認メールのリンクを使用します）。詳しくは、一時停止をご覧ください。

   # Read-only: list suspensions on EXECUTION_ID
   curl -sS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/executions/EXECUTION_ID/suspensions"
   

2. 承認タスク： Cloud コンソール UI または REST API で承認または拒否できます（POST https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/executions/EXECUTION_ID/suspensions/SUSPENSION_ID:resolve を本文 {"suspension": {"eventExecutionInfoId": "EXECUTION_ID", "integration": "INTEGRATION_NAME", "taskId": "TASK_ID", "state": "LIFTED"}} または "REJECTED" とともに呼び出します。これはコンソールの［承認］／［拒否］ボタンと同じ呼び出しです）。解決する前に、必ずユーザーに確認してください。呼び出し元が integrations.suspensions.resolve（roles/integrations.suspensionResolver に含まれますが、roles/integrations.integrationEditor には含まれません）および インテグレーションの runAsServiceAccount に対する roles/iam.serviceAccountUser を持っていることを確認してください。roles/iam.serviceAccountUser がない場合、承認しても実行は期限切れになるまで一時停止したままです。
3. 一時停止タスク： :lift は一時停止タスク用の操作で、integrations.suspensions.lift（roles/integrations.suspensionResolver に含まれます）と、インテグレーションの runAsServiceAccount に対する roles/iam.serviceAccountUser が必要です。ユーザーの確認後、オプションの suspensionResult を指定して POST .../executions/EXECUTION_ID/suspensions/SUSPENSION_ID:lift を呼び出します。
4. バージョン公開によるキャンセルに注意： インテグレーションの新しいバージョンを公開すると、以前のバージョンの一時停止中の実行はすべて自動的にキャンセルされます。

シナリオ C：トリガー、テスト、または公開で HTTP 403 PERMISSION_DENIED が発生する

Application Integration では、互いに独立した 2 つの権限チェックが行われます。

1. 呼び出し元の IAM チェック： 呼び出し元にはインテグレーションに対する権限が必要です（呼び出しには roles/integrations.integrationInvoker、編集／テストには roles/integrations.integrationEditor、公開には roles/integrations.integrationDeployer または roles/integrations.integrationEditor）。
2. 実行サービスアカウントのチェック： バージョンに runAsServiceAccount が設定されている場合、バージョンを公開またはテストするユーザー（またはプリンシパル）には、公開／テスト時に runAsServiceAccount に対する roles/iam.serviceAccountUser が必要です。また、実行時には、呼び出し元またはトリガーのサービスアカウントに、runAsServiceAccount に対する roles/iam.serviceAccountUser が必要です（サービスアカウントを所有するプロジェクトで付与します）。さらに、runAsServiceAccount には、下流の Google Cloud リソースに対するロールが必要です。

再試行する前に、両方のバインディングを確認してください。Pub/Sub、Eventarc、Connector Event トリガーでは、実行サービスアカウントの権限（roles/iam.serviceAccountUser）が拒否されると、失敗した実行が記録され、イベントは再配信されません。

復旧操作（ユーザーの確認が必要）

:cancel、:replay、:lift、または :resolve を実行する前に、必ず正確なコマンドを表示し、ユーザーの確認を得てください。:cancel には integrations.executions.cancel が必要で、:replay には integrations.executions.replay が必要です（いずれも roles/integrations.integrationInvoker、roles/integrations.integrationEditor、roles/integrations.integrationAdmin が保持しますが、roles/integrations.suspensionResolver または roles/integrations.integrationViewer は保持しません。そのため、roles/integrations.suspensionResolver のみを持つ承認者は、停止した SUSPENDED 実行をキャンセルできません）。また、:replay には FAILED_PRECONDITION を返す次の 2 つの前提条件があります。（a）テストケースの実行は、どのモードでも再実行できません（"Test runs cannot be replayed."）。（b）データベース永続化（ローカルログ／databasePersistencePolicy: DATABASE_PERSISTENCE_DISABLED）を無効にして実行した場合、実行スナップショットが必要なため、REPLAY_MODE_POINT_OF_FAILURE は拒否されます。その場合は REPLAY_MODE_FROM_BEGINNING を使用してください。:replay で modifiedParameters と updateMask を使って入力を上書きする場合は、上書きするキーをすべて updateMask に列挙してください。updateMask がない場合、元の入力はすべて破棄され、modifiedParameters のみが使用されます。また、updateMask に含まれるキーが modifiedParameters にない場合はエラーになります。

# Cancel an execution in PENDING (console "On hold"), RETRY_ON_HOLD, or SUSPENDED state (requires integrations.executions.cancel)
# (Cannot cancel executions in PROCESSING state [console "In process"], completed runs [SUCCEEDED, FAILED, CANCELLED], or Schedule-trigger runs; approvers with only roles/integrations.suspensionResolver cannot cancel a stuck SUSPENDED run)
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"cancelReason": "Canceling stuck execution after investigation"}' \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/executions/EXECUTION_ID:cancel"

# Replay a SUCCEEDED, FAILED, or CANCELLED execution on a published integration (Preview; requires integrations.executions.replay; test-case runs and Schedule-trigger runs cannot be replayed)
# replayMode: REPLAY_MODE_FROM_BEGINNING or REPLAY_MODE_POINT_OF_FAILURE (failed runs only; refused with FAILED_PRECONDITION if databasePersistencePolicy was DATABASE_PERSISTENCE_DISABLED—use REPLAY_MODE_FROM_BEGINNING in that case)
# Optional modifiedParameters/updateMask: list every overridden key in updateMask; without updateMask, all original inputs are discarded and only modifiedParameters are used; a key in updateMask missing from modifiedParameters is an error
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"replayReason": "Replay after fixing downstream permission", "replayMode": "REPLAY_MODE_POINT_OF_FAILURE"}' \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/executions/EXECUTION_ID:replay"

参考ファイル

詳細、正確なフィールド名、またはエッジケースの確認が必要な場合は、該当する参考ファイルを読み込んでください。

• 実行状態：ExecutionDetails.state と TaskExecutionDetails.taskExecutionState の列挙値、executions.list のフィルター演算子、大容量ログ（300 MB 超）への対処方法、:cancel／:replay の制約。
• ロギングとモニタリング：ローカルロギングと Cloud Logging の相互作用、ドラフトバージョンでの Cloud Logging の有効化、Logs Explorer のクエリ、integrations.googleapis.com/* と connectors.googleapis.com/* のメトリクススキーマ、アラートの設定。
• 一般的なエラー：HTTP/gRPC のエラーコード、403 に関する二段階のチェックリスト、2026 年 10 月 15 日の実行用サービスアカウント要件、タスク単位の制限と注意点、ADK ApplicationIntegrationToolset のエラー。
• コネクタの状態：ConnectionStatus.state、EventingStatus.state、connectionSchemaMetadata の確認、ランタイム v2 のレディネス呼び出し、ノードのスロットリング（HTTP 429）、接続認証と呼び出し元の IAM の切り分け。
• 一時停止：一時停止、承認、タイマーの動作、suspensions.list／:lift／:resolve のペイロード、有効期限の設定、roles/iam.serviceAccountUser がないと承認が停止したままになる理由。