Back to Details

application-integration-basics

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Application Integration Basics

Application Integration 基础

Application Integration is Google Cloud's serverless, auto-scaling Integration-Platform-as-a-Service (iPaaS) for connecting Google Cloud services and third-party SaaS applications. It runs event-driven workflows made of triggers, tasks, data mappings, and Integration Connectors connections without requiring you to manage servers. Use this skill to decide whether Application Integration fits a workload, set up a project and region, configure IAM and run-as service accounts, choose the right API or tool interface, and design around platform limits.
Application Integration 是 Google Cloud 的无服务器、自动扩缩容 Integration-Platform-as-a-Service (iPaaS)，用于连接 Google Cloud 服务和第三方 SaaS 应用。它运行由触发器、任务、数据映射及 Integration Connectors 连接构成的事件驱动工作流，无需管理服务器。使用此 skill 可判断 Application Integration 是否适合某项工作负载、设置项目和区域、配置 IAM 及运行身份服务账户、选择合适的 API 或工具接口，并围绕平台限制进行设计。

When to Use Application Integration vs. Custom Glue Code

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

Choose Application Integration when...Choose custom code (Cloud Run / Cloud Functions) when...
Connecting SaaS apps (CRM, ERP, databases, Google Cloud services) via prebuilt Integration Connectors.You need sub-second latency or custom binary protocols.
Orchestrating event-driven workflows from API, Pub/Sub, Cloud Scheduler, Salesforce, or Connector Event triggers.Total workflow data exceeds 30 MB (or 8 MB for API trigger inputs and Connector payloads).
Transforming JSON/array data visually with Data Mapping or Jsonnet without deploying containers.Synchronous runs take longer than 2 minutes or asynchronous runs take longer than 10 minutes.
Pausing workflows for human review (
Approval
or 
Suspend
tasks up to 31 days).		You must call VPC-only HTTP endpoints directly without Private Service Connect connectors (Call REST Endpoint reaches the public internet only).
Exposing enterprise workflows or connectors as tools to AI agents via ADK 
ApplicationIntegrationToolset
.		You need arbitrary language packages or heavy in-memory compute beyond JavaScript (V8) or Jsonnet tasks.
在以下情况下选择 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/array 数据。同步运行超过 2 分钟或异步运行超过 10 分钟。
需要暂停工作流以供人工审核（
Approval
或 
Suspend
任务最长 31 天）。		必须直接调用仅限 VPC 的 HTTP 端点，且不能使用 Private Service Connect 连接器（Call REST Endpoint 只能访问公共互联网）。
需要通过 ADK 
ApplicationIntegrationToolset
将企业工作流或连接器公开为 AI Agent 工具。		需要 JavaScript (V8) 或 Jsonnet 任务之外的任意语言包，或需要高内存计算。

Safety and Confirmation Rules

