Back to Details

application-integration-authoring

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Application Integration Authoring

Application Integration 编排

Google Cloud Application Integration workflows are authored, versioned, published, and executed programmatically through the REST API (
https://integrations.googleapis.com/v1/...
) or the discovery-based Google API Python client (
googleapiclient.discovery.build("integrations", "v1")
).
There is no 
gcloud integrations
command group, no Google-managed MCP server for Application Integration, and no documented Terraform resource for integrations or versions. Use 
gcloud
only for authentication, enabling APIs, and IAM bindings. Use Terraform only for region provisioning (
google_integrations_client
), authentication profiles (
google_integrations_auth_config
), and Integration Connectors (
google_integration_connectors_connection
).
For initial project setup, region provisioning, and IAM role definitions, use the 
application-integration-basics
skill. For diagnosing failed or stuck runs, execution logs, and quota errors, use the 
application-integration-troubleshooting
skill.
Google Cloud Application Integration 工作流可通过 REST API（
https://integrations.googleapis.com/v1/...
）或基于 discovery 的 Google API Python 客户端（
googleapiclient.discovery.build("integrations", "v1")
）进行编程式编排、版本管理、发布和执行。
不存在 
gcloud integrations
命令组，也不存在 Google 托管的 Application Integration MCP server，并且没有针对 integration 或 version 的已文档化 Terraform resource。仅将 
gcloud
用于身份验证、启用 API 和绑定 IAM。仅将 Terraform 用于区域预配（
google_integrations_client
）、身份验证配置文件（
google_integrations_auth_config
）和 Integration Connectors（
google_integration_connectors_connection
）。
对于初始项目设置、区域预配和 IAM 角色定义，请使用 
application-integration-basics
skill。对于诊断失败或卡住的运行、执行日志和配额错误，请使用 
application-integration-troubleshooting
skill。

Safety and Confirmation Rules

安全与确认规则

  • Read-only operations run freely: 
    integrations.list
    , 
    integrations:search
    , 
    versions.list
    , 
    versions.get
    , 
    versions:download
    , 
    authConfigs.list
    , and 
    executions.list
    .
  • Confirm before any state change or execution: Before creating, uploading, patching, publishing, unpublishing, testing, executing, scheduling, or deleting an integration or version, or modifying IAM or auth configs, show the exact command and payload to the user and get explicit confirmation.
  • 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.
  • Never store secrets in config variables: Config variables (
    CONFIG_*
    ) are stored and exported in plain text. Always use authentication profiles (
    projects.locations.authConfigs
    ) or the Secret Manager access task for credentials.
  • 只读操作可直接执行：
    integrations.list
    、
    integrations:search
    、
    versions.list
    、
    versions.get
    、
    versions:download
    、
    authConfigs.list
    和 
    executions.list
    。
  • 任何状态变更或执行前均需确认：在创建、上传、修补、发布、取消发布、测试、执行、调度或删除 integration 或 version，或者修改 IAM 或 auth config 之前，向用户展示确切的命令和 payload，并获得明确确认。
  • 安装软件包（
    pip install
    ）或更改全局 gcloud 设置（例如 
    gcloud config set auth/impersonate_service_account
    ）之前，须询问用户；先展示确切的命令。
  • 切勿在配置变量中存储机密：配置变量（
    CONFIG_*
    ）以明文形式存储和导出。始终使用身份验证配置文件（
    projects.locations.authConfigs
    ）或 Secret Manager access task 存储凭据。

Prerequisites Checklist

前提条件检查清单

  1. Install Google Cloud SDK: Follow Install the gcloud CLI if 
    gcloud
    is not installed.
  2. Billing and project: Ensure the Google Cloud project has an active billing account attached (required even when usage stays within the free tier), then set the target project:
    bash
    gcloud config set project PROJECT_ID
  3. Enable required APIs:
    bash
    gcloud services enable integrations.googleapis.com connectors.googleapis.com secretmanager.googleapis.com
  4. Provision the region: 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. The target 
    LOCATION
    must be provisioned via the Cloud console or 
    POST .../clients:provision
    before authoring integrations (see 
    application-integration-basics
    ).
  5. Authenticate:
    • For 
      curl
      : run 
      gcloud auth login
      and pass 
      -H "Authorization: Bearer $(gcloud auth print-access-token)"
      .
    • For the Python client (install with 
      pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3"
      ): run 
      gcloud auth application-default login
      (or set 
      GOOGLE_APPLICATION_CREDENTIALS
      for a service account).
    • For service account impersonation: run 
      gcloud config set auth/impersonate_service_account SA_EMAIL
      (requires 
      roles/iam.serviceAccountTokenCreator
      ).
  6. Verify IAM roles:
    • Create, upload, or edit drafts: 
      roles/integrations.integrationEditor
      (covers 
      versions:upload
      , which needs 
      integrations.integrationVersions.create
      , and 
      versions:publish
      )
    • Publish or unpublish: 
      roles/integrations.integrationDeployer
      or 
      roles/integrations.integrationEditor
      (
      roles/integrations.integrationDeployer
      alone can publish an existing version but cannot upload via 
      versions:upload
      ), plus 
      roles/integrations.serviceAgent
      granted to the Application Integration service agent (
      service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com
      )
    • Invoke integrations: 
      roles/integrations.integrationInvoker
    • Act as the 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 (and region governance requires it for all integrations); whenever 
      runAsServiceAccount
      is set, the user publishing or testing the version needs 
      roles/iam.serviceAccountUser
      on it (and at runtime, the invoking caller or trigger service account needs 
      roles/iam.serviceAccountUser
      on it).
  1. 安装 Google Cloud SDK：如果尚未安装 
    gcloud
    ，请按照安装 gcloud CLI中的说明操作。
  2. 计费与项目：确保 Google Cloud 项目已关联有效计费账户（即使使用量保持在免费额度内也必须关联），然后设置目标项目：
    bash
    gcloud config set project PROJECT_ID
  3. 启用所需 API：
    bash
    gcloud services enable integrations.googleapis.com connectors.googleapis.com secretmanager.googleapis.com
  4. 预配区域：Application Integration 是区域性的：在 Application Integration locations 上确认目标区域受支持；如果用户没有偏好，可使用支持较完善的默认区域 
    us-central1
    。每条 REST 路径中的 
    LOCATION
    都是该区域；Application Integration 不适用 
    gcloud
    的默认区域设置。在编排 integration 之前，必须通过 Cloud console 或 
    POST .../clients:provision
    预配目标 
    LOCATION
    （参见 
    application-integration-basics
    ）。
  5. 进行身份验证：
    • 对于 
      curl
      ：运行 
      gcloud auth login
      ，并传入 
      -H "Authorization: Bearer $(gcloud auth print-access-token)"
      。
    • 对于 Python 客户端（使用 
      pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3"
      安装）：运行 
      gcloud auth application-default login
      （或者为 service account 设置 
      GOOGLE_APPLICATION_CREDENTIALS
      ）。
    • 对于 service account 模拟：运行 
      gcloud config set auth/impersonate_service_account SA_EMAIL
      （需要 
      roles/iam.serviceAccountTokenCreator
      ）。
  6. 验证 IAM 角色：
    • 创建、上传或编辑草稿：
      roles/integrations.integrationEditor
      （涵盖需要 
      integrations.integrationVersions.create
      权限的 
      versions:upload
      ，以及 
      versions:publish
      ）。
    • 发布或取消发布：
      roles/integrations.integrationDeployer
      或 
      roles/integrations.integrationEditor
      （
      roles/integrations.integrationDeployer
      单独可以发布现有 version，但无法通过 
      versions:upload
      上传），并且需要将 
      roles/integrations.serviceAgent
      授予 Application Integration service agent（
      service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com
      ）。
    • 调用 integration：
      roles/integrations.integrationInvoker
      。
    • 以 run-as service account 身份运行：对于 2026 年 10 月 15 日及之后创建、且触发器不是 API 或 Private 的 integration（例如 Schedule、Cloud Scheduler、Cloud Pub/Sub、Salesforce 或 Connector Event；Private trigger 与 API trigger 一样豁免，因此仅以 Private 为触发器的 sub-integration 无需设置 
      runAsServiceAccount
      即可发布），如果未设置 
      runAsServiceAccount
      ，则无法测试或发布（区域治理还要求所有 integration 都设置该账户）；只要设置了 
      runAsServiceAccount
      ，发布或测试该 version 的用户就需要拥有该账户的 
      roles/iam.serviceAccountUser
      （运行时，调用方或 trigger service account 也需要拥有该权限）。

