application-integration-basics

Application Integration 基础知识

Application Integration 是 Google Cloud 提供的无服务器、自动扩缩的集成平台即服务（iPaaS），用于连接 Google Cloud 服务和第三方 SaaS 应用。它运行由触发器、任务、数据映射和 Integration Connectors 连接组成的事件驱动型工作流，无需你管理服务器。使用此技能可判断 Application Integration 是否适合某项工作负载，设置项目和区域，配置 IAM 和运行身份服务账号，选择合适的 API 或工具接口，并围绕平台限制进行设计。

何时使用 Application Integration，何时使用自定义粘合代码

适合选择 Application Integration 的情况……	适合选择自定义代码（Cloud Run / Cloud Functions）的情况……
通过预构建的 Integration Connectors 连接 SaaS 应用（CRM、ERP、数据库、Google Cloud 服务）。	需要亚秒级延迟或自定义二进制协议。
编排由 API、Pub/Sub、Cloud Scheduler、Salesforce 或 Connector Event 触发器启动的事件驱动型工作流。	工作流数据总量超过 30 MB（API 触发器输入和 Connector 载荷的上限为 8 MB）。
使用 Data Mapping 或 Jsonnet 以可视化方式转换 JSON/数组数据，无需部署容器。	同步运行时间超过 2 分钟，或异步运行时间超过 10 分钟。
暂停工作流以供人工审核（使用 Approval 或 Suspend 任务，最长可暂停 31 天）。	必须直接调用仅限 VPC 的 HTTP 端点，且不使用 Private Service Connect 连接器（Call REST Endpoint 只能访问公共互联网）。
将企业工作流或连接器作为工具，通过 ADK ApplicationIntegrationToolset 提供给 AI Agent。	需要任意语言的软件包，或超出 JavaScript（V8）或 Jsonnet 任务能力范围的大量内存计算。

安全与确认规则

• 只读检查可直接运行：你可以直接运行 gcloud services list、gcloud projects get-iam-policy，以及对 https://integrations.googleapis.com/v1/... 或 https://connectors.googleapis.com/v1/... 发起 HTTP GET 请求，无需事先询问。
• 任何状态变更都必须获得用户明确确认：在执行以下操作前，务必展示确切的命令或请求载荷，并等待用户批准：
  • 启用 API（gcloud services enable）。
  • 配置区域（clients:provision 或针对 google_integrations_client 执行 terraform apply），尤其是使用客户管理的加密密钥（CMEK）时，因为 区域启用 CMEK 后无法撤销。
  • 修改 IAM 政策（gcloud projects add-iam-policy-binding 或 gcloud iam service-accounts add-iam-policy-binding）。
  • 创建、上传、发布、取消发布、执行、测试或删除任何集成、版本、身份验证配置文件或连接。
• 绝不要将破坏性脚本打包执行，在无人值守的情况下删除集成、版本、身份验证配置文件或连接。
• 安装软件包（pip install）或更改全局 gcloud 设置（例如 gcloud config set auth/impersonate_service_account）前，先询问用户；务必先展示确切的命令。

选择接口

Application Integration 没有 gcloud integrations 命令组（也没有 gcloud connectors 命令组），并且没有 Google 管理的远程 MCP 服务。REST API 是主要的控制和执行接口。

接口	覆盖范围	身份验证
REST API（curl）	完整的 v1 接口：区域预配、集成、版本、下载/上传、发布、执行、计划、执行记录、挂起、authConfigs、模板。	Authorization: Bearer $(gcloud auth print-access-token)
Python discovery 客户端	通过 googleapiclient.discovery.build("integrations", "v1") 提供完整的 v1 接口（也可通过 build("integrations", "v2") 使用 v2；没有专用的 Cloud Client Library）。使用 pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3" 安装。	Application Default Credentials（gcloud auth application-default login）
Terraform（hashicorp/google）	仅限基础设施：google_integrations_client（区域设置）、google_integrations_auth_config 和 google_integration_connectors_*。不管理集成工作流版本。	ADC 或 Terraform 提供程序凭据
ADK（ApplicationIntegrationToolset）	将已发布的 API 触发器集成或 Integration Connectors 操作/实体作为工具提供给 ADK Agent（Python v0.1.0+、Java v0.3.0+）。	ADC（gcloud auth application-default login）或服务账号 JSON
Cloud 控制台	可视化拖放编辑器、快速/高级区域设置、审批任务处理、OAuth 2.0 授权码授权流程。	在浏览器中登录 Google Cloud