安全与确认规则

  • Read-only checks run freely: You may run 
    gcloud services list
    , 
    gcloud projects get-iam-policy
    , and HTTP 
    GET
    calls to 
    https://integrations.googleapis.com/v1/...
    or 
    https://connectors.googleapis.com/v1/...
    without asking first.
  • Require explicit user confirmation before any state change: Always show the exact command or request payload and wait for user approval before:
    • Enabling APIs (
      gcloud services enable
      ).
    • Provisioning a region (
      clients:provision
      or 
      terraform apply
      on 
      google_integrations_client
      ), especially with Customer-Managed Encryption Keys (CMEK), because enabling CMEK for a region cannot be undone.
    • Modifying IAM policies (
      gcloud projects add-iam-policy-binding
      or 
      gcloud iam service-accounts add-iam-policy-binding
      ).
    • Creating, uploading, publishing, unpublishing, executing, testing, or deleting any integration, version, auth profile, or connection.
  • Never bundle destructive scripts that delete integrations, versions, auth profiles, or connections unattended.
  • Ask the user before installing packages (
    pip install
    ) or changing global gcloud settings such as 
    gcloud config set auth/impersonate_service_account
    ; show the exact command first.
  • 只读检查可直接执行：无需事先询问，即可运行 
    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
      ），尤其是使用 Customer-Managed Encryption Keys (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
    ）前，先询问用户；并先显示准确的命令。

Choosing the Interface

选择接口

Application Integration has no 
gcloud integrations
command group (and no 
gcloud connectors
command group), and no Google-managed remote MCP server. The REST API is the primary control and execution interface.
InterfaceWhat it coversAuthentication
REST API (
curl
)		Full v1 surface: region provisioning, integrations, versions, download/upload, publish, execute, schedule, executions, suspensions, authConfigs, templates.
Authorization: Bearer $(gcloud auth print-access-token)
Python discovery clientFull v1 surface via 
googleapiclient.discovery.build("integrations", "v1")
(and v2 via 
build("integrations", "v2")
; no dedicated Cloud Client Library exists). Install with 
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
)		Infrastructure only: 
google_integrations_client
(region setup), 
google_integrations_auth_config
, and 
google_integration_connectors_*
. Does not manage integration workflow versions.		ADC or Terraform provider credentials
ADK (
ApplicationIntegrationToolset
)		Exposes published API-trigger integrations or Integration Connectors actions/entities as tools for ADK agents (Python v0.1.0+, Java v0.3.0+).ADC (
gcloud auth application-default login
) or service account JSON
Cloud consoleVisual drag-and-drop editor, Quick/Advanced region setup, Approval task resolution, OAuth 2.0 authorization code consent flow.Browser Google Cloud sign-in
  • Use 
    gcloud
    only for generic Google Cloud tasks: enabling APIs (
    gcloud services enable
    ), printing access tokens (
    gcloud auth print-access-token
    ), managing IAM, and reading Cloud Logging (
    gcloud logging read
    ).
  • Integration Connectors includes an outbound MCP connector (
    MCP v1
    and 
    v2
    ) that lets a workflow call an external MCP server as a connector target; this is an outbound connector, not a Google-managed MCP server for controlling Application Integration.
  • Always use the global endpoint 
    https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/...
    consistently for REST calls.
  • Note on draft testing (
    integrations:test
    )    : Although 
    POST .../integrations/INTEGRATION_NAME:test
    exists in the v1 REST API, its required 
    TestIntegrationsRequest.clientId
    value is not publicly documented, so do not invent one; test integrations by publishing to a non-production project and calling 
    :execute
    .
  • See references/api-access.md for authentication setup, 
    curl
    commands, Python discovery client patterns, and ADK 
    ApplicationIntegrationToolset
    configuration.
Application Integration 没有 
gcloud integrations
命令组（也没有 
gcloud connectors
命令组），并且没有 Google 管理的远程 MCP server。REST API 是主要的控制和执行接口。
接口覆盖范围身份验证
REST API（
curl
）		完整的 v1 功能范围：区域预配、集成、版本、下载/上传、发布、执行、调度、执行记录、暂停、authConfigs、模板。
Authorization: Bearer $(gcloud auth print-access-token)
Python discovery client通过 
googleapiclient.discovery.build("integrations", "v1")
提供完整的 v1 功能范围（v2 使用 
build("integrations", "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 provider 凭据
ADK（
ApplicationIntegrationToolset
）		将已发布的 API 触发集成或 Integration Connectors 操作/实体公开为 ADK Agent 的工具（Python v0.1.0+、Java v0.3.0+）。ADC（
gcloud auth application-default login
）或 service account JSON
Cloud console可视化拖放编辑器、Quick/Advanced 区域设置、Approval 任务处理，以及 OAuth 2.0 authorization code consent flow。浏览器中的 Google Cloud 登录
  • 仅将 
    gcloud
    用于通用 Google Cloud 任务：启用 API（
    gcloud services enable
    ）、打印访问令牌（
    gcloud auth print-access-token
    ）、管理 IAM，以及读取 Cloud Logging（
    gcloud logging read
    ）。
  • Integration Connectors 包含一个出站 MCP connector（
    MCP v1
    和 
    v2
    ），允许工作流将外部 MCP server 作为 connector 目标进行调用；这是出站 connector，不是用于控制 Application Integration 的 Google 托管 MCP server。
  • 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 client 模式和 ADK 
    ApplicationIntegrationToolset
    配置，请参阅 references/api-access.md。

Step-by-Step Region Setup Workflow

分步区域设置工作流

Application Integration is regional: confirm the target region is supported on Application Integration locations and use 
us-central1
as a well-supported default when the user has no preference. The region is the 
LOCATION
in every REST path; no 
gcloud
default-region setting applies to Application Integration. Provisioning is per region. Provisioning 
us-central1
does not provision 
europe-west1
; repeat region provisioning for every 
LOCATION
you use in 
PROJECT_ID
. Ensure an active billing account is attached to 
PROJECT_ID
before setup—an active billing account is required even when usage stays within the monthly free tier (see the Application Integration pricing page).
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. Check and enable required APIs

1. 检查并启用所需 API

First check which APIs are already enabled (read-only):
bash
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)"
After getting user confirmation, enable the required APIs (add 
cloudkms.googleapis.com
only if configuring CMEK):
bash
gcloud services enable \
  integrations.googleapis.com \
  connectors.googleapis.com \
  secretmanager.googleapis.com \
  --project=PROJECT_ID