Decision Flow

决策流程

GoalActionEndpoint / Method
Inspect existing integrations in a regionList integrations, then list versions
GET .../integrations
then 
GET .../versions
Export an integration version to source controlDownload version JSON
GET .../versions/VERSION_ID:download?fileFormat=JSON
Create an integration or add a new 
DRAFT
version from JSON		Upload version JSON (creates the integration if it does not exist, or adds a new 
DRAFT
version; still needs 
:publish
)
POST .../integrations/INTEGRATION_NAME/versions:upload
Create a brand-new integration and fail on a name clashCreate first 
DRAFT
version with 
newIntegration=true
(returns 
ALREADY_EXISTS
if 
INTEGRATION_NAME
already exists)
POST .../integrations/INTEGRATION_NAME/versions?newIntegration=true
Edit an existing 
DRAFT
version		Check 
lockHolder
, then patch or upload
PATCH .../versions/VERSION_ID?updateMask=...
Edit an 
ACTIVE
(published) integration		Upload or create a new 
DRAFT
version
POST .../integrations/INTEGRATION_NAME/versions:upload
Externalize environment-specific URLs or IDsDefine 
CONFIG_<NAME>
and supply at publish
integrationConfigParameters
+ 
versions:publish
Store API keys, OAuth credentials, or certsCreate an authentication profile
POST .../authConfigs
Test an integration before productionPublish to a non-production project and invoke 
:execute
POST .../versions/VERSION_ID:publish
then 
POST .../integrations/INTEGRATION_NAME:execute
Deploy a 
DRAFT
to serve live traffic		Publish version with 
configParameters
POST .../versions/VERSION_ID:publish
Invoke a published integration synchronouslyCall 
:execute
with 
api_trigger/TRIGGER_NAME
POST .../integrations/INTEGRATION_NAME:execute
Invoke a published integration asynchronouslyCall 
:schedule
with 
scheduleTime
POST .../integrations/INTEGRATION_NAME:schedule
Promote a version across projects (CI/CD)Download JSON -> Upload to target -> Publish
:download
-> 
:upload
-> 
:publish
See references/rest-api-cheatsheet.md for full request parameters, query filters, and IAM permissions for each method.
目标操作端点/方法
检查某个区域中现有的 integration列出 integration，然后列出 version
GET .../integrations
，然后 
GET .../versions
将 integration version 导出到源代码管理下载 version JSON
GET .../versions/VERSION_ID:download?fileFormat=JSON
根据 JSON 创建 integration 或添加新的 
DRAFT
version		上传 version JSON（如果 integration 不存在则创建；如果已存在则添加新的 
DRAFT
version；仍需执行 
:publish
）
POST .../integrations/INTEGRATION_NAME/versions:upload
创建一个全新的 integration，并在名称冲突时失败使用 
newIntegration=true
创建首个 
DRAFT
version（如果 
INTEGRATION_NAME
已存在，则返回 
ALREADY_EXISTS
）
POST .../integrations/INTEGRATION_NAME/versions?newIntegration=true
编辑现有的 
DRAFT
version		检查 
lockHolder
，然后执行 patch 或 upload
PATCH .../versions/VERSION_ID?updateMask=...
编辑现有的 
ACTIVE
（已发布）integration		上传 version 或创建新的 
DRAFT
version
POST .../integrations/INTEGRATION_NAME/versions:upload
将环境特定的 URL 或 ID 外部化定义 
CONFIG_<NAME>
，并在发布时提供对应值
integrationConfigParameters
+ 
versions:publish
存储 API key、OAuth 凭据或证书创建身份验证配置文件
POST .../authConfigs
在生产环境之前测试 integration发布到非生产项目，然后调用 
:execute
POST .../versions/VERSION_ID:publish
，然后 
POST .../integrations/INTEGRATION_NAME:execute
部署 
DRAFT
以承载线上流量		使用 
configParameters
发布 version
POST .../versions/VERSION_ID:publish
同步调用已发布的 integration使用 
api_trigger/TRIGGER_NAME
调用 
:execute
POST .../integrations/INTEGRATION_NAME:execute
异步调用已发布的 integration使用 
scheduleTime
调用 
:schedule
POST .../integrations/INTEGRATION_NAME:schedule
在项目之间提升 version（CI/CD）下载 JSON -> 上传到目标项目 -> 发布
:download
-> 
:upload
-> 
:publish
有关每个方法的完整请求参数、查询过滤器和 IAM 权限，请参阅 references/rest-api-cheatsheet.md。

Core Authoring Workflow

核心编排工作流

1. List Integrations and Download a Version

1. 列出 Integration 并下载 Version

List integrations in 
LOCATION
and list versions for a specific 
INTEGRATION_NAME
:
bash
TOKEN="$(gcloud auth print-access-token)"
在 
LOCATION
中列出 integration，并列出特定 
INTEGRATION_NAME
的 version：
bash
TOKEN="$(gcloud auth print-access-token)"

List integrations in the region

List integrations in the region

curl -sS -H "Authorization: Bearer ${TOKEN}"
"https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations?pageSize=50"
curl -sS -H "Authorization: Bearer ${TOKEN}"
"https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations?pageSize=50"

List versions (ordered by most recently modified)

List versions (ordered by most recently modified)

curl -sS -H "Authorization: Bearer ${TOKEN}"
"https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions?orderBy=last_modified_time%20desc"