• gcloud 仅用于通用 Google Cloud 任务：启用 API（gcloud services enable）、打印访问令牌（gcloud auth print-access-token）、管理 IAM，以及读取 Cloud Logging（gcloud logging read）。
• Integration Connectors 包含一个出站 MCP 连接器（MCP v1 和 v2），可让工作流将外部 MCP 服务作为连接器目标调用；这是出站连接器，并非用于控制 Application Integration 的 Google 管理 MCP 服务。
• REST 调用始终统一使用全局端点 https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/...。
• 关于草稿测试（integrations:test）的说明：虽然 v1 REST API 中存在 POST .../integrations/INTEGRATION_NAME:test，但其必填的 TestIntegrationsRequest.clientId 值未公开文档说明，因此请勿自行编造；应将集成发布到非生产项目，然后调用 :execute 来测试。
• 有关身份验证设置、curl 命令、Python discovery 客户端用法模式和 ADK ApplicationIntegrationToolset 配置，请参阅 references/api-access.md。

逐步区域设置工作流

Application Integration 按区域部署：请在 Application Integration locations 中确认目标区域受支持；如果用户没有偏好，可使用支持良好的默认区域 us-central1。每个 REST 路径中的 LOCATION 都是该区域；Application Integration 不适用 gcloud 默认区域设置。预配按区域进行。预配 us-central1 不会预配 europe-west1；请在 PROJECT_ID 中使用的每个 LOCATION 重复进行区域预配。设置前，请确保 PROJECT_ID 关联了有效的结算账号——即使使用量处于每月免费额度内，也必须有有效的结算账号（请参阅 Application Integration pricing page）。

1. 检查并启用所需 API

首先检查已启用的 API（只读）：

gcloud services list --enabled --project=PROJECT_ID \
  --filter="config.name:(integrations.googleapis.com OR connectors.googleapis.com OR secretmanager.googleapis.com OR cloudkms.googleapis.com)"

获得用户确认后，启用所需的 API（仅在配置 CMEK 时添加 cloudkms.googleapis.com）：

gcloud services enable \
  integrations.googleapis.com \
  connectors.googleapis.com \
  secretmanager.googleapis.com \
  --project=PROJECT_ID

2. 验证调用方的 IAM 角色设置

设置 Application Integration 需要 roles/integrations.integrationAdmin、roles/connectors.admin 和 roles/editor（CMEK 还需要 roles/cloudkms.admin）。检查当前绑定（只读）：

gcloud projects get-iam-policy PROJECT_ID --format=json

3. 配置区域（LOCATION）

获得用户确认后，从以下三种受支持的方式中选择一种：

• 选项 A：REST（clients:provision）

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}' \
    "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clients:provision"
  

  配置成功时，响应为 {}（clients:provision 不会应用 runAsServiceAccount；请改为通过 IntegrationVersion.runAsServiceAccount 为每个集成版本设置运行身份）。如果区域已配置，响应也会是 {}；此调用不会更改现有区域的设置。要更改现有区域的 HTTP 调用或加密设置，请使用控制台的 Regions 页面（如果区域已处于 ACTIVE 状态，则 clients:provision 中的 cloudKmsConfig、enableHttpCall 和 enableManagedAiFeatures 不会生效）。如果 PROJECT_ID 已通过 Apigee Integration 注册，配置将失败。