首先检查哪些 API 已经启用（只读）：
bash
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
）：
bash
gcloud services enable \
  integrations.googleapis.com \
  connectors.googleapis.com \
  secretmanager.googleapis.com \
  --project=PROJECT_ID

2. Verify setup IAM roles on the caller

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

Setting up Application Integration requires 
roles/integrations.integrationAdmin
, 
roles/connectors.admin
, and 
roles/editor
(plus 
roles/cloudkms.admin
for CMEK). Check current bindings (read-only):
bash
gcloud projects get-iam-policy PROJECT_ID --format=json
设置 Application Integration 需要 
roles/integrations.integrationAdmin
、
roles/connectors.admin
和 
roles/editor
（配置 CMEK 时还需要 
roles/cloudkms.admin
）。检查当前绑定（只读）：
bash
gcloud projects get-iam-policy PROJECT_ID --format=json

3. Provision the region (
LOCATION
)

3. 预配区域（
LOCATION
）

Choose one of the three supported paths after getting user confirmation:
  • Option A: REST (
    clients:provision
    )
    bash
    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"
    The response is 
    {}
    when provisioning succeeds (
    clients:provision
    does not apply 
    runAsServiceAccount
    ; set the run-as identity on each integration version via 
    IntegrationVersion.runAsServiceAccount
    ). 
    {}
    is also returned when the region is already provisioned; the call does not change an existing region's settings. Change HTTP calls or encryption on an existing region from the console's Regions page (when the region is already 
    ACTIVE
    , 
    cloudKmsConfig
    , 
    enableHttpCall
    , and 
    enableManagedAiFeatures
    on 
    clients:provision
    are not applied). If 
    PROJECT_ID
    was already registered through Apigee Integration, provisioning fails.
  • Option B: Cloud console Open 
    https://console.cloud.google.com/integrations
    , select 
    LOCATION
    , and click Quick setup (enables the APIs, creates the default service account, and uses Google-managed encryption) or Advanced setup (to configure CMEK, HTTP calls, AI features, governance, or variable masking). To add another region later, go to Regions > Provision new region.
  • Option C: Terraform (
    google_integrations_client
    )     Use the 
    google_integrations_client
    resource in 
    hashicorp/google
    . Do not set 
    run_as_service_account
    on 
    google_integrations_client
    —that argument was removed in provider v8.0.0 (August 26, 2026), and it mapped to the 
    clients:provision
    runAsServiceAccount
    field, which is likewise not applied; set the run-as identity on each integration version (
    IntegrationVersion.runAsServiceAccount
    ) instead.
