application-integration-troubleshooting

Application Integration 故障排查

诊断并恢复运行失败、停滞或看似毫无响应的 Google Cloud Application Integration 执行。本技能将引导你核实执行状态、检查各任务的失败情况、查看 Cloud Logging 和 Cloud Monitoring、探测 Integration Connectors 健康状况、解决挂起问题，并检查 IAM 或配额。

工具与范围边界

• REST 是交互接口。 没有 gcloud integrations 命令组，也没有 Google 管理的 Application Integration MCP 服务。请使用 curl 搭配 gcloud auth print-access-token，或使用基于 discovery 的 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）。查询错误的区域会返回空结果。
• 相关技能：
  • 使用 application-integration-basics 了解产品概念、启用 API、配置区域、初始 IAM 角色和服务限额。
  • 使用 application-integration-authoring 创建草稿、编辑任务和触发器、配置变量、发布、编写 :execute 和 :schedule 负载，以及 CI/CD 导出/导入。

安全与确认规则

• 可直接执行只读检查： executions.list、suspensions.list、connections.get、connectionSchemaMetadata 获取调用、运行时 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 discovery 客户端（通过 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 会返回 HTTP 200 和一个 executionId，并将错误详情放在事件参数中，而不是返回 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，请对 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 参考页面中所示的 eventExecutionState，也不要使用 API 参考的过滤条件说明中的 event_execution_state），并使用受支持的过滤键（execution_id、state、update_time、workflow_name、trigger_id、CreateTimestamp、parameter_type）——即使某些文档示例中出现了驼峰形式，也不支持 executionId 等写法。

步骤 2：如果没有执行记录怎么办？

如果 executions.list 未返回匹配的运行记录，请先检查以下五种情况，再判断触发器从未触发：

原因	症状	检查内容
区域错误	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 默认处于停用状态，且如果本地日志记录已停用，则不会写入任何内容。有关如何启用 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）及其架构元数据（使用 GET .../connections/CONNECTION_NAME/connectionSchemaMetadata 检查 state 和 errorMessage；使用运行时 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；Private 触发器与 API 触发器一样不受此限制，因此仅有 Private 触发器的子集成可以在未设置 runAsServiceAccount 的情况下发布），除非设置了 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：**连接运行正常。请检查运行任务的身份（集成的 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。征得用户确认后，调用 POST .../executions/EXECUTION_ID/suspensions/SUSPENSION_ID:lift，并可选择传入 suspensionResult。
4. **注意版本发布取消执行：**发布集成的新版本会自动取消上一版本的所有挂起执行。

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

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

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：(a) 测试用例运行在任何模式下都无法重放（"Test runs cannot be replayed."）；(b) 对于运行时禁用了数据库持久化（本地日志记录 / databasePersistencePolicy: DATABASE_PERSISTENCE_DISABLED）的执行，不允许使用 REPLAY_MODE_POINT_OF_FAILURE，因为该模式需要执行快照——这种情况下请使用 REPLAY_MODE_FROM_BEGINNING。在使用 modifiedParameters 和 updateMask 覆盖 :replay 的输入时，请在 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 时审批会一直卡住的原因。