Download a specific version (`VERSION_ID` is the UUID at the end of the version's `name` field) as portable JSON:

```bash
curl -sS -H "Authorization: Bearer ${TOKEN}" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions/VERSION_ID:download?fileFormat=JSON" \
  | jq -r '.content' > integration-version.json
curl -sS -H "Authorization: Bearer ${TOKEN}"
"https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions?orderBy=last_modified_time%20desc"

将特定 version（`VERSION_ID` 是该 version 的 `name` 字段末尾的 UUID）下载为可移植 JSON：

```bash
curl -sS -H "Authorization: Bearer ${TOKEN}" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions/VERSION_ID:download?fileFormat=JSON" \
  | jq -r '.content' > integration-version.json

2. Understand the 
IntegrationVersion
Structure

2. 理解 
IntegrationVersion
结构

An 
IntegrationVersion
JSON object contains four primary arrays and version-level settings:
  • triggerConfigs
    : Entry points that start the workflow. Each entry requires a unique 
    triggerNumber
    , plus 
    triggerType
    (such as 
    API
    or 
    PRIVATE_TRIGGER
    ), optional 
    triggerId
    (auto-generated from 
    properties
    if omitted; for API triggers: 
    api_trigger/TRIGGER_NAME
    ), and 
    startTasks
    pointing to the first 
    taskId
    .
  • taskConfigs
    : Units of work. Each entry needs 
    task
    (the task type, such as 
    EmailTask
    in the public upload sample, or 
    FieldMappingTask
    in a discovery enum description), a unique 
    taskId
    , 
    parameters
    , 
    nextTasks
    , and optional 
    failurePolicy
    or 
    errorCatcherId
    .
  • integrationParameters
    : Input, output, and transient variables (
    key
    , 
    dataType
    such as 
    STRING_VALUE
    or 
    JSON_VALUE
    , 
    inputOutputType
    of 
    IN
    , 
    OUT
    , 
    IN_OUT
    , or 
    IN_OUT_TYPE_UNSPECIFIED
    , and 
    defaultValue
    ).
  • integrationConfigParameters
    : Environment-specific config variable definitions (
    parameter
    with key 
    `CONFIG_<NAME>`
    and 
    parameter.defaultValue
    ; a top-level 
    value
    in uploaded or created draft JSON is discarded, so per-environment values go in 
    configParameters
    at publish).
  • runAsServiceAccount
    : Dedicated user-managed service account email. When set and no authentication profile (
    authConfig
    ) is configured on the task, it is used to generate the auth token for Connector (
    Connectors
    ), REST (
    Call REST Endpoint
    ), and Cloud Function tasks; an authentication profile configured on the task takes precedence over 
    runAsServiceAccount
    .
Always use 
triggerConfigs
, 
taskConfigs
, and 
integrationParameters
. Never use 
triggerConfigsInternal
, 
taskConfigsInternal
, or 
integrationParametersInternal
because they are deprecated. See references/integration-version-json.md for field schemas, 
ValueType
shapes, and a minimal 
IntegrationVersion
JSON template.
一个 
IntegrationVersion
JSON 对象包含四个主要数组和 version 级设置：
  • triggerConfigs
    ：启动工作流的入口点。每个入口都需要唯一的 
    triggerNumber
    、
    triggerType
    （例如 
    API
    或 
    PRIVATE_TRIGGER
    ）、可选的 
    triggerId
    （如果省略，则根据 
    properties
    自动生成；对于 API trigger：
    api_trigger/TRIGGER_NAME
    ），以及指向首个 
    taskId
    的 
    startTasks
    。
  • taskConfigs
    ：工作单元。每个条目都需要 
    task
    （任务类型，例如公共上传示例中的 
    EmailTask
    ，或 discovery 枚举描述中的 
    FieldMappingTask
    ）、唯一的 
    taskId
    、
    parameters
    、
    nextTasks
    ，以及可选的 
    failurePolicy
    或 
    errorCatcherId
    。
  • integrationParameters
    ：输入、输出和瞬态变量（
    key
    、
    dataType
    ，例如 
    STRING_VALUE
    或 
    JSON_VALUE
    ；
    inputOutputType
    ，即 
    IN
    、
    OUT
    、
    IN_OUT
    或 
    IN_OUT_TYPE_UNSPECIFIED
    ；以及 
    defaultValue
    ）。
  • integrationConfigParameters
    ：环境特定的配置变量定义（
    parameter
    的键为 
    `CONFIG_<NAME>`
    ，并包含 
    parameter.defaultValue
    ；上传或创建的 draft JSON 中，顶层 
    value
    会被丢弃，因此各环境的值应在发布时通过 
    configParameters
    提供）。
  • runAsServiceAccount
    ：专用的用户管理型 service account 邮箱地址。设置该字段且任务未配置身份验证配置文件（
    authConfig
    ）时，将使用它为 Connector（
    Connectors
    ）、REST（
    Call REST Endpoint
    ）和 Cloud Function 任务生成 auth token；任务上配置的身份验证配置文件优先于 
    runAsServiceAccount
    。
始终使用 
triggerConfigs
、
taskConfigs
和 
integrationParameters
。切勿使用 
triggerConfigsInternal
、
taskConfigsInternal
或 
integrationParametersInternal
，因为它们已经弃用。有关字段 schema、
ValueType
结构以及最小化的 
IntegrationVersion
JSON 模板，请参阅 references/integration-version-json.md。

3. Create or Upload a 
DRAFT
Version

3. 创建或上传 
DRAFT
Version

Each integration allows up to 100 versions and 100 tasks, and 
INTEGRATION_NAME
can be at most 64 characters. Calling 
versions:upload
creates a new 
DRAFT
version—creating the integration automatically if 
INTEGRATION_NAME
does not exist yet, or adding the next 
DRAFT
version if it already exists (for example, uploading onto version 5 creates version 6). The uploaded version is in 
DRAFT
state and still requires 
versions:publish
to serve traffic. Use 
POST .../versions?newIntegration=true
(passing an 
IntegrationVersion
JSON body) only when you explicitly want the call to fail with 
ALREADY_EXISTS
if 
INTEGRATION_NAME
already exists.
bash
undefined
每个 integration 最多允许 100 个 version 和 100 个 task，且 
INTEGRATION_NAME
最长为 64 个字符。调用 
versions:upload
会创建一个新的 
DRAFT
version——如果 
INTEGRATION_NAME
尚不存在，则自动创建 integration；如果已经存在，则添加下一个 
DRAFT
version（例如，在 version 5 基础上上传会创建 version 6）。上传后的 version 处于 
DRAFT
状态，仍需执行 
versions:publish
才能承载流量。仅当明确希望调用在 
INTEGRATION_NAME
已存在时返回 
ALREADY_EXISTS
，才使用 
POST .../versions?newIntegration=true
（请求体为 
IntegrationVersion
JSON）。
bash
undefined

Upload integration-version.json as a new DRAFT version

Upload integration-version.json as a new DRAFT version

PAYLOAD="$(jq -n --rawfile content integration-version.json '{content: $content, fileFormat: "JSON"}')"
curl -sS --fail-with-body -X POST
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-d "${PAYLOAD}"
"https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions:upload"

Capture the new `VERSION_ID` from `.integrationVersion.name` in the response (`projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions/VERSION_ID`).
PAYLOAD="$(jq -n --rawfile content integration-version.json '{content: $content, fileFormat: "JSON"}')"
curl -sS --fail-with-body -X POST
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-d "${PAYLOAD}"
"https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions:upload"

从响应中的 `.integrationVersion.name` 获取新的 `VERSION_ID`（`projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions/VERSION_ID`）。

4. Version States and Edit-Lock Rules

4. Version 状态与编辑锁规则

StateMeaningEditable?Can Serve Triggers?
DRAFT
Version actively being edited; its edit lock is held by its author (
lockHolder
email) for 15 minutes from the last update		Yes (only by 
lockHolder
)		No
ACTIVE
Published version serving live trafficNoYes
SNAPSHOT
Prior draft (when another author takes over in the console) or unpublished version (
PREVIOUSLY_PUBLISHED
)		NoNo
ARCHIVED
Soft-deleted via 
versions.delete
(no undelete; listed as 
DELETED
on the Integration versions documentation page)		NoNo
  • Edit-lock enforcement: A 
    DRAFT
    version's edit lock is held by its author (
    lockHolder
    ). Calling 
    versions:publish
    or 
    versions.delete
    on a 
    DRAFT
    fails if the caller is not the 
    lockHolder
    (
    versions:publish
    and 
    versions.delete
    release any existing lock when they succeed).
  • No v1 lock-takeover API: 
    takeoverEditLock
    does not exist on 
    projects.locations.integrations.versions
    in the v1 REST API (it only exists on 
    versions.testCases
    ). If a 
    DRAFT
    is locked by another user, wait 15 minutes from 
    updateTime
    for the lock to expire automatically, or click Take Over in the Cloud console (which converts the existing draft to 
    SNAPSHOT
    and creates a new 
    DRAFT
    ).
状态含义是否可编辑是否可承载 Trigger
DRAFT
正在主动编辑的 version；其编辑锁由作者（
lockHolder
邮箱）持有，期限为最后一次更新后的 15 分钟		是（仅限 
lockHolder
）		否
ACTIVE
已发布并承载线上流量的 version否是
SNAPSHOT
先前的 draft（当另一位作者在 console 中接手时），或未发布的 version（
PREVIOUSLY_PUBLISHED
）		否否
ARCHIVED
通过 
versions.delete
软删除（无法恢复；在 Integration versions 文档页面中列为 
DELETED
）		否否
  • 编辑锁强制执行：
    DRAFT
    version 的编辑锁由其作者（
    lockHolder
    ）持有。如果调用方不是 
    lockHolder
    ，则对该 
    DRAFT
    调用 
    versions:publish
    或 
    versions:delete
    会失败（
    versions:publish
    和 
    versions:delete
    成功后都会释放现有锁）。
  • v1 不提供锁接管 API：在 v1 REST API 的 
    projects.locations.integrations.versions
    上不存在 
    takeoverEditLock
    （它仅存在于 
    versions.testCases
    上）。如果一个 
    DRAFT
    被其他用户锁定，请等待从 
    updateTime
    起 15 分钟让锁自动过期，或者在 Cloud console 中单击 Take Over（这会将现有 draft 转换为 
    SNAPSHOT
    ，并创建一个新的 
    DRAFT
    ）。