获得用户确认后，从以下三条受支持路径中选择一条：
  • 选项 A：REST（
    clients:provision
    ）
    bash
    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
    为每个集成版本设置运行身份）。
    {}
    也表示该区域已经预配；此调用不会更改现有区域的设置。如果区域已经处于 
    ACTIVE
    状态，请通过 Cloud console 的 Regions 页面更改 HTTP 调用或加密设置（区域已经处于 
    ACTIVE
    时，
    clients:provision
    中的 
    cloudKmsConfig
    、
    enableHttpCall
    和 
    enableManagedAiFeatures
    不会生效）。如果 
    PROJECT_ID
    已经通过 Apigee Integration 注册，预配将失败。
  • 选项 B：Cloud console 打开 
    https://console.cloud.google.com/integrations
    ，选择 
    LOCATION
    ，然后点击 Quick setup（启用 API、创建默认 service account 并使用 Google 管理的加密）或 Advanced setup（配置 CMEK、HTTP 调用、AI 功能、治理或变量掩码）。如需稍后添加其他区域，请进入 Regions > Provision new region。
  • 选项 C：Terraform（
    google_integrations_client
    ）     在 
    hashicorp/google
    中使用 
    google_integrations_client
    resource。不要在 
    google_integrations_client
    上设置 
    run_as_service_account
    ——该参数已从 provider v8.0.0（2026 年 8 月 26 日）中移除；它原先映射到 
    clients:provision
    的 
    runAsServiceAccount
    字段，而该字段同样不会生效；请改为在每个集成版本上设置运行身份（
    IntegrationVersion.runAsServiceAccount
    ）。

4. Sanity-check region access

4. 快速检查区域访问权限

Run a read-only list call against the region; a successful 
200 OK
response is a good sign that the API is reachable in 
LOCATION
:
bash
curl -sS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations"
See references/provisioning-and-terraform.md for all 
ProvisionClientRequest
fields, CMEK and governance options, and complete Terraform examples.
对该区域运行只读 list 调用；成功返回 
200 OK
是 API 可在 
LOCATION
访问的良好迹象：
bash
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。

Core Concepts at a Glance

核心概念速览

  • Integrations and Triggers: An integration is a workflow started by one or more triggers. Synchronous runs (
    SYNC
    ) wait for completion and return output (
    integrations.execute
    , console test, sync 
    Call Integration
    ). Asynchronous runs (
    ASYNC
    ) are fire-and-forget (
    integrations.schedule
    , Schedule, Cloud Scheduler, Cloud Pub/Sub, Salesforce triggers, and runs resumed after a suspension or approval).
  • Tasks: Units of work chained after a trigger (such as 
    Data Mapping
    , 
    Call REST Endpoint
    , 
    Connectors
    , 
    JavaScript
    on V8, 
    Cloud Function
    , 
    Approval
    , 
    Suspend
    , 
    Timer
    , loops, and 
    Call Integration
    ).
  • Versions and Edit Locks: Only a 
    DRAFT
    version can be edited (locked to its author for 15 minutes after the last update). Only an 
    ACTIVE
    (published) version runs from triggers. Publishing a version automatically unpublishes the prior active version and cancels any suspended executions of that prior version. Unpublishing moves an active version to 
    SNAPSHOT
    (
    PREVIOUSLY_PUBLISHED
    ). Calling 
    versions.delete
    soft-deletes a version into 
    ARCHIVED
    (listed as 
    DELETED
    on the Integration versions documentation page).
  • Variables:
    • Integration variables: Explicit inputs (
      IN
      ), outputs (
      OUT
      ), 
      IN_OUT
      , or internal variables with 
      IN_OUT_TYPE_UNSPECIFIED
      (
      $varName$
      ).
    • Task variables: Auto-generated task outputs named 
      `Task_<taskId>_<variableName>`
      where 
      taskId
      is the bare task number in 
      taskConfigs[].taskId
      (for example, 
      taskId
      "1"
      -> 
      $`Task_1_responseBody`$
      ).
    • System variables: keys are backtick-wrapped (
      `ExecutionId`
      , 
      `ExecutionMode`
      , 
      `ErrorInfo`
      [
      message
      , 
      code
      ], 
      `IntegrationName`
      , 
      `Region`
      , 
      `ProjectId`
      ); reference them as 
      $`ExecutionId`$
      (a bare 
      $ExecutionId$
      names a nonexistent integration variable and fails).
    • Config variables (Preview): Environment-specific values defined in 
      integrationConfigParameters
      (with defaults in 
      parameter.defaultValue
      ; a top-level 
      value
      on a draft is discarded) and supplied per environment in 
      configParameters
      at publish time (named 
      `CONFIG_<NAME>`
      ; keys in 
      configParameters
      must exactly match a key in 
      integrationConfigParameters
      , backticks included, such as 
      "`CONFIG_target_url`"
      , because unknown keys are silently ignored—publish returns 200 and the default stays). Never store secrets in config variables—they are exported in plain text. Use an authentication profile (
      authConfigs
      ) or the Secret Manager task instead.
  • Suspensions: 
    Suspend
    tasks pause up to 31 days and are resumed via the Suspensions API (
    suspensions:lift
    , with an optional 
    suspensionResult
    , requiring 
    integrations.suspensions.lift
    ). 
    Approval
    tasks email approvers and can be approved or rejected in the Cloud console UI or via 
    suspensions:resolve
    (
    state
    : 
    "LIFTED"
    or 
    "REJECTED"
    , requiring 
    integrations.suspensions.resolve
    ). Listing suspensions (
    suspensions.list
    ) requires 
    integrations.suspensions.list
    . All three permissions are included in 
    roles/integrations.suspensionResolver
    (and 
    roles/integrations.integrationAdmin
    ), and resuming also requires 
    roles/iam.serviceAccountUser
    on the integration's run-as service account; always confirm with the user before lifting or resolving. 
    Timer
    tasks resume automatically.
  • Authentication Profiles (
    authConfigs
    )    : Reusable regional credential records (
    projects/PROJECT_ID/locations/LOCATION/authConfigs/AUTH_CONFIG_ID
    ). They are not included when downloading an integration version.