• 选项 B：Cloud 控制台 打开 https://console.cloud.google.com/integrations，选择 LOCATION，然后点击 快速设置（启用 API、创建默认服务账号并使用 Google 管理的加密）或 高级设置（用于配置 CMEK、HTTP 调用、AI 功能、治理或变量遮蔽）。之后要添加其他区域，请前往 Regions > Provision new region。

• 选项 C：Terraform（google_integrations_client） 在 hashicorp/google 中使用 google_integrations_client 资源。不要在 google_integrations_client 上设置 run_as_service_account——此参数已在提供程序 v8.0.0（2026 年 8 月 26 日）中移除，而且它映射到 clients:provision 的 runAsServiceAccount 字段，该字段同样不会生效；请改为通过 IntegrationVersion.runAsServiceAccount 为每个集成版本设置运行身份。

4. 简单检查区域访问权限

对该区域运行只读列表调用；成功返回 200 OK 表示 API 很可能可在 LOCATION 中访问：

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

有关所有 ProvisionClientRequest 字段、CMEK 和治理选项，以及完整的 Terraform 示例，请参阅 references/provisioning-and-terraform.md。

核心概念一览

• 集成和触发器：集成是由一个或多个触发器启动的工作流。同步运行（SYNC）会等待完成并返回输出（integrations.execute、控制台测试、同步 Call Integration）。异步运行（ASYNC）则触发后即返回（integrations.schedule、Schedule、Cloud Scheduler、Cloud Pub/Sub、Salesforce 触发器，以及暂停或审批后恢复的运行）。
• 任务：触发器之后串联的工作单元（例如 Data Mapping、Call REST Endpoint、Connectors、V8 上的 JavaScript、Cloud Function、Approval、Suspend、Timer、循环和 Call Integration）。
• 版本和编辑锁：只有 DRAFT 版本可以编辑（上次更新后 15 分钟内锁定给其作者）。只有 ACTIVE（已发布）版本会由触发器运行。发布某个版本会自动取消发布之前的活动版本，并取消该旧版本的所有暂停执行。取消发布会将活动版本移至 SNAPSHOT（PREVIOUSLY_PUBLISHED）。调用 versions.delete 会将版本软删除为 ARCHIVED（在 Integration 版本文档页面中列为 DELETED）。
• 变量：
  • 集成变量：显式输入（IN）、输出（OUT）、IN_OUT，或类型为 IN_OUT_TYPE_UNSPECIFIED 的内部变量（$varName$）。
  • 任务变量：自动生成的任务输出，命名为 `Task_<taskId>_<variableName>`，其中 taskId 是 taskConfigs[].taskId 中不带修饰的任务编号（例如，taskId "1" -> $`Task_1_responseBody`$）。
  • 系统变量：键名以反引号括起（`ExecutionId`、`ExecutionMode`、`ErrorInfo` [message、code]、`IntegrationName`、`Region`、`ProjectId`）；引用时使用 $`ExecutionId`$（单独的 $ExecutionId$ 会被视为不存在的集成变量，导致失败）。
  • 配置变量（预览版）：在 integrationConfigParameters 中定义的环境特定值（默认值位于 parameter.defaultValue 中；草稿上的顶层 value 会被丢弃），并在发布时通过 configParameters 按环境提供（命名为 `CONFIG_<NAME>`；configParameters 中的键必须与 integrationConfigParameters 中的键完全一致，包括反引号，例如 "`CONFIG_target_url`"，因为未知键会被静默忽略——发布会返回 200，且保留默认值）。切勿在配置变量中存储密钥——这些变量会以纯文本形式导出。请改用身份验证配置文件（authConfigs）或 Secret Manager 任务。