5. Config Variables vs Authentication Profiles

5. 配置变量与身份验证配置文件

  • Config variables (
    CONFIG_<NAME>
    )    : Use for non-secret environment values (backend hostnames, Pub/Sub topics, connection names). Define them in 
    integrationConfigParameters
    on the draft (putting any default in 
    parameter.defaultValue
    , because a top-level 
    value
    on a draft is discarded) and pass their per-environment values in 
    configParameters
    when calling 
    versions:publish
    . Gotcha: Keys in 
    configParameters
    at publish must exactly match a key in 
    integrationConfigParameters
    , backticks included (for example, 
    "`CONFIG_target_url`"
    ); unknown keys are silently ignored, not rejected (
    versions:publish
    returns 200 and the default stays). Config variables cannot configure Integration Connectors entity operations or actions.
  • Authentication profiles (
    authConfigs
    )    : Use for API keys, OAuth 2.0 credentials, JWTs, OIDC tokens, SSL/TLS certificates, and service accounts. Auth profiles are regional resources (
    projects/PROJECT_ID/locations/LOCATION/authConfigs/AUTH_CONFIG_ID
    ) and are not included when you download an integration version. Create them in each target project via 
    POST .../authConfigs
    or Terraform 
    google_integrations_auth_config
    .
  • 配置变量（
    CONFIG_<NAME>
    ）    ：用于非机密的环境值（后端主机名、Pub/Sub topic、连接名称）。在 draft 中通过 
    integrationConfigParameters
    定义（默认值放在 
    parameter.defaultValue
    中，因为 draft 顶层的 
    value
    会被丢弃），并在调用 
    versions:publish
    时通过 
    configParameters
    传入各环境的值。注意：发布时 
    configParameters
    中的键必须与 
    integrationConfigParameters
    中的键完全一致，包括反引号（例如 
    "`CONFIG_target_url`"
    ）；未知键会被静默忽略，而不是被拒绝（
    versions:publish
    返回 200，并继续使用默认值）。配置变量无法配置 Integration Connectors 的实体操作或 action。
  • 身份验证配置文件（
    authConfigs
    ）    ：用于 API key、OAuth 2.0 凭据、JWT、OIDC token、SSL/TLS 证书和 service account。身份验证配置文件是区域资源（
    projects/PROJECT_ID/locations/LOCATION/authConfigs/AUTH_CONFIG_ID
    ），下载 integration version 时不会包含它们。通过 
    POST .../authConfigs
    或 Terraform 
    google_integrations_auth_config
    在每个目标项目中分别创建。

6. Test, Publish, and Unpublish

6. 测试、发布与取消发布

  • Recommended testing path: Test integrations by publishing the version in a non-production project (
    versions:publish
    ) and invoking 
    integrations:execute
    there.
    • Note on 
      integrations:test
      : The v1 REST API includes 
      POST .../integrations/INTEGRATION_NAME:test
      for testing a 
      DRAFT
      , which requires 
      TestIntegrationsRequest.clientId
      ("Required. This is used to identify the client on whose behalf the event will be executed."), but the public documentation does not specify what value to pass. Do not invent a 
      clientId
      value; publish to a non-production project and call 
      :execute
      instead. (Draft testing also cannot run 
      Approval
      , 
      Suspend
      , or 
      Timer
      tasks, and Call REST Endpoint authentication profile changes only take effect after publishing.)
  • Publish (
    versions:publish
    )    : Deploys the version as 
    ACTIVE
    and releases any edit lock (fails if the version is already 
    ACTIVE
    or 
    ARCHIVED
    , or if it is a 
    DRAFT
    whose 
    lockHolder
    differs from the caller). Any previously 
    ACTIVE
    version is automatically unpublished, and dependent services switch to the newly published version.
    • Gotcha: Publishing a new version automatically cancels all suspended executions of the previous version.
    • Gotcha: Due to eventual consistency, the previous version can continue running for up to 10 minutes after a new version is published.
  • Unpublish (
    versions:unpublish
    )    : Moves the 
    ACTIVE
    version to 
    SNAPSHOT
    (tagged 
    PREVIOUSLY_PUBLISHED
    ; fails if the version is not 
    ACTIVE
    ) and stops triggers and dependent services.
bash
undefined
  • 推荐测试路径：通过在非生产项目中发布 version（
    versions:publish
    ），并在该项目中调用 
    integrations:execute
    来测试 integration。
    • 关于 
      integrations:test
      的说明      ：v1 REST API 包含用于测试 
      DRAFT
      的 
      POST .../integrations/INTEGRATION_NAME:test
      ，该接口要求提供 
      TestIntegrationsRequest.clientId
      （“必需。用于标识代表其执行事件的客户端。”），但公开文档未说明应传入什么值。不要自行编造 
      clientId
      ；应改为发布到非生产项目并调用 
      :execute
      。（Draft 测试也无法运行 
      Approval
      、
      Suspend
      或 
      Timer
      任务，并且 Call REST Endpoint 的身份验证配置文件更改只有在发布后才会生效。）
  • 发布（
    versions:publish
    ）    ：将 version 部署为 
    ACTIVE
    并释放任何编辑锁（如果 version 已经是 
    ACTIVE
    或 
    ARCHIVED
    ，或者该 
    DRAFT
    的 
    lockHolder
    与调用方不同，则会失败）。之前处于 
    ACTIVE
    状态的 version 会自动取消发布，依赖服务也会切换到新发布的 version。
    • 注意：发布新 version 会自动取消上一个 version 中所有已暂停的 execution。
    • 注意：由于最终一致性，新 version 发布后，旧 version 仍可能继续运行最多 10 分钟。
  • 取消发布（
    versions:unpublish
    ）    ：将 
    ACTIVE
    version 转换为 
    SNAPSHOT
    （标记为 
    PREVIOUSLY_PUBLISHED
    ；如果该 version 不是 
    ACTIVE
    ，则失败），并停止 trigger 和依赖服务。
bash
undefined

Publish VERSION_ID and supply config variable values (keys must exactly match integrationConfigParameters keys, backticks included; unknown keys are silently ignored)

Publish VERSION_ID and supply config variable values (keys must exactly match integrationConfigParameters keys, backticks included; unknown keys are silently ignored)

curl -sS --fail-with-body -X POST
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-d '{"configParameters": {"
CONFIG_backend_url
": "https://api.example.com"}}'
"https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions/VERSION_ID:publish"
undefined
curl -sS --fail-with-body -X POST
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-d '{"configParameters": {"
CONFIG_backend_url
": "https://api.example.com"}}'
"https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions/VERSION_ID:publish"
undefined

7. Execute (Sync) vs Schedule (Async)

7. 同步执行与异步调度

Only an 
ACTIVE
(published) version can be invoked via 
execute
or 
schedule
. For API triggers, 
triggerId
is always 
api_trigger/TRIGGER_NAME
(where 
TRIGGER_NAME
is at most 64 characters). Passing 
-
as 
INTEGRATION_NAME
in 
execute
runs all published integrations in that region that share the 
triggerId
.
MethodModeMax TimeoutMax API InputKey Request FieldsKey Response Fields
integrations:execute
Sync2 minutes8 MB
triggerId
, 
inputParameters
, 
requestId
, 
doNotPropagateError
executionId
, 
outputParameters
, 
parameters
integrations:schedule
Async10 minutesNot documented
triggerId
, 
scheduleTime
(RFC 3339), 
inputParameters
, 
requestId
, 
userGeneratedExecutionId
executionInfoIds[]
  • Reading 
    outputParameters
    and 
    executionId
    : In 
    ExecuteIntegrationsResponse
    , 
    executionId
    identifies the run, and 
    outputParameters
    is a JSON object of output variables (system-generated keys such as 
    `ExecutionId`
    are wrapped in backticks).
  • HTTP 200 does not prove every task succeeded: If 
    doNotPropagateError
    is 
    true
    , or a task uses failure policy 
    IGNORE
    or 
    NONE
    with an alternate path, the HTTP call returns 
    200 OK
    even when a task failed. Always verify the execution record via 
    executions.list?filter=execution_id="EXECUTION_ID"
    (checking 
    executionDetails.state
    , each task's 
    taskExecutionState
    , and 
    ErrorInfo
    in 
    Execution.responseParameters
    ; when 
    doNotPropagateError
    is 
    true
    , errors are also returned in event parameters as 
    PostWithTriggerIdExecutionException
    ). Do not rely on the legacy/deprecated 
    executionFailed
    field.