See references/core-concepts.md for full details on version states, trigger types, task categories, variables, suspensions, and authentication profiles.
  • 集成与触发器：集成是由一个或多个触发器启动的工作流。同步运行（
    SYNC
    ）会等待完成并返回输出（
    integrations.execute
    、console test、同步 
    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
    （已发布）版本会由触发器运行。发布新版本会自动取消先前 active 版本的发布状态，并取消该先前版本所有处于暂停状态的执行。取消发布会将 active 版本转为 
    SNAPSHOT
    （
    PREVIOUSLY_PUBLISHED
    ）。调用 
    versions.delete
    会将版本软删除为 
    ARCHIVED
    （在 Integration versions 文档页面上显示为 
    DELETED
    ）。
  • 变量：
    • Integration variables：显式输入（
      IN
      ）、输出（
      OUT
      ）、
      IN_OUT
      ，或类型为 
      IN_OUT_TYPE_UNSPECIFIED
      的内部变量（
      $varName$
      ）。
    • Task variables：自动生成的任务输出，名称格式为 
      `Task_<taskId>_<variableName>`
      ，其中 
      taskId
      是 
      taskConfigs[].taskId
      中的裸任务编号（例如 
      taskId
      为 
      "1"
      时，对应 
      $`Task_1_responseBody`$
      ）。
    • System variables：键使用反引号包裹（
      `ExecutionId`
      、
      `ExecutionMode`
      、
      `ErrorInfo`
      [
      message
      、
      code
      ]、
      `IntegrationName`
      、
      `Region`
      、
      `ProjectId`
      ）；引用方式为 
      $`ExecutionId`$
      （裸 
      $ExecutionId$
      表示不存在的 integration variable，执行会失败）。
    • Config variables（Preview）：在 
      integrationConfigParameters
      中定义的环境特定值（默认值位于 
      parameter.defaultValue
      ；草稿顶层的 
      value
      会被丢弃），并在发布时通过每个环境的 
      configParameters
      提供（命名为 
      `CONFIG_<NAME>`
      ；
      configParameters
      中的键必须与 
      integrationConfigParameters
      中的键完全一致，包括反引号，例如 
      "`CONFIG_target_url`"
      ，因为未知键会被静默忽略——发布会返回 200 并继续使用默认值）。切勿在 config variable 中存储 secret——它们会以明文导出。请改用 authentication profile（
      authConfigs
      ）或 Secret Manager task。
  • 暂停：
    Suspend
    任务最长可暂停 31 天，并通过 Suspensions API 恢复（
    suspensions:lift
    ，可附带 
    suspensionResult
    ，需要 
    integrations.suspensions.lift
    ）。
    Approval
    任务会向审批人发送电子邮件，并可在 Cloud console UI 中批准或拒绝，也可通过 
    suspensions:resolve
    处理（
    state
    为 
    "LIFTED"
    或 
    "REJECTED"
    ，需要 
    integrations.suspensions.resolve
    ）。列出暂停项（
    suspensions.list
    ）需要 
    integrations.suspensions.list
    。上述三种权限都包含在 
    roles/integrations.suspensionResolver
    中（
    roles/integrations.integrationAdmin
    中也包含）；恢复时还需要在集成的运行身份服务账户上拥有 
    roles/iam.serviceAccountUser
    ；解除或处理暂停前始终要先取得用户确认。
    Timer
    任务会自动恢复。
  • Authentication Profiles（
    authConfigs
    ）    ：可复用的区域级凭据记录（
    projects/PROJECT_ID/locations/LOCATION/authConfigs/AUTH_CONFIG_ID
    ）。下载集成版本时不会包含它们。