• 暂停：Suspend 任务最多可暂停 31 天，并通过 Suspensions API（suspensions:lift，可选传入 suspensionResult，需要 integrations.suspensions.lift）恢复。Approval 任务会向审批者发送电子邮件，可在 Cloud 控制台界面中批准或拒绝，也可通过 suspensions:resolve 执行（state 为 "LIFTED" 或 "REJECTED"，需要 integrations.suspensions.resolve）。列出暂停项（suspensions.list）需要 integrations.suspensions.list。这三项权限都包含在 roles/integrations.suspensionResolver（以及 roles/integrations.integrationAdmin）中；恢复还需要在集成的运行身份服务账号上拥有 roles/iam.serviceAccountUser。在解除或处理暂停前，务必先征得用户同意。Timer 任务会自动恢复。
• 身份验证配置文件（authConfigs）：可重复使用的区域凭据记录（projects/PROJECT_ID/locations/LOCATION/authConfigs/AUTH_CONFIG_ID）。下载集成版本时不会包含这些记录。

有关版本状态、触发器类型、任务类别、变量、暂停和身份验证配置文件的完整详情，请参阅 references/core-concepts.md。

IAM 和运行身份服务账号要求

关键 IAM 角色和服务代理

• 开发者和运维人员角色：roles/integrations.integrationAdmin（拥有完整的 CRUD 权限，并可删除身份验证配置文件）、roles/integrations.integrationEditor（可创建、上传、编辑、测试、调用、取消、重放和发布，包括 integrations.integrationVersions.create 和 integrations.integrationVersions.deploy）、roles/integrations.integrationDeployer（通过 integrations.integrationVersions.deploy 发布/取消发布；拥有 list/get/deploy 权限，但没有 create 权限，因此可以发布现有版本，但无法上传）、roles/integrations.integrationInvoker（可调用、取消和重放）、roles/integrations.integrationViewer（查看集成和日志），以及 roles/integrations.suspensionResolver（列出、解除和处理暂停状态：integrations.suspensions.list、integrations.suspensions.lift、integrations.suspensions.resolve；仅有 suspensionResolver 角色无法读取执行记录，因此还需授予 roles/integrations.integrationViewer，以查看 taskExecutionDetails 或运行 :troubleshoot；也可以使用审批邮件链接，该链接包含执行 ID 和任务 ID）。
• 服务代理：
  • Application Integration 服务代理：service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com（已授予 roles/integrations.serviceAgent）。
  • Integration Connectors 服务代理：[email protected]（已授予 roles/connectors.serviceAgent）。

强制执行身份服务账号规则（自 2026 年 10 月 15 日起生效）

1. 必须指定明确的身份：对于在 2026 年 10 月 15 日或之后创建的集成（以及之后日期的现有集成），每次运行都需要明确的身份——可以是触发调用方，也可以是通过 IntegrationVersion.runAsServiceAccount 为每个集成版本设置的用户管理型执行身份服务账号（通过 clients:provision 配置区域时不会应用 runAsServiceAccount）。
2. API 或 Private 以外的触发器必须配置执行身份服务账号：对于在 2026 年 10 月 15 日或之后创建、且触发器不是 API 或 Private 的集成（例如 Schedule、Cloud Scheduler、Cloud Pub/Sub、Eventarc、Salesforce 或 Connector Event），除非设置了 runAsServiceAccount，否则无法测试或发布。Private 触发器与 API 触发器一样不受此要求限制，因此，唯一触发器为 Private 的子集成可以在不设置 runAsServiceAccount 的情况下发布。
3. 区域治理：如果区域启用了治理，则每个新集成和新版本都必须配置执行身份服务账号，包括由 API 触发的集成。
4. 服务账号用户（roles/iam.serviceAccountUser）：只要某个版本设置了 runAsServiceAccount，发布或测试该版本的用户（或主体）就必须在该服务账号（或其所属项目）上拥有 roles/iam.serviceAccountUser。在运行时，调用方或触发器服务账号，以及处理或解除暂停状态的任何人，也必须在该服务账号上拥有 roles/iam.serviceAccountUser。
5. 最佳做法：为每个集成创建一个专用且权限范围尽可能小的用户管理型服务账号。设置了 runAsServiceAccount 且未设置任务级身份验证配置文件时，它会为 Connector、Call REST Endpoint 和 Cloud Function 任务创建令牌（任务上的 OAuth 2.0 或 OIDC 身份验证配置文件优先于 runAsServiceAccount）。