See references/triggers-and-execution.md for all trigger types, 
ValueType
input formatting, OpenAPI spec generation, and suspension lifting and approval resolution.
只有 
ACTIVE
（已发布）version 才能通过 
execute
或 
schedule
调用。对于 API trigger，
triggerId
始终为 
api_trigger/TRIGGER_NAME
（其中 
TRIGGER_NAME
最长为 64 个字符）。在 
execute
中将 
-
作为 
INTEGRATION_NAME
传入，会运行该区域中共享同一 
triggerId
的所有已发布 integration。
方法模式最大超时时间最大 API 输入关键请求字段关键响应字段
integrations:execute
同步2 分钟8 MB
triggerId
、
inputParameters
、
requestId
、
doNotPropagateError
executionId
、
outputParameters
、
parameters
integrations:schedule
异步10 分钟未文档化
triggerId
、
scheduleTime
（RFC 3339）、
inputParameters
、
requestId
、
userGeneratedExecutionId
executionInfoIds[]
  • 读取 
    outputParameters
    和 
    executionId
    ：在 
    ExecuteIntegrationsResponse
    中，
    executionId
    用于标识运行，
    outputParameters
    是由输出变量组成的 JSON 对象（系统生成的键，例如 
    `ExecutionId`
    ，会包含在反引号中）。
  • HTTP 200 不代表每个任务都成功：如果 
    doNotPropagateError
    为 
    true
    ，或者任务使用 failure policy 
    IGNORE
    或 
    NONE
    并配置了备用路径，即使任务失败，HTTP 调用也会返回 
    200 OK
    。始终通过 
    executions.list?filter=execution_id="EXECUTION_ID"
    验证 execution 记录（检查 
    executionDetails.state
    、每个任务的 
    taskExecutionState
    ，以及 
    Execution.responseParameters
    中的 
    ErrorInfo
    ；当 
    doNotPropagateError
    为 
    true
    时，错误还会作为 event parameter 以 
    PostWithTriggerIdExecutionException
    的形式返回）。不要依赖已弃用的旧版 
    executionFailed
    字段。
有关所有 trigger 类型、
ValueType
输入格式、OpenAPI spec 生成，以及暂停解除和审批处理，请参阅 references/triggers-and-execution.md。

End-to-End Version and API Workflow Examples

端到端 Version 与 API 工作流示例

In downloaded and uploaded 
IntegrationVersion
JSON, an 
EmailTask
uses four customer-visible parameter keys inside 
taskConfigs[].parameters
: 
"To"
(
stringArray
of recipient addresses), 
"Subject"
(
stringValue
), 
"BodyFormat"
(
stringValue
, such as 
"PLAIN_TEXT"
), and 
"TextBody"
(
stringValue
). Both runnable examples below also set 
"runAsServiceAccount": "RUN_AS_SA"
(replace 
RUN_AS_SA
with your dedicated service account email, such as 
order-workflow-sa@PROJECT_ID.iam.gserviceaccount.com
; projects with governance require a run-as service account to publish, and the caller needs 
roles/iam.serviceAccountUser
on it). Executing an 
EmailTask
sends a real email, so always confirm the recipient address (
RECIPIENT_EMAIL
) and each state-changing command (upload, publish, and execute) with the user before running.
在下载和上传的 
IntegrationVersion
JSON 中，
EmailTask
会在 
taskConfigs[].parameters
内部使用四个对用户可见的参数键：
"To"
（收件人地址的 
stringArray
）、
"Subject"
（
stringValue
）、
"BodyFormat"
（
stringValue
，例如 
"PLAIN_TEXT"
）和 
"TextBody"
（
stringValue
）。下面两个可运行示例也都设置了 
"runAsServiceAccount": "RUN_AS_SA"
（将 
RUN_AS_SA
替换为专用的 service account 邮箱，例如 
order-workflow-sa@PROJECT_ID.iam.gserviceaccount.com
；受治理策略约束的项目必须设置 run-as service account 才能发布，并且调用方需要拥有该账户的 
roles/iam.serviceAccountUser
）。执行 
EmailTask
会发送真实电子邮件，因此运行前务必向用户确认收件人地址（
RECIPIENT_EMAIL
）以及每个会改变状态的命令（上传、发布和执行）。

Example 1: Upload, Publish, and Invoke Workflow with 
curl

示例 1：使用 
curl
上传、发布并调用 Workflow

This example uploads a runnable 
IntegrationVersion
JSON (
versions:upload
creates 
INTEGRATION_NAME
automatically if it does not exist yet, or adds a new 
DRAFT
version if it does), publishes the draft, and invokes 
:execute
. The caller must hold 
roles/iam.serviceAccountUser
on 
RUN_AS_SA
(projects with governance require a run-as service account to publish). Because 
EmailTask
sends real email, confirm 
RECIPIENT_EMAIL
and get user confirmation before running the upload, publish, and execute calls.
bash
set -euo pipefail
export PROJECT_ID="my-project"
export LOCATION="us-central1"
export INTEGRATION_NAME="order-webhook"
export TRIGGER_NAME="order_api"
TOKEN="$(gcloud auth print-access-token)"
BASE_URL="https://integrations.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}"
此示例上传一个可运行的 
IntegrationVersion
JSON（如果 
INTEGRATION_NAME
尚不存在，
versions:upload
会自动创建该 integration；如果已经存在，则添加新的 
DRAFT
version），发布该 draft，然后调用 
:execute
。调用方必须拥有 
RUN_AS_SA
的 
roles/iam.serviceAccountUser
（受治理策略约束的项目必须设置 run-as service account 才能发布）。由于 
EmailTask
会发送真实电子邮件，请在运行 upload、publish 和 execute 调用之前确认 
RECIPIENT_EMAIL
并获得用户确认。
bash
set -euo pipefail
export PROJECT_ID="my-project"
export LOCATION="us-central1"
export INTEGRATION_NAME="order-webhook"
export TRIGGER_NAME="order_api"
TOKEN="$(gcloud auth print-access-token)"
BASE_URL="https://integrations.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}"

1. Write an IntegrationVersion JSON file (set RUN_AS_SA and confirm RECIPIENT_EMAIL with user first; caller needs roles/iam.serviceAccountUser on RUN_AS_SA)

1. Write an IntegrationVersion JSON file (set RUN_AS_SA and confirm RECIPIENT_EMAIL with user first; caller needs roles/iam.serviceAccountUser on RUN_AS_SA)