有关版本状态、触发器类型、任务类别、变量、暂停和 authentication profile 的完整详情，请参阅 references/core-concepts.md。

IAM and the Run-As Service Account Requirement

IAM 与运行身份服务账户要求

Key IAM roles and service agents

关键 IAM 角色和服务代理

  • Developer & operator roles: 
    roles/integrations.integrationAdmin
    (full CRUD + delete auth profiles), 
    roles/integrations.integrationEditor
    (create/upload/edit/test/invoke/cancel/replay/publish, including 
    integrations.integrationVersions.create
    and 
    integrations.integrationVersions.deploy
    ), 
    roles/integrations.integrationDeployer
    (publish/unpublish via 
    integrations.integrationVersions.deploy
    ; holds 
    list
    /
    get
    /
    deploy
    but not 
    create
    , so it can publish an existing version but cannot upload), 
    roles/integrations.integrationInvoker
    (invoke/cancel/replay), 
    roles/integrations.integrationViewer
    (view integrations and logs), and 
    roles/integrations.suspensionResolver
    (list, lift, and resolve suspensions: 
    integrations.suspensions.list
    , 
    integrations.suspensions.lift
    , 
    integrations.suspensions.resolve
    ; 
    suspensionResolver
    alone cannot read execution records, so also grant 
    roles/integrations.integrationViewer
    to inspect 
    taskExecutionDetails
    or run 
    :troubleshoot
    , or use the approval email link, which carries the execution and task IDs).
  • Service agents:
    • Application Integration service agent: 
      service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com
      (granted 
      roles/integrations.serviceAgent
      ).
    • Integration Connectors service agent: 
      service-PROJECT_NUMBER@gcp-sa-connectors.iam.gserviceaccount.com
      (granted 
      roles/connectors.serviceAgent
      ).
  • 开发者与操作员角色：
    roles/integrations.integrationAdmin
    （完整 CRUD，以及删除 auth profile）、
    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
    ，或者使用审批邮件链接，其中包含 execution 和 task ID）。
  • 服务代理：
    • Application Integration service agent：
      service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com
      （授予 
      roles/integrations.serviceAgent
      ）。
    • Integration Connectors service agent：
      service-PROJECT_NUMBER@gcp-sa-connectors.iam.gserviceaccount.com
      （授予 
      roles/connectors.serviceAgent
      ）。