请参阅 references/iam-and-service-accounts.md，了解完整的 IAM 角色表、服务代理权限、凭据优先级规则和 gcloud IAM 命令。

设计时需要考虑的关键配额和限制

限制	值	对设计的影响
SYNC 执行超时	2 分钟	对于耗时超过 2 分钟的工作流，请使用异步触发器或 integrations.schedule；同步运行超时后会变为 CANCELLED。
ASYNC 执行超时	10 分钟	如果单次异步运行耗时超过 10 分钟，请将繁重工作拆分为子集成或外部作业。
最长执行时长	31 天	包含在 Approval 或 Suspend 任务中暂停的时间（最长 44,640 分钟）。
集成数据总量	30 MB	由输入／输出变量和私有触发器子集成共享。超过 10 MB 后，本地日志记录将被禁用，重试会停止工作，监控也会跳过此次运行。
API 触发器输入大小	8 MB	所有输入变量的累计大小；更大的负载会在工作流启动前失败。
连接器数据量和超时	输入／输出 8 MB；超时 3 分钟	Application Integration 配额将通过连接发送／接收的数据累计量限制为 8 MB，连接器响应限制为 20 MB（Integration Connectors 配额将 Connectors 任务负载限制为 10 MB）；自定义查询限制为 180 秒和 50,000 行。
并发执行数	每个项目、每个区域 50 个；每个集成 10 个（默认值）	两项并发上限均可调整；单个集成出现突发流量时，会触及每个集成 10 个的上限，而非 50 个。执行请求速率配额可在项目的 Cloud Quotas 页面查看和调整。
集成／任务／版本	1,000／100／100	每个项目最多可有 1,000 个集成，每个集成最多可有 100 个任务和 100 个版本。
发布传播	最长 10 分钟	最终一致性：发布新版本后，旧版本仍可能继续运行最长 10 分钟。

有关所有特定任务的负载上限、循环迭代限制、Integration Connectors 节点限制和定价详情，请参阅 references/limits.md。

相关技能

• application-integration-basics（此技能）：概念、API 启用、区域配置、IAM 角色和运行身份服务账号、接口选项（REST、Python 客户端、Terraform、ADK）以及配额／限制。
• application-integration-authoring：通过 REST API 构建、上传、版本管理、配置变量、发布、执行和测试集成；触发器 ID；任务注意事项；以及通过下载／上传在项目间进行 CI/CD 晋级。
• application-integration-troubleshooting：诊断失败或卡住的执行，检查执行和任务状态及 ErrorInfo，列出和筛选执行，使用 Cloud Logging 和 Cloud Monitoring，处理暂停和审批，检查 Integration Connectors 连接健康状况，以及排查 IAM／运行身份／配额错误。

参考文件

• references/core-concepts.md：触发器、执行模式、任务类型、版本生命周期、编辑锁、变量、暂停和身份验证配置文件。
• references/iam-and-service-accounts.md：Application Integration 和 Integration Connectors 的预定义 IAM 角色、服务代理、运行身份服务账号规则以及 IAM 命令。
• references/provisioning-and-terraform.md：通过 REST clients:provision 按区域配置、Cloud 控制台快速／高级设置、CMEK 注意事项，以及 Terraform google_integrations_*／google_integration_connectors_* 资源。
• references/api-access.md：端点、身份验证、curl 示例、Python google-api-python-client 发现模式、ADK ApplicationIntegrationToolset，以及 MCP 连接器说明。
• references/limits.md：超时、负载上限、并发配额、循环／任务限制、Integration Connectors 限制以及定价层级。