cat <<'EOF' > /tmp/version.json { "description": "API-triggered order notification integration", "runAsServiceAccount": "RUN_AS_SA", "triggerConfigs": [ { "label": "API Trigger", "triggerType": "API", "triggerNumber": "1", "triggerId": "api_trigger/order_api", "properties": {"Trigger name": "order_api"}, "startTasks": [{"taskId": "1"}] } ], "taskConfigs": [ { "task": "EmailTask", "taskId": "1", "displayName": "Send Email", "taskExecutionStrategy": "WHEN_ALL_SUCCEED", "parameters": { "To": {"key": "To", "value": {"stringArray": {"stringValues": ["RECIPIENT_EMAIL"]}}}, "Subject": {"key": "Subject", "value": {"stringValue": "Order notification for $orderId$"}}, "BodyFormat": {"key": "BodyFormat", "value": {"stringValue": "PLAIN_TEXT"}}, "TextBody": {"key": "TextBody", "value": {"stringValue": "Processing order $orderId$."}} } } ], "integrationParameters": [ { "key": "orderId", "dataType": "STRING_VALUE", "inputOutputType": "IN_OUT", "defaultValue": {"stringValue": "ORD-0000"} } ] } EOF
cat <<'EOF' > /tmp/version.json { "description": "API-triggered order notification integration", "runAsServiceAccount": "RUN_AS_SA", "triggerConfigs": [ { "label": "API Trigger", "triggerType": "API", "triggerNumber": "1", "triggerId": "api_trigger/order_api", "properties": {"Trigger name": "order_api"}, "startTasks": [{"taskId": "1"}] } ], "taskConfigs": [ { "task": "EmailTask", "taskId": "1", "displayName": "Send Email", "taskExecutionStrategy": "WHEN_ALL_SUCCEED", "parameters": { "To": {"key": "To", "value": {"stringArray": {"stringValues": ["RECIPIENT_EMAIL"]}}}, "Subject": {"key": "Subject", "value": {"stringValue": "Order notification for $orderId$"}}, "BodyFormat": {"key": "BodyFormat", "value": {"stringValue": "PLAIN_TEXT"}}, "TextBody": {"key": "TextBody", "value": {"stringValue": "Processing order $orderId$."}} } } ], "integrationParameters": [ { "key": "orderId", "dataType": "STRING_VALUE", "inputOutputType": "IN_OUT", "defaultValue": {"stringValue": "ORD-0000"} } ] } EOF

2. Upload as a new DRAFT version — creates INTEGRATION_NAME if it does not exist yet (confirm with user first)

2. Upload as a new DRAFT version — creates INTEGRATION_NAME if it does not exist yet (confirm with user first)