Mandatory run-as service account rules (effective October 15, 2026)

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

  1. Explicit identity required: For integrations created on or after October 15, 2026 (and for existing integrations at a later date), every run needs an explicit identity—either the triggering caller or a user-managed run-as service account set per integration version via 
    IntegrationVersion.runAsServiceAccount
    (region provisioning via 
    clients:provision
    does not apply 
    runAsServiceAccount
    ).
  2. Triggers other than API or Private require a 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, Eventarc, Salesforce, or Connector Event) cannot be tested or published unless 
    runAsServiceAccount
    is set    . Private triggers are exempt like API triggers, so a sub-integration whose only trigger is Private can be published without 
    runAsServiceAccount
    .
  3. Region governance: If governance is enabled on the region, a run-as service account is mandatory for every new integration and version, including API-trigger integrations.
  4. Service Account User (
    roles/iam.serviceAccountUser
    )    : Whenever 
    runAsServiceAccount
    is set on a version, the user (or principal) publishing or testing the version must hold 
    roles/iam.serviceAccountUser
    on that service account (or its owning project). At runtime, the invoking caller or trigger service account—and anyone resolving or lifting a suspension—must also hold 
    roles/iam.serviceAccountUser
    on it.
  5. Best practice: Create one dedicated, minimally scoped user-managed service account per integration. When 
    runAsServiceAccount
    is set and no task-level auth profile is set, it mints tokens for Connector, Call REST Endpoint, and Cloud Function tasks (an OAuth 2.0 or OIDC auth profile on a task takes precedence over 
    runAsServiceAccount
    ).
See references/iam-and-service-accounts.md for the complete IAM role tables, service agent permissions, credential precedence rules, and 
gcloud
IAM commands.
  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. Service Account User（
    roles/iam.serviceAccountUser
    ）    ：只要版本中设置了 
    runAsServiceAccount
    ，发布或测试该版本的用户（或 principal）必须在该服务账户（或其所属项目）上拥有 
    roles/iam.serviceAccountUser
    。运行时，调用方或触发器服务账户，以及任何处理或解除暂停的人员，也必须在该服务账户上拥有 
    roles/iam.serviceAccountUser
    。
  5. 最佳实践：为每个集成创建一个专用、权限范围最小化的用户管理服务账户。设置 
    runAsServiceAccount
    且任务级 auth profile 未设置时，它会为 Connector、Call REST Endpoint 和 Cloud Function 任务签发 token（任务上的 OAuth 2.0 或 OIDC auth profile 优先于 
    runAsServiceAccount
    ）。
有关完整的 IAM 角色表、服务代理权限、凭据优先级规则和 
gcloud
IAM 命令，请参阅 references/iam-and-service-accounts.md。

Key Quotas and Limits to Design Around

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

LimitValueDesign impact
SYNC execution timeout2 minutesUse async triggers or 
integrations.schedule
for workflows exceeding 2 minutes; timed-out sync runs become 
CANCELLED
.
ASYNC execution timeout10 minutesSplit heavy work into sub-integrations or external jobs if a single async run exceeds 10 minutes.
Max execution lifetime31 daysIncludes time paused in 
Approval
or 
Suspend
tasks (max 44,640 minutes).
Total integration data30 MBShared across input/output variables and private-trigger sub-integrations. Above 10 MB, local logging is disabled, retries stop working, and monitoring skips the run.
API trigger input size8 MBCumulative size across all input variables; larger payloads fail before the workflow starts.
Connectors data & timeout8 MB in/out; 3 min timeoutApplication Integration quotas cap cumulative data sent to/from connections at 8 MB and connector response at 20 MB (Integration Connectors quotas cap the Connectors task payload at 10 MB); custom queries cap at 180 seconds and 50,000 rows.
Concurrent executions50 per project per region; 10 per integration (defaults)Both concurrency caps are adjustable; a burst on a single integration hits the 10-per-integration cap, not 50. The execution request rate quota is shown on the project's Cloud Quotas page and can be adjusted there.
Integrations / tasks / versions1,000 / 100 / 100Up to 1,000 integrations per project, 100 tasks per integration, and 100 versions per integration.
Publish propagationUp to 10 minutesEventual consistency: an older version can keep running for up to 10 minutes after publishing a new version.
See references/limits.md for all task-specific payload caps, loop iteration limits, Integration Connectors node limits, and pricing details.
限制数值设计影响
SYNC 执行超时2 分钟对于超过 2 分钟的工作流，使用异步触发器或 
integrations.schedule
；超时的同步运行会变为 
CANCELLED
。
ASYNC 执行超时10 分钟如果单次异步运行超过 10 分钟，将重型工作拆分为子集成或外部作业。
最长执行生命周期31 天包含在 
Approval
或 
Suspend
任务中暂停的时间（最长 44,640 分钟）。
集成数据总量30 MB在输入/输出变量及 Private 触发器子集成之间共享。超过 10 MB 后，本地日志记录会禁用，重试将停止工作，监控也会跳过该运行。
API 触发器输入大小8 MB所有输入变量的累计大小；更大的载荷会在工作流启动前失败。
Connectors 数据与超时输入/输出 8 MB；超时 3 分钟Application Integration 配额将发送到/来自 connection 的累计数据限制为 8 MB，并将 connector 响应限制为 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。

