application-integration-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Application Integration Troubleshooting

Application Integration 故障排查

Diagnose and recover Google Cloud Application Integration executions that fail, stall, or appear to do nothing. This skill walks through execution state verification, per-task failure inspection, Cloud Logging and Cloud Monitoring checks, Integration Connectors health probes, suspension resolution, and IAM or quota checks.

诊断并恢复失败、停滞或看似未执行任何操作的 Google Cloud Application Integration 执行。本 skill 将引导你完成执行状态验证、单任务失败检查、Cloud Logging 和 Cloud Monitoring 检查、Integration Connectors 健康探测、暂停解除，以及 IAM 或配额检查。

Tooling and Scope Boundaries

工具与范围边界

REST is the interface. There is no

gcloud integrations

command group and no Google-managed MCP server for Application Integration. Use

curl

with

gcloud auth print-access-token

, or the discovery-based Python client (

googleapiclient.discovery.build("integrations", "v1")

and

build("connectors", "v1")

; install with

pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3"

Generic
gcloud
commands apply for authentication (

gcloud auth

), enabling APIs (

gcloud services

), IAM checks (

gcloud projects get-iam-policy

gcloud iam service-accounts get-iam-policy

), and log queries (

gcloud logging read

Regional scope. Integrations, executions, connections, and execution logs live in a single Google Cloud region (
```
LOCATION
```
, for example
```
us-central1
```
). Querying the wrong region returns empty results.
Sibling skills:
- Use
```
application-integration-basics
```
  for product concepts, enabling APIs, provisioning a region, initial IAM roles, and service limits.
- Use
```
application-integration-authoring
```
  for creating drafts, editing tasks and triggers, config variables, publishing,
```
:execute
```
  and
```
:schedule
```
  payloads, and CI/CD export/import.

REST 是接口。 没有

gcloud integrations

命令组，也没有 Google 管理的 Application Integration MCP server。使用

curl

搭配

gcloud auth print-access-token

，或使用基于 discovery 的 Python client（

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

）。

区域范围。 Integration、execution、connection 和 execution log 都位于单个 Google Cloud region（
```
LOCATION
```
，例如
```
us-central1
```
）中。查询错误的 region 会返回空结果。
同级 skill：
- 对产品概念、启用 API、预配 region、初始 IAM role 和 service limit，使用
```
application-integration-basics
```
  。
- 对创建 draft、编辑 task 和 trigger、配置 variable、发布、
```
:execute
```
  和
```
:schedule
```
  payload 以及 CI/CD export/import，使用
```
application-integration-authoring
```
  。

Safety and Confirmation Rules

安全与确认规则

Read-only checks run freely:

executions.list

suspensions.list

connections.get

connectionSchemaMetadata

get calls, runtime v2

actions.list

entityTypes.list

gcloud logging read

, and

v2

executions:troubleshoot

State-changing actions require explicit user confirmation. Before canceling or replaying an execution, lifting or resolving a suspension, refreshing connector schema metadata, repairing connector eventing, publishing or unpublishing a version, or changing IAM bindings, show the exact command and wait for user approval.
Never bundle destructive scripts or delete integrations, versions, connections, or auth profiles during troubleshooting unless the user specifically asks.

只读检查可直接执行：

executions.list

、

suspensions.list

、

connections.get

、

connectionSchemaMetadata

get 调用、runtime v2

actions.list

entityTypes.list

、

gcloud logging read

和

v2

executions:troubleshoot

。

更改状态的操作需要用户明确确认。 在取消或重放 execution、解除或解决 suspension、刷新 connector schema metadata、修复 connector eventing、发布或取消发布 version，或更改 IAM binding 之前，应展示确切命令并等待用户批准。
绝不要捆绑破坏性脚本，也不要在故障排查过程中删除 integration、version、connection 或 auth profile，除非用户明确要求。

Prerequisites and Setup Check

前置条件与设置检查

Before querying APIs, confirm the environment has credentials, active APIs, and the right target region:

bash

undefined

查询 API 前，先确认环境具有有效凭据、所需 API 已启用，并且目标 region 正确：

bash

undefined

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)"


- If an API is missing, ask the user before running `gcloud services enable integrations.googleapis.com connectors.googleapis.com secretmanager.googleapis.com --project="PROJECT_ID"`.
- Ensure an active billing account is attached to `PROJECT_ID` (required even when usage stays within the monthly free tier; see the [Application Integration pricing page](https://cloud.google.com/application-integration/pricing)).
- For Python discovery clients (install with `pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3"`) or ADK (`ApplicationIntegrationToolset`), authenticate with `gcloud auth application-default login` and `gcloud auth application-default set-quota-project 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` 已关联有效的 billing account（即使用量保持在每月 free tier 内也必须关联；参见 [Application Integration 定价页面](https://cloud.google.com/application-integration/pricing)）。
- 对于 Python discovery client（通过 `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`。

Diagnostic Decision Flow

诊断决策流程

Follow these steps in order whenever a user reports that an integration failed, did nothing, or is stuck.

每当用户报告 integration 失败、未执行任何操作或卡住时，都应按顺序执行以下步骤。

Step 1: Confirm Whether an Execution Ran and Check Its True State

第 1 步：确认 Execution 是否运行并检查其真实状态

Do not rely on an HTTP 200 status from

:execute

as proof that every task succeeded (note:

integrations:test

also exists in the v1 REST API, but its required

TestIntegrationsRequest.clientId

value is not publicly documented, so do not invent one; test by publishing to a non-production project and calling

:execute

). As a diagnostic rule, always check the response payload and execution record because:

The required verification is the execution record from
```
executions.list?filter=execution_id="EXECUTION_ID"
```
—inspect
```
executionDetails.state
```
, each task's
```
taskExecutionState
```
, and
```
ErrorInfo
```
in
```
responseParameters
```
(do not rely on the legacy/deprecated
```
executionFailed
```
field, which is not a supported public signal).
If the caller passed
```
"doNotPropagateError": true
```
on
```
:execute
```
, the API returns HTTP 200 with an
```
executionId
```
and places error details inside event parameters instead of returning an HTTP error.
A duplicate
```
requestId
```
on
```
:execute
```
or
```
:schedule
```
returns the previous execution's response without running a new execution.
Task failure policies (
```
IGNORE
```
and
```
NONE
```
) allow an integration to continue or finish as
```
SUCCEEDED
```
down an alternate branch even when an individual task failed.

List executions for the integration (use

INTEGRATION_NAME

to search across all integrations in the region; the discovery doc does not specify whether

orderBy=create_time

sorts ascending or descending, so add a

CreateTimestamp

filter or paginate with

pageToken

if needed):

bash

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"

Once you have the

EXECUTION_ID

, fetch its full

ExecutionDetails

and per-task states (use

filter

snapshotMetadataWithoutParams=true

, and

readMask

executions.list

—never the deprecated

truncateParams

[UI-only] or

filterParams.*

[internal-only] parameters):

bash

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"

To filter

executions.list

by state, use the

state

field (

!=

) with unquoted

ExecutionDetails.state

values (for example,

filter=state=FAILED

filter=state!=SUCCEEDED

filter=state=CANCELLED

, or

filter=state=FAILED OR state=CANCELLED

, URL-encoded as

filter=state%3DFAILED

filter=state%3DFAILED%20OR%20state%3DCANCELLED

); use

state

(not

eventExecutionState

, as shown on the REST reference page, or

event_execution_state

in the API reference's filter description), and use the supported filter keys (

execution_id

state

update_time

workflow_name

trigger_id

CreateTimestamp

parameter_type

)—camelCase variants such as

executionId

are not supported even though some docs examples show them.

不要把

:execute

返回的 HTTP 200 状态当作所有 task 均成功的证据（注意：v1 REST API 中也存在

integrations:test

，但其必需的

TestIntegrationsRequest.clientId

值没有公开文档，因此不要自行编造；可将该版本发布到非生产项目，然后调用

:execute

进行测试）。作为诊断规则，始终应检查 response payload 和 execution record，原因如下：

必需的验证依据是
```
executions.list?filter=execution_id="EXECUTION_ID"
```
返回的 execution record——检查
```
executionDetails.state
```
、每个 task 的
```
taskExecutionState
```
，以及
```
responseParameters
```
中的
```
ErrorInfo
```
（不要依赖旧版或已弃用的
```
executionFailed
```
字段，因为它不是受支持的公开信号）。
如果调用方在
```
:execute
```
中传入
```
"doNotPropagateError": true
```
，API 会返回 HTTP 200 和
```
executionId
```
，并将错误详情放入 event parameter，而不是返回 HTTP error。
在
```
:execute
```
或
```
:schedule
```
中使用重复的
```
requestId
```
，会返回上一次 execution 的 response，而不会启动新的 execution。
Task failure policy（
```
IGNORE
```
和
```
NONE
```
）允许 integration 沿备用分支继续执行或最终为
```
SUCCEEDED
```
，即使某个 task 已失败。

列出该 integration 的 execution（使用

作为

INTEGRATION_NAME

可搜索该 region 中的所有 integration；discovery doc 未说明

orderBy=create_time

按升序还是降序排序，因此必要时添加

CreateTimestamp

filter，或使用

pageToken

分页）：

bash

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

和各 task 状态（在

executions.list

上使用

filter

、

snapshotMetadataWithoutParams=true

和

readMask

——切勿使用已弃用的

truncateParams

［仅限 UI］或

filterParams.*

［仅限内部］参数）：

bash

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

，请使用

state

字段（

或

!=

）和未加引号的

ExecutionDetails.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

）；请使用

state

，而不是 REST reference page 中所示的

eventExecutionState

，也不要使用 API reference 的 filter description 中的

event_execution_state

；支持的 filter key 为（

execution_id

、

state

、

update_time

、

workflow_name

、

trigger_id

、

CreateTimestamp

、

parameter_type

）——即使部分文档示例显示为 camelCase 变体（如

executionId

），也不受支持。

Step 2: What If No Execution Record Exists?

第 2 步：如果没有 Execution Record 怎么办？

executions.list

returns no matching run, check these five causes before assuming the trigger never fired:

Cause	Symptom	What to verify
Wrong region	Empty list in `LOCATION`	Check `https://console.cloud.google.com/integrations` or list integrations in other regions.
API trigger 403	Caller got HTTP 403 `PERMISSION_DENIED`	API trigger auth denials fail before execution creation; nothing is written to execution logs. Check caller IAM and `roles/iam.serviceAccountUser` on the run-as service account.
API trigger payload > 8 MB	Caller got an error	Cumulative API trigger input variables exceed the 8 MB limit, so the integration does not start.
Local logging disabled	Integration ran, but logs are empty	Check `IntegrationVersion.databasePersistencePolicy` ( `DATABASE_PERSISTENCE_DISABLED` = `Disable` ; `DATABASE_PERSISTENCE_POLICY_UNSPECIFIED` = `Enable (sync)` , the API default; `DATABASE_PERSISTENCE_ASYNC` = `Enable (async)` , the console default). Also, if total integration data exceeds 10 MB (up to the 30 MB limit), local logging is disabled automatically.
Version not `ACTIVE`	Trigger never fires	Only an `ACTIVE` (published) version runs from triggers. After publishing, an older version can keep serving for up to 10 minutes due to eventual consistency.

如果

executions.list

没有返回匹配的 run，在假定 trigger 从未触发之前，先检查以下五种原因：

原因	症状	检查内容
Region 错误	`LOCATION` 中返回空列表	检查 `https://console.cloud.google.com/integrations` ，或列出其他 region 中的 integration。
API trigger 403	调用方收到 HTTP 403 `PERMISSION_DENIED`	API trigger 的身份验证拒绝发生在创建 execution 之前；不会向 execution log 写入任何内容。检查调用方 IAM，以及 run-as service account 上的 `roles/iam.serviceAccountUser` 。
API trigger payload > 8 MB	调用方收到错误	API trigger 输入变量的累计大小超过 8 MB 上限，因此 integration 不会启动。
本地日志记录已禁用	Integration 已运行，但日志为空	检查 `IntegrationVersion.databasePersistencePolicy` （ `DATABASE_PERSISTENCE_DISABLED` = `Disable` ； `DATABASE_PERSISTENCE_POLICY_UNSPECIFIED` = `Enable (sync)` ，即 API 默认值； `DATABASE_PERSISTENCE_ASYNC` = `Enable (async)` ，即控制台默认值）。此外，如果 integration 数据总量超过 10 MB（上限为 30 MB），本地日志记录会自动禁用。
Version 不是 `ACTIVE`	Trigger 从不触发	只有 `ACTIVE` （已发布）version 才能由 trigger 运行。发布后，由于最终一致性，旧 version 最多可能继续提供服务 10 分钟。

Step 3: Branch by Execution State (

ExecutionDetails.state

)

第 3 步：根据 Execution State（

ExecutionDetails.state

）分支处理

See Execution States for the full state reference, task-level states (

TaskExecutionDetails.taskExecutionState

), filter syntax, and cancel/replay rules.

`ExecutionDetails.state`	Console status	Meaning and next step
`FAILED`	Failed	Check `ErrorInfo` ( `message` , `code` ) in `responseParameters` , inspect the failing task's `taskExecutionState` ( `FAILED` or `FATAL` ), and run Step 4 ( `:troubleshoot` and Cloud Logging).
`SUCCEEDED`	Succeeded	If expected work did not happen, inspect `taskExecutionDetails` for tasks in `SKIPPED` (edge condition false) or `FAILED` (masked by `IGNORE` or `NONE` retry strategy).
`CANCELLED`	Canceled	User canceled the run, a new integration version was published while the run was suspended, a SYNC run hit the 2-minute timeout, or a replayed run hit the 10-minute deadline.
`SUSPENDED`	Suspended	Waiting on an Approval task (resolvable in the Cloud console UI or via `suspensions:resolve` ) or a Suspend task (resumable via `suspensions:lift` ). See Suspensions.
`RETRY_ON_HOLD`	Retry on hold	A task or integration failed with a temporary error and is waiting in the backoff retry queue.
`PROCESSING`	In process	Currently running. Check whether an ASYNC run is approaching the 10-minute timeout.
`PENDING`	On hold	Scheduled or temporarily paused and waiting to be triggered.

有关完整的 state 参考、task-level state（

TaskExecutionDetails.taskExecutionState

）、filter syntax 和 cancel/replay 规则，请参阅 Execution States。

`ExecutionDetails.state`	控制台状态	含义与后续操作
`FAILED`	失败	检查 `responseParameters` 中的 `ErrorInfo` （ `message` 、 `code` ），检查失败 task 的 `taskExecutionState` （ `FAILED` 或 `FATAL` ），并执行第 4 步（ `:troubleshoot` 和 Cloud Logging）。
`SUCCEEDED`	成功	如果预期工作没有发生，检查 `taskExecutionDetails` 中状态为 `SKIPPED` （edge condition 为 false）或 `FAILED` （被 `IGNORE` 或 `NONE` retry strategy 掩盖）的 task。
`CANCELLED`	已取消	用户取消了 run；在 run 处于 suspended 期间发布了新的 integration version；SYNC run 达到 2 分钟超时；或重放的 run 达到 10 分钟期限。
`SUSPENDED`	已暂停	正在等待 Approval task（可在 Cloud console UI 或通过 `suspensions:resolve` 解决），或正在等待 Suspend task（可通过 `suspensions:lift` 恢复）。请参阅 Suspensions。
`RETRY_ON_HOLD`	重试暂挂	Task 或 integration 因临时错误失败，正在等待 backoff retry queue。
`PROCESSING`	处理中	当前正在运行。检查 ASYNC run 是否即将达到 10 分钟超时。
`PENDING`	暂挂	已调度或暂时暂停，正在等待触发。

Step 4: Inspect Logs, AI Root Cause, and Subsystem Health

第 4 步：检查日志、AI Root Cause 和子系统健康状况

Run AI Troubleshoot (v2 REST API) on a failed execution to get a structured root-cause summary (requires

integrations.executions.get

bash

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"

Query Cloud Logging if Cloud Logging was enabled on the version. Note that Cloud Logging is disabled by default and writes nothing if local logging is disabled. See Logging and Monitoring for how to enable it, severity behavior, and exact queries.
bash
```
gcloud logging read \
  'resource.type="integrations.googleapis.com/IntegrationVersion" AND jsonPayload.executionId="EXECUTION_ID"' \
  --project="PROJECT_ID" --limit=20 --format=json
```

If a Connectors task failed, do not guess whether the connector or IAM is at fault. Inspect the connection resource (

connections.get

) and its schema metadata (

GET .../connections/CONNECTION_NAME/connectionSchemaMetadata

for

state

and

errorMessage

, and runtime v2

GET .../v2/.../connections/CONNECTION_NAME/actions

and

.../entityTypes

for listing—v1

connectionSchemaMetadata:listActions

and

:listEntityTypes

require a

filter

and reject unfiltered calls). See Connectors Health for connection states, schema metadata checks, and node throttling (HTTP 429).

bash

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"

If an IAM (403), run-as service account, timeout, or quota error occurred, check both the caller's role and the integration's run-as service account. Integrations created on or after October 15, 2026 with any trigger other than an API or Private trigger (for example Schedule, Cloud Scheduler, Cloud Pub/Sub, Salesforce, or Connector Event; Private triggers are exempt like API triggers, so a sub-integration whose only trigger is Private can be published without
```
runAsServiceAccount
```
) cannot be tested or published unless
```
runAsServiceAccount
```
is set; whenever
```
runAsServiceAccount
```
is set, the user publishing or testing the version needs
```
roles/iam.serviceAccountUser
```
on it. See Common Errors for the two-sided 403 checklist, error codes, task limits, and ADK
```
ApplicationIntegrationToolset
```
errors.

对失败的 execution 运行 AI Troubleshoot（v2 REST API），以获得结构化 root cause summary（需要

integrations.executions.get

）：

bash

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"

如果 version 启用了 Cloud Logging，则查询 Cloud Logging。 注意，Cloud Logging 默认禁用，如果本地日志记录已禁用，也不会写入任何内容。有关如何启用、严重级别行为和精确查询，请参阅 Logging and Monitoring。
bash
```
gcloud logging read \
  'resource.type="integrations.googleapis.com/IntegrationVersion" AND jsonPayload.executionId="EXECUTION_ID"' \
  --project="PROJECT_ID" --limit=20 --format=json
```

如果 Connectors task 失败，不要猜测是 connector 还是 IAM 的问题。 检查 connection resource（

connections.get

）及其 schema metadata（通过

GET .../connections/CONNECTION_NAME/connectionSchemaMetadata

获取

state

和

errorMessage

，并通过 runtime v2

GET .../v2/.../connections/CONNECTION_NAME/actions

和

.../entityTypes

进行列出——v1

connectionSchemaMetadata:listActions

和

:listEntityTypes

要求提供

filter

，不接受无 filter 的调用）。有关 connection state、schema metadata check 和 node throttling（HTTP 429），请参阅 Connectors Health。

bash

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"

如果发生 IAM（403）、run-as service account、timeout 或 quota 错误，应同时检查调用方的 role 和 integration 的 run-as service account。 对于在 2026 年 10 月 15 日或之后创建、除 API 或 Private trigger 外还包含其他 trigger 的 integration（例如 Schedule、Cloud Scheduler、Cloud Pub/Sub、Salesforce 或 Connector Event；Private trigger 与 API trigger 一样豁免，因此仅以 Private trigger 为唯一 trigger 的 sub-integration 无需设置
```
runAsServiceAccount
```
即可发布），如果未设置
```
runAsServiceAccount
```
，则无法测试或发布；只要设置了
```
runAsServiceAccount
```
，发布或测试该 version 的用户就需要拥有它的
```
roles/iam.serviceAccountUser
```
。有关双方 403 检查清单、错误代码、task limit 和 ADK
```
ApplicationIntegrationToolset
```
错误，请参阅 Common Errors。

Common Diagnostic Scenarios

常见诊断场景

Scenario A: Failed Connectors Task (Connection Health vs Caller IAM)

场景 A：Connectors task 失败（Connection Health 与调用方 IAM）

Run

connections.get

with

view=FULL

(command above) and inspect

status.state

and

status.status

If
status.state
is
ERROR
or
AUTHORIZATION_REQUIRED
: the connection itself cannot reach or authenticate to the target backend. Fix the connection's credentials in Secret Manager or the Cloud console (
```
https://console.cloud.google.com/connectors/connections
```
). If the connection uses a service account in another project, verify
```
service-PROJECT_NUMBER@gcp-sa-connectors.iam.gserviceaccount.com
```
has
```
roles/iam.serviceAccountTokenCreator
```
in that project.
If
status.state
is
ACTIVE
: the connection is healthy. Check whether the identity running the task (the integration's
```
runAsServiceAccount
```
, or if unset,
```
service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com
```
) has a required Integration Connectors role (such as
```
roles/connectors.invoker
```
or
```
roles/connectors.admin
```
) in the connection's project.
If the task failed with HTTP 429: the connection exceeded its provisioned nodes. Raise min/max nodes on the connection and add a task retry strategy (
```
EXPONENTIAL_BACKOFF
```
).

Trace the exact connector attempt in Cloud Logging (when connector logging is enabled on the connection):

bash

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

使用
```
view=FULL
```
运行
```
connections.get
```
（使用上面的命令），并检查
```
status.state
```
和
```
status.status
```
。
如果
status.state
为
ERROR
或
AUTHORIZATION_REQUIRED
： connection 本身无法访问目标 backend 或无法向其完成身份验证。在 Secret Manager 或 Cloud console（
```
https://console.cloud.google.com/connectors/connections
```
）中修复 connection 的凭据。如果 connection 使用另一个项目中的 service account，请验证
```
service-PROJECT_NUMBER@gcp-sa-connectors.iam.gserviceaccount.com
```
在该项目中拥有
```
roles/iam.serviceAccountTokenCreator
```
。
如果
status.state
为
ACTIVE
： connection 处于健康状态。检查运行该 task 的 identity（integration 的
```
runAsServiceAccount
```
；如果未设置，则为
```
service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com
```
）是否在 connection 所在项目中拥有所需的 Integration Connectors role，例如
```
roles/connectors.invoker
```
或
```
roles/connectors.admin
```
。
如果 task 因 HTTP 429 失败： connection 超过了其配置的 node 数量。提高 connection 上的 min/max node，并为 task 添加 retry strategy（
```
EXPONENTIAL_BACKOFF
```
）。

在 Cloud Logging 中追踪确切的 connector attempt（前提是 connection 已启用 connector logging）：

bash

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

Scenario B: Stuck in

SUSPENDED

(Approval vs Suspend Task)

场景 B：卡在

SUSPENDED

状态（Approval 与 Suspend Task）

Identify which task paused the execution from

taskExecutionDetails

and list pending suspensions (read-only; requires

integrations.suspensions.list

, included in

roles/integrations.suspensionResolver

) to find

SUSPENSION_ID

and

taskId

. Note that

roles/integrations.suspensionResolver

alone cannot read execution records (no

integrations.executions.list

integrations.executions.get

, returning HTTP 403 on

executions.list

and v2

:troubleshoot

); to inspect

taskExecutionDetails

(or run

:troubleshoot

), also grant

roles/integrations.integrationViewer

(or use the approval email link, which carries the execution and task IDs). See Suspensions for full details.

bash

# 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"

Approval task: can be approved or rejected in the Cloud console UI or via the REST API (

POST https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/executions/EXECUTION_ID/suspensions/SUSPENSION_ID:resolve

with body

{"suspension": {"eventExecutionInfoId": "EXECUTION_ID", "integration": "INTEGRATION_NAME", "taskId": "TASK_ID", "state": "LIFTED"}}

"REJECTED"

—the same call the console Approve/Reject buttons make). Always confirm with the user before resolving. Verify the caller holds

integrations.suspensions.resolve

(included in

roles/integrations.suspensionResolver

, which is not included in

roles/integrations.integrationEditor

) and

roles/iam.serviceAccountUser

on the integration's

runAsServiceAccount

. Without

roles/iam.serviceAccountUser

, approving leaves the execution paused until it expires.

Suspend task:

:lift

is the Suspend-task variant and requires

integrations.suspensions.lift

(included in

roles/integrations.suspensionResolver

) plus

roles/iam.serviceAccountUser

on the integration's

runAsServiceAccount

. After user confirmation, call

POST .../executions/EXECUTION_ID/suspensions/SUSPENSION_ID:lift

with an optional

suspensionResult

Watch out for version publish cancellation: publishing a new version of an integration automatically cancels all suspended executions of the previous version.

从

taskExecutionDetails

中确定是哪个 task 暂停了 execution，并列出 pending suspension（只读；需要

integrations.suspensions.list

，该权限包含于

roles/integrations.suspensionResolver

），以找到

SUSPENSION_ID

和

taskId

。注意，仅有

roles/integrations.suspensionResolver

无法读取 execution record（没有

integrations.executions.list

或

integrations.executions.get

，调用

executions.list

和 v2

:troubleshoot

时会返回 HTTP 403）；要检查

taskExecutionDetails

（或运行

:troubleshoot

），还应授予

roles/integrations.integrationViewer

（或使用 approval email link，其中包含 execution 和 task ID）。有关完整详情，请参阅 Suspensions。

bash

# 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"

Approval task： 可在 Cloud console UI 中批准或拒绝，也可通过 REST API（

POST https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/executions/EXECUTION_ID/suspensions/SUSPENSION_ID:resolve

，body 为

{"suspension": {"eventExecutionInfoId": "EXECUTION_ID", "integration": "INTEGRATION_NAME", "taskId": "TASK_ID", "state": "LIFTED"}}

或

"REJECTED"

——与控制台 Approve/Reject 按钮执行的调用相同）完成。解决前始终与用户确认。验证调用方持有

integrations.suspensions.resolve

（包含于

roles/integrations.suspensionResolver

，但不包含于

roles/integrations.integrationEditor

）并且对 integration 的

runAsServiceAccount

拥有

roles/iam.serviceAccountUser

。如果没有

roles/iam.serviceAccountUser

，批准后 execution 仍会暂停，直至过期。

Suspend task：

:lift

是 Suspend task 对应的操作，需要

integrations.suspensions.lift

（包含于

roles/integrations.suspensionResolver

），并且需要对 integration 的

runAsServiceAccount

拥有

roles/iam.serviceAccountUser

。获得用户确认后，调用

POST .../executions/EXECUTION_ID/suspensions/SUSPENSION_ID:lift

，并按需提供

suspensionResult

。

注意 version 发布导致的取消： 发布 integration 的新 version 会自动取消上一个 version 的所有 suspended execution。

Scenario C: HTTP 403

PERMISSION_DENIED

on Trigger, Test, or Publish

场景 C：Trigger、测试或发布时出现 HTTP 403

PERMISSION_DENIED

Application Integration enforces two independent permission checks:

Caller IAM check: the caller needs permission on the integration (

roles/integrations.integrationInvoker

to invoke,

roles/integrations.integrationEditor

to edit/test,

roles/integrations.integrationDeployer

roles/integrations.integrationEditor

to publish).

Run-as service account check: whenever
```
runAsServiceAccount
```
is set on the version, the user (or principal) publishing or testing the version needs
```
roles/iam.serviceAccountUser
```
on
```
runAsServiceAccount
```
at publish/test time, and at runtime the invoking caller or trigger service account needs
```
roles/iam.serviceAccountUser
```
on
```
runAsServiceAccount
```
(granted in the project that owns the service account). In addition,
```
runAsServiceAccount
```
needs roles on downstream Google Cloud resources.

Check both bindings before retrying. For Pub/Sub, Eventarc, and Connector Event triggers, a run-as service account (

roles/iam.serviceAccountUser

) denial records a failed execution and the event is not redelivered.

Application Integration 会执行两项相互独立的权限检查：

调用方 IAM 检查： 调用方需要对 integration 拥有相应权限（

roles/integrations.integrationInvoker

用于调用，

roles/integrations.integrationEditor

用于编辑或测试，

roles/integrations.integrationDeployer

或

roles/integrations.integrationEditor

用于发布）。

Run-as service account 检查： 只要 version 设置了
```
runAsServiceAccount
```
，发布或测试该 version 的用户（或 principal）在发布或测试时就需要对该
```
runAsServiceAccount
```
拥有
```
roles/iam.serviceAccountUser
```
；在运行时，调用 execution 的 principal 或 trigger service account 需要拥有该
```
roles/iam.serviceAccountUser
```
（授予 service account 所在的项目）。此外，
```
runAsServiceAccount
```
还需要拥有下游 Google Cloud resource 所需的 role。

重试前请检查两项 binding。对于 Pub/Sub、Eventarc 和 Connector Event trigger，run-as service account（

roles/iam.serviceAccountUser

）拒绝会记录失败的 execution，并且 event 不会重新投递。

Recovery Actions (Require User Confirmation)

恢复操作（需要用户确认）

Always display the exact command and obtain user confirmation before running

:cancel

:replay

:lift

, or

:resolve

:cancel

requires

integrations.executions.cancel

and

:replay

requires

integrations.executions.replay

(both are held by

roles/integrations.integrationInvoker

roles/integrations.integrationEditor

, and

roles/integrations.integrationAdmin

—not by

roles/integrations.suspensionResolver

roles/integrations.integrationViewer

, so approvers with only

roles/integrations.suspensionResolver

cannot cancel a stuck

SUSPENDED

run).

:replay

also enforces two preconditions that return

FAILED_PRECONDITION

: (a) test-case runs cannot be replayed in any mode (

"Test runs cannot be replayed."

), and (b)

REPLAY_MODE_POINT_OF_FAILURE

is refused for executions that ran with database persistence (local logging /

databasePersistencePolicy: DATABASE_PERSISTENCE_DISABLED

) disabled because it needs execution snapshots—use

REPLAY_MODE_FROM_BEGINNING

in that case. When overriding inputs on

:replay

with

modifiedParameters

and

updateMask

, list every overridden key in

updateMask

; without

updateMask

, all original inputs are discarded and only

modifiedParameters

are used, and a key in

updateMask

missing from

modifiedParameters

is an error.

bash

undefined

在运行

: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

的 approver 无法取消卡在

SUSPENDED

状态的 run）。

:replay

还会强制执行两项前置条件，若不满足会返回

FAILED_PRECONDITION

：（a）test-case run 在任何模式下都不能重放（

"Test runs cannot be replayed."

）；（b）对于运行期间禁用了 database persistence（local logging /

databasePersistencePolicy: DATABASE_PERSISTENCE_DISABLED

）的 execution，由于重放需要 execution snapshot，因此会拒绝

REPLAY_MODE_POINT_OF_FAILURE

——此时应使用

REPLAY_MODE_FROM_BEGINNING

。在

:replay

中使用

modifiedParameters

和

updateMask

覆盖输入时，必须在

updateMask

中列出每个被覆盖的 key；如果没有

updateMask

，所有原始输入都会被丢弃，仅使用

modifiedParameters

；若

updateMask

中某个 key 未出现在

modifiedParameters

中，则会报错。

bash

undefined

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"

undefined

undefined

Reference Files

Load the matching reference file when you need deeper details, exact field names, or edge-case checks:

Execution States:
```
ExecutionDetails.state
```
and
```
TaskExecutionDetails.taskExecutionState
```
enums,
```
executions.list
```
filter operators, large-log workarounds (> 300 MB), and
```
:cancel
```
/
```
:replay
```
constraints.
Logging and Monitoring: Local logging vs Cloud Logging interactions, enabling Cloud Logging on a draft version, Logs Explorer queries,
```
integrations.googleapis.com/*
```
and
```
connectors.googleapis.com/*
```
metric schemas, and alerting setup.
Common Errors: HTTP/gRPC error codes, the two-sided 403 checklist, the October 15, 2026 run-as service account requirement, task-level limits and gotchas, and ADK
```
ApplicationIntegrationToolset
```
errors.
Connectors Health:
```
ConnectionStatus.state
```
,
```
EventingStatus.state
```
,
```
connectionSchemaMetadata
```
probes, runtime v2 readiness calls, node throttling (HTTP 429), and separating connection auth from caller IAM.
Suspensions: Suspend vs Approval vs Timer behavior,
```
suspensions.list
```
/
```
:lift
```
/
```
:resolve
```
payloads, expiration settings, and why approvals stay stuck without
```
roles/iam.serviceAccountUser
```
.

在需要更深入的信息、准确字段名或边界检查时，加载对应的 reference file：

Execution States：
```
ExecutionDetails.state
```
和
```
TaskExecutionDetails.taskExecutionState
```
enum、
```
executions.list
```
filter operator、大日志处理方案（> 300 MB），以及
```
:cancel
```
/
```
:replay
```
约束。
Logging and Monitoring：Local logging 与 Cloud Logging 的交互、在 draft version 上启用 Cloud Logging、Logs Explorer query、
```
integrations.googleapis.com/*
```
和
```
connectors.googleapis.com/*
```
metric schema，以及 alert 设置。
Common Errors：HTTP/gRPC error code、双方 403 检查清单、2026 年 10 月 15 日的 run-as service account 要求、task-level limit 和注意事项，以及 ADK
```
ApplicationIntegrationToolset
```
错误。
Connectors Health：
```
ConnectionStatus.state
```
、
```
EventingStatus.state
```
、
```
connectionSchemaMetadata
```
probe、runtime v2 readiness call、node throttling（HTTP 429），以及区分 connection auth 与调用方 IAM。
Suspensions：Suspend、Approval 和 Timer 行为，
```
suspensions.list
```
/
```
:lift
```
/
```
:resolve
```
payload、expiration setting，以及 approval 为何会在缺少
```
roles/iam.serviceAccountUser
```
时一直卡住。

application-integration-troubleshooting

Original

Translation

Application Integration Troubleshooting

Application Integration 故障排查

Tooling and Scope Boundaries

工具与范围边界

Safety and Confirmation Rules

安全与确认规则

Prerequisites and Setup Check

前置条件与设置检查

Verify active identity and project

Verify active identity and project

Check that required APIs are enabled on PROJECT_ID

Check that required APIs are enabled on PROJECT_ID

Diagnostic Decision Flow

诊断决策流程

Step 1: Confirm Whether an Execution Ran and Check Its True State

第 1 步：确认 Execution 是否运行并检查其真实状态

Step 2: What If No Execution Record Exists?

第 2 步：如果没有 Execution Record 怎么办？

Step 3: Branch by Execution State (ExecutionDetails.state)

第 3 步：根据 Execution State（ExecutionDetails.state）分支处理

Step 4: Inspect Logs, AI Root Cause, and Subsystem Health

第 4 步：检查日志、AI Root Cause 和子系统健康状况

Common Diagnostic Scenarios

常见诊断场景

Scenario A: Failed Connectors Task (Connection Health vs Caller IAM)

场景 A：Connectors task 失败（Connection Health 与调用方 IAM）

Scenario B: Stuck in SUSPENDED (Approval vs Suspend Task)

场景 B：卡在 SUSPENDED 状态（Approval 与 Suspend Task）

Scenario C: HTTP 403 PERMISSION_DENIED on Trigger, Test, or Publish

场景 C：Trigger、测试或发布时出现 HTTP 403 PERMISSION_DENIED

Recovery Actions (Require User Confirmation)

恢复操作（需要用户确认）

Cancel an execution in PENDING (console "On hold"), RETRY_ON_HOLD, or SUSPENDED state (requires integrations.executions.cancel)

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)

(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)

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)

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)

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

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

Reference Files

Reference Files

Step 3: Branch by Execution State (
`ExecutionDetails.state`
)

第 3 步：根据 Execution State（
`ExecutionDetails.state`
）分支处理

Scenario B: Stuck in
`SUSPENDED`
(Approval vs Suspend Task)

场景 B：卡在
`SUSPENDED`
状态（Approval 与 Suspend Task）

Scenario C: HTTP 403
`PERMISSION_DENIED`
on Trigger, Test, or Publish

场景 C：Trigger、测试或发布时出现 HTTP 403
`PERMISSION_DENIED`