UPLOAD_BODY="$(jq -n --rawfile content /tmp/version.json '{content: $content, fileFormat: "JSON"}')" VERSION_NAME="$(curl -sS --fail-with-body -X POST
-H "Authorization: Bearer ${TOKEN}"
-H "Content-Type: application/json"
-d "${UPLOAD_BODY}"
"${BASE_URL}/integrations/${INTEGRATION_NAME}/versions:upload"
| jq -r '.integrationVersion.name')" VERSION_ID="${VERSION_NAME##*/}" [[ -n "${VERSION_ID}" && "${VERSION_ID}" != "null" ]] || { echo "upload failed: ${VERSION_NAME}" >&2; exit 1; }
UPLOAD_BODY="$(jq -n --rawfile content /tmp/version.json '{content: $content, fileFormat: "JSON"}')" VERSION_NAME="$(curl -sS --fail-with-body -X POST
-H "Authorization: Bearer ${TOKEN}"
-H "Content-Type: application/json"
-d "${UPLOAD_BODY}"
"${BASE_URL}/integrations/${INTEGRATION_NAME}/versions:upload"
| jq -r '.integrationVersion.name')" VERSION_ID="${VERSION_NAME##*/}" [[ -n "${VERSION_ID}" && "${VERSION_ID}" != "null" ]] || { echo "upload failed: ${VERSION_NAME}" >&2; exit 1; }

3. Publish the DRAFT version (confirm with user first)

3. Publish the DRAFT version (confirm with user first)

curl -sS --fail-with-body -X POST
-H "Authorization: Bearer ${TOKEN}"
-H "Content-Type: application/json"
-d '{}'
"${BASE_URL}/integrations/${INTEGRATION_NAME}/versions/${VERSION_ID}:publish"
curl -sS --fail-with-body -X POST
-H "Authorization: Bearer ${TOKEN}"
-H "Content-Type: application/json"
-d '{}'
"${BASE_URL}/integrations/${INTEGRATION_NAME}/versions/${VERSION_ID}:publish"

4. Invoke the published version synchronously — sends a real email to RECIPIENT_EMAIL (confirm with user first)

4. Invoke the published version synchronously — sends a real email to RECIPIENT_EMAIL (confirm with user first)

curl -sS --fail-with-body -X POST
-H "Authorization: Bearer ${TOKEN}"
-H "Content-Type: application/json"
-H "X-Server-Timeout: 120"
-d "{ "triggerId": "api_trigger/${TRIGGER_NAME}", "inputParameters": { "orderId": {"stringValue": "ORD-1001"} } }"
"${BASE_URL}/integrations/${INTEGRATION_NAME}:execute"
| jq '{executionId, outputParameters}'
undefined
curl -sS --fail-with-body -X POST
-H "Authorization: Bearer ${TOKEN}"
-H "Content-Type: application/json"
-H "X-Server-Timeout: 120"
-d "{ "triggerId": "api_trigger/${TRIGGER_NAME}", "inputParameters": { "orderId": {"stringValue": "ORD-1001"} } }"
"${BASE_URL}/integrations/${INTEGRATION_NAME}:execute"
| jq '{executionId, outputParameters}'
undefined

Example 2: Python Discovery Client Workflow (Built from the API Reference)

示例 2：Python Discovery Client 工作流（基于 API Reference 构建）

No official Python sample is published on 
docs.cloud.google.com
; the following workflow is built from the v1 API discovery document (
google-api-python-client
). The caller must hold 
roles/iam.serviceAccountUser
on 
RUN_AS_SA
(projects with governance require a run-as service account to publish). Because 
EmailTask
sends real email, confirm 
RECIPIENT_EMAIL
and each state-changing call (
upload
, 
publish
, 
execute
) with the user before running. Install dependencies first with 
pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3"
.
python
import json
from googleapiclient.discovery import build

PROJECT_ID = "PROJECT_ID"
LOCATION = "LOCATION"
INTEGRATION_NAME = "INTEGRATION_NAME"
TRIGGER_NAME = "TRIGGER_NAME"
RECIPIENT_EMAIL = "RECIPIENT_EMAIL"
parent = f"projects/{PROJECT_ID}/locations/{LOCATION}"
integration_path = f"{parent}/integrations/{INTEGRATION_NAME}"

service = build("integrations", "v1")
integrations_api = service.projects().locations().integrations()
versions_api = integrations_api.versions()
docs.cloud.google.com
上未发布官方 Python 示例；以下工作流基于 v1 API discovery document（
google-api-python-client
）构建。调用方必须拥有 
RUN_AS_SA
的 
roles/iam.serviceAccountUser
（受治理策略约束的项目必须设置 run-as service account 才能发布）。由于 
EmailTask
会发送真实电子邮件，请在运行每个会改变状态的调用（
upload
、
publish
、
execute
）之前确认 
RECIPIENT_EMAIL
并获得用户确认。请先使用 
pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3"
安装依赖项。
python
import json
from googleapiclient.discovery import build

PROJECT_ID = "PROJECT_ID"
LOCATION = "LOCATION"
INTEGRATION_NAME = "INTEGRATION_NAME"
TRIGGER_NAME = "TRIGGER_NAME"
RECIPIENT_EMAIL = "RECIPIENT_EMAIL"
parent = f"projects/{PROJECT_ID}/locations/{LOCATION}"
integration_path = f"{parent}/integrations/{INTEGRATION_NAME}"

service = build("integrations", "v1")
integrations_api = service.projects().locations().integrations()
versions_api = integrations_api.versions()

1. List existing integrations (read-only)

1. List existing integrations (read-only)

listed = integrations_api.list(parent=parent, pageSize=20).execute() for item in listed.get("integrations", []): print(item["name"], "active=", item.get("active"))
listed = integrations_api.list(parent=parent, pageSize=20).execute() for item in listed.get("integrations", []): print(item["name"], "active=", item.get("active"))

2. Upload a DRAFT version — creates INTEGRATION_NAME if it does not exist yet (set RUN_AS_SA and confirm RECIPIENT_EMAIL and action with user before running; caller needs roles/iam.serviceAccountUser on RUN_AS_SA)

2. Upload a DRAFT version — creates INTEGRATION_NAME if it does not exist yet (set RUN_AS_SA and confirm RECIPIENT_EMAIL and action with user before running; caller needs roles/iam.serviceAccountUser on RUN_AS_SA)

version_dict = { "description": "API-triggered order notification integration", "runAsServiceAccount": "RUN_AS_SA", "triggerConfigs": [{ "label": "API Trigger", "triggerType": "API", "triggerNumber": "1", "triggerId": f"api_trigger/{TRIGGER_NAME}", "properties": {"Trigger name": TRIGGER_NAME}, "startTasks": [{"taskId": "1"}], }], "taskConfigs": [{ "task": "EmailTask", "taskId": "1", "displayName": "Send Email", "taskExecutionStrategy": "WHEN_ALL_SUCCEED", "parameters": { "To": {"key": "To", "value": {"stringArray": {"stringValues": [RECIPIENT_EMAIL]}}}, "Subject": {"key": "Subject", "value": {"stringValue": "Order notification for $orderId$"}}, "BodyFormat": {"key": "BodyFormat", "value": {"stringValue": "PLAIN_TEXT"}}, "TextBody": {"key": "TextBody", "value": {"stringValue": "Processing order $orderId$."}}, }, }], "integrationParameters": [{ "key": "orderId", "dataType": "STRING_VALUE", "inputOutputType": "IN_OUT", "defaultValue": {"stringValue": "ORD-0000"}, }], } upload_resp = versions_api.upload( parent=integration_path, body={"content": json.dumps(version_dict), "fileFormat": "JSON"}, ).execute() version_name = upload_resp["integrationVersion"]["name"]
version_dict = { "description": "API-triggered order notification integration", "runAsServiceAccount": "RUN_AS_SA", "triggerConfigs": [{ "label": "API Trigger", "triggerType": "API", "triggerNumber": "1", "triggerId": f"api_trigger/{TRIGGER_NAME}", "properties": {"Trigger name": TRIGGER_NAME}, "startTasks": [{"taskId": "1"}], }], "taskConfigs": [{ "task": "EmailTask", "taskId": "1", "displayName": "Send Email", "taskExecutionStrategy": "WHEN_ALL_SUCCEED", "parameters": { "To": {"key": "To", "value": {"stringArray": {"stringValues": [RECIPIENT_EMAIL]}}}, "Subject": {"key": "Subject", "value": {"stringValue": "Order notification for $orderId$"}}, "BodyFormat": {"key": "BodyFormat", "value": {"stringValue": "PLAIN_TEXT"}}, "TextBody": {"key": "TextBody", "value": {"stringValue": "Processing order $orderId$."}}, }, }], "integrationParameters": [{ "key": "orderId", "dataType": "STRING_VALUE", "inputOutputType": "IN_OUT", "defaultValue": {"stringValue": "ORD-0000"}, }], } upload_resp = versions_api.upload( parent=integration_path, body={"content": json.dumps(version_dict), "fileFormat": "JSON"}, ).execute() version_name = upload_resp["integrationVersion"]["name"]

3. Publish the DRAFT version (confirm with user before running)

3. Publish the DRAFT version (confirm with user before running)

versions_api.publish( name=version_name, body={"configParameters": {}}, ).execute()
versions_api.publish( name=version_name, body={"configParameters": {}}, ).execute()

4. Invoke the published version synchronously — sends a real email to RECIPIENT_EMAIL (confirm with user before running)

4. Invoke the published version synchronously — sends a real email to RECIPIENT_EMAIL (confirm with user before running)

exec_resp = integrations_api.execute( name=integration_path, body={ "triggerId": f"api_trigger/{TRIGGER_NAME}", "inputParameters": {"orderId": {"stringValue": "ORD-1001"}}, }, ).execute() print("executionId:", exec_resp.get("executionId")) print("outputParameters:", exec_resp.get("outputParameters"))
undefined
exec_resp = integrations_api.execute( name=integration_path, body={ "triggerId": f"api_trigger/{TRIGGER_NAME}", "inputParameters": {"orderId": {"stringValue": "ORD-1001"}}, }, ).execute() print("executionId:", exec_resp.get("executionId")) print("outputParameters:", exec_resp.get("outputParameters"))
undefined

Common Task Gotchas and Limits

常见任务注意事项与限制

  • Data limits: Total cumulative integration data (including inputs and outputs) is capped at 30 MB. Above 10 MB, local execution logging is automatically disabled.
  • Data Mapping: Input and output types must match (cast with 
    TO_STRING
    , 
    TO_INT
    , and so on). Always set a fallback value or null inputs fail the task.
  • Call REST Endpoint: Reaches the public internet only (cannot reach VPC-internal hosts). Fails on HTTP 4xx and 5xx responses. Request max 20 MB, response max 34 MB, max 100 concurrent calls.
  • JavaScript: Uses the V8 engine (Rhino was deprecated January 24, 2025). Never remove the 
    executesScript(event)
    entrypoint. Max script request size is 25 MB.
  • Connectors task: Requires an active Integration Connectors connection (billed separately). Timeout is 3 minutes; Application Integration quotas cap data to and from connections at 8 MB (Integration Connectors quotas list a 10 MB Connectors task payload limit; response max 20 MB).
  • Approval vs Suspend: Approval tasks can be approved or rejected via 
    POST .../executions/EXECUTION_ID/suspensions/SUSPENSION_ID:resolve
    with body 
    {"suspension": {"eventExecutionInfoId": "EXECUTION_ID", "integration": "INTEGRATION_NAME", "taskId": "TASK_ID", "state": "LIFTED"}}
    (or 
    "REJECTED"
    ), which is the same call the Cloud console Approve/Reject buttons make and requires 
    integrations.suspensions.resolve
    . Suspend tasks are resumed via 
    POST .../integrations/INTEGRATION_NAME/executions/EXECUTION_ID/suspensions/SUSPENSION_ID:lift
    (where 
    -
    can replace 
    INTEGRATION_NAME
    and either 
    EXECUTION_ID
    or 
    SUSPENSION_ID
    , provided at least one of 
    EXECUTION_ID
    or 
    SUSPENSION_ID
    is concrete; accepts an optional 
    suspensionResult
    defaulting to 
    Resolved
    ), which requires 
    integrations.suspensions.lift
    . Listing suspensions (
    suspensions.list
    ) requires 
    integrations.suspensions.list
    . All three permissions are included in 
    roles/integrations.suspensionResolver
    (and 
    roles/integrations.integrationAdmin
    ); resuming also requires 
    roles/iam.serviceAccountUser
    on the integration's run-as service account, requires user confirmation first, and runs the remainder of the execution in async mode.
  • Loops and Sub-integrations: For Each Loop and While Loop allow up to 8,000 iterations; For Each Parallel allows up to 10,000 iterations (default parallelism 50). For sub-integration calls (
    Call Integration
    , 
    For Each Loop
    , 
    For Each Parallel
    ), child responses/output parameters are returned to the parent only in 
    SYNC
    mode (
    ASYNC
    calls return no output parameters); avoid 
    SYNC
    mode if the sub-integration exceeds 2 minutes or includes an Approval task.
See references/tasks-and-gotchas.md for the full task catalog, limits, variable reference syntax, and retry strategies.
  • 数据限制：integration 数据总量（包括输入和输出）上限为 30 MB。超过 10 MB 后，将自动禁用本地 execution 日志。
  • 数据映射：输入和输出类型必须匹配（可使用 
    TO_STRING
    、
    TO_INT
    等进行类型转换）。务必设置回退值，否则空值输入会导致任务失败。
  • Call REST Endpoint：只能访问公共互联网（无法访问 VPC 内部主机）。遇到 HTTP 4xx 和 5xx 响应时会失败。请求最大 20 MB，响应最大 34 MB，最多允许 100 个并发调用。
  • JavaScript：使用 V8 engine（Rhino 已于 2025 年 1 月 24 日弃用）。切勿移除 
    executesScript(event)
    入口点。脚本请求大小上限为 25 MB。
  • Connectors 任务：需要处于活跃状态的 Integration Connectors connection（单独计费）。超时时间为 3 分钟；Application Integration 配额将传入和传出 connection 的数据限制在 8 MB（Integration Connectors 配额列出了 10 MB 的 Connectors task payload 上限；响应最大 20 MB）。
  • Approval 与 Suspend：可以通过 
    POST .../executions/EXECUTION_ID/suspensions/SUSPENSION_ID:resolve
    批准或拒绝 Approval task，请求体为 
    {"suspension": {"eventExecutionInfoId": "EXECUTION_ID", "integration": "INTEGRATION_NAME", "taskId": "TASK_ID", "state": "LIFTED"}}
    （或 
    "REJECTED"
    ），这与 Cloud console 中的 Approve/Reject 按钮执行的调用相同，并且需要 
    integrations.suspensions.resolve
    权限。通过 
    POST .../integrations/INTEGRATION_NAME/executions/EXECUTION_ID/suspensions/SUSPENSION_ID:lift
    恢复 Suspend task（其中可以使用 
    -
    替代 
    INTEGRATION_NAME
    ，且 
    EXECUTION_ID
    或 
    SUSPENSION_ID
    至少有一个必须是具体值；还接受可选的 
    suspensionResult
    ，默认值为 
    Resolved
    ），该操作需要 
    integrations.suspensions.lift
    权限。列出 suspension（
    suspensions.list
    ）需要 
    integrations.suspensions.list
    权限。所有三项权限都包含在 
    roles/integrations.suspensionResolver
    （以及 
    roles/integrations.integrationAdmin
    ）角色中；恢复 execution 还需要拥有 integration 的 run-as service account 的 
    roles/iam.serviceAccountUser
    权限，需要事先获得用户确认，并以异步模式运行 execution 的剩余部分。
  • Loop 与 Sub-integration：For Each Loop 和 While Loop 最多允许 8,000 次迭代；For Each Parallel 最多允许 10,000 次迭代（默认并行度为 50）。对于 sub-integration 调用（
    Call Integration
    、
    For Each Loop
    、
    For Each Parallel
    ），只有 
    SYNC
    模式会将子响应或输出参数返回给父级（
    ASYNC
    调用不返回输出参数）；如果 sub-integration 超过 2 分钟或包含 Approval task，请避免使用 
    SYNC
    模式。
有关完整的 task 目录、限制、变量引用语法和重试策略，请参阅 references/tasks-and-gotchas.md。

Promoting Between Environments (CI/CD)

环境间提升（CI/CD）

To promote an integration from development to staging or production:
  1. Externalize environment-specific values (endpoints, project IDs, connection names) as 
    CONFIG_<NAME>
    config variables.
  2. Provision the target region, run-as service account, Integration Connectors connections, and authentication profiles (
    authConfigs
    ) in the target project first (these infrastructure resources are not created by version uploads).
  3. Download the tested version JSON (
    versions:download?fileFormat=JSON
    ), commit it to Git alongside per-environment config files, rewrite 
    .runAsServiceAccount
    to the target environment's run-as service account (
    jq --arg sa "$RUN_AS_SA" '.runAsServiceAccount = $sa' integration.json > integration.env.json
    ) before uploading, and run 
    versions:upload
    + 
    versions:publish
    from Cloud Build or your CI runner (
    versions:upload
    creates the integration automatically in the target project if it does not exist yet, producing a 
    DRAFT
    that 
    :publish
    activates).