Sibling Skills

同级 Skill

  • application-integration-basics (this skill): Concepts, API enablement, region provisioning, IAM roles and run-as service accounts, interface choices (REST, Python client, Terraform, ADK), and quotas/limits.
  • application-integration-authoring: Building, uploading, versioning, config variables, publishing, executing, and testing integrations via the REST API; trigger IDs; task gotchas; and CI/CD promotion across projects with download/upload.
  • application-integration-troubleshooting: Diagnosing failed or stuck executions, checking execution and task states and 
    ErrorInfo
    , listing and filtering executions, Cloud Logging and Cloud Monitoring, suspensions and approvals, Integration Connectors connection health, and IAM / run-as / quota errors.
  • application-integration-basics（此 skill）：概念、API 启用、区域预配、IAM 角色和运行身份服务账户、接口选择（REST、Python client、Terraform、ADK），以及配额/限制。
  • application-integration-authoring：通过 REST API 构建、上传和管理集成版本、config variable、发布、执行和测试集成；trigger ID；task 常见问题；以及通过 download/upload 在项目间执行 CI/CD 晋级。
  • application-integration-troubleshooting：诊断失败或卡住的执行，检查 execution 和 task 状态及 
    ErrorInfo
    ，列出和筛选执行，查阅 Cloud Logging 和 Cloud Monitoring，排查暂停与审批、Integration Connectors connection 健康状况，以及 IAM、run-as 和配额错误。

Reference Files

参考文件

  • references/core-concepts.md: Triggers, execution modes, task types, version lifecycle, edit locks, variables, suspensions, and authentication profiles.
  • references/iam-and-service-accounts.md: Predefined IAM roles for Application Integration and Integration Connectors, service agents, run-as service account rules, and IAM commands.
  • references/provisioning-and-terraform.md: Per-region provisioning via REST 
    clients:provision
    , Cloud console Quick/Advanced setup, CMEK caveats, and Terraform 
    google_integrations_*
    / 
    google_integration_connectors_*
    resources.
  • references/api-access.md: Endpoints, authentication, 
    curl
    examples, Python 
    google-api-python-client
    discovery patterns, ADK 
    ApplicationIntegrationToolset
    , and MCP connector clarification.
  • references/limits.md: Timeouts, payload caps, concurrency quotas, loop/task limits, Integration Connectors limits, and pricing tiers.
  • references/core-concepts.md：触发器、执行模式、任务类型、版本生命周期、编辑锁、变量、暂停和 authentication profile。
  • references/iam-and-service-accounts.md：Application Integration 和 Integration Connectors 的预定义 IAM 角色、服务代理、run-as service account 规则，以及 IAM 命令。
  • references/provisioning-and-terraform.md：通过 REST 
    clients:provision
    按区域预配、Cloud console Quick/Advanced 设置、CMEK 注意事项，以及 Terraform 
    google_integrations_*
    / 
    google_integration_connectors_*
    resource。
  • references/api-access.md：端点、身份验证、
    curl
    示例、Python 
    google-api-python-client
    discovery 模式、ADK 
    ApplicationIntegrationToolset
    ，以及 MCP connector 辨析。
  • references/limits.md：超时、载荷上限、并发配额、循环/任务限制、Integration Connectors 限制和定价层级。