See references/cicd-promotion.md for the complete promotion checklist and a ready-to-use Cloud Build pipeline.
要将 integration 从开发环境提升到 staging 或 production：
  1. 将环境特定的值（endpoint、项目 ID、连接名称）外部化为 
    CONFIG_<NAME>
    配置变量。
  2. 首先在目标项目中预配目标区域、run-as service account、Integration Connectors connection 和身份验证配置文件（
    authConfigs
    ）；这些基础架构资源不会由 version 上传操作创建。
  3. 下载经过测试的 version JSON（
    versions:download?fileFormat=JSON
    ），将其与各环境的配置文件一起提交到 Git，在上传前使用 
    jq --arg sa "$RUN_AS_SA" '.runAsServiceAccount = $sa' integration.json > integration.env.json
    将 
    .runAsServiceAccount
    改写为目标环境的 run-as service account，然后在 Cloud Build 或 CI runner 中运行 
    versions:upload
    + 
    versions:publish
    （如果目标项目中尚不存在该 integration，
    versions:upload
    会自动创建它，并生成一个由 
    :publish
    激活的 
    DRAFT
    ）。
有关完整的提升检查清单和可直接使用的 Cloud Build pipeline，请参阅 references/cicd-promotion.md。

Cleanup and Cost Management

清理与成本管理

  • Pricing: An active billing account must be attached to the project even when usage stays within the monthly free tier. Application Integration offers a monthly free tier for executions, data processed, and Google service connector nodes, after which executions, data processed, and Integration Connectors nodes incur charges. Review current thresholds and rates on the Application Integration pricing page and estimate costs with the Google Cloud Pricing Calculator.
  • Unpublish to stop triggers: Run 
    POST .../versions/VERSION_ID:unpublish
    (after user confirmation) to stop scheduled, Pub/Sub, or API triggers from firing.
  • Delete versions or integrations: 
    DELETE .../versions/VERSION_ID
    archives a single version (deleting all versions deletes the integration). 
    DELETE .../integrations/INTEGRATION_NAME
    permanently deletes the integration and all its versions.
  • Connector nodes: Unpublishing or deleting an integration does not delete Integration Connectors connections. Delete unused connections at 
    https://console.cloud.google.com/connectors/connections
    to stop hourly node charges.
  • 定价：即使使用量保持在每月免费额度内，项目也必须关联有效的计费账户。Application Integration 对 execution、处理的数据和 Google service connector node 提供每月免费额度；超出后，execution、处理的数据和 Integration Connectors node 将产生费用。请在 Application Integration pricing page 上查看当前阈值和费率，并使用 Google Cloud Pricing Calculator 估算成本。
  • 取消发布以停止 trigger：运行 
    POST .../versions/VERSION_ID:unpublish
    （获得用户确认后）以停止 scheduled、Pub/Sub 或 API trigger 触发。
  • 删除 version 或 integration：
    DELETE .../versions/VERSION_ID
    会归档单个 version（删除所有 version 会删除该 integration）。
    DELETE .../integrations/INTEGRATION_NAME
    会永久删除该 integration 及其所有 version。
  • Connector node：取消发布或删除 integration 不会删除 Integration Connectors connection。若要停止每小时 node 费用，请在 
    https://console.cloud.google.com/connectors/connections
    删除未使用的 connection。

Reference Guides

Reference Guides

  • REST API Cheatsheet: v1 and v2 endpoints, parameters, filters, and IAM permissions.
  • IntegrationVersion JSON Reference: Schema for 
    triggerConfigs
    , 
    taskConfigs
    , 
    integrationParameters
    , 
    ValueType
    , and config variables.
  • Triggers and Execution Reference: Trigger types, 
    triggerId
    formats, 
    :execute
    vs 
    :schedule
    , OpenAPI generation, and lifting or resolving suspensions.
  • Tasks and Gotchas Reference: Task-by-task rules, quotas, variable reference syntax, and error handling strategies.
  • CI/CD Promotion Reference: Cross-project promotion checklist, environment config pattern, and Cloud Build workflow.
  • REST API Cheatsheet：v1 和 v2 端点、参数、过滤器及 IAM 权限。
  • IntegrationVersion JSON Reference：
    triggerConfigs
    、
    taskConfigs
    、
    integrationParameters
    、
    ValueType
    和配置变量的 schema。
  • Triggers and Execution Reference：trigger 类型、
    triggerId
    格式、
    :execute
    与 
    :schedule
    、OpenAPI 生成，以及暂停解除或审批处理。
  • Tasks and Gotchas Reference：逐任务规则、配额、变量引用语法和错误处理策略。
  • CI/CD Promotion Reference：跨项目提升检查清单、环境配置模式和 Cloud Build 工作流。