application-integration-authoring

应用集成创作

Google Cloud Application Integration 工作流通过 REST API（https://integrations.googleapis.com/v1/...）或基于发现机制的 Google API Python 客户端（googleapiclient.discovery.build("integrations", "v1")）以编程方式编写、版本管理、发布和执行。

没有 gcloud integrations 命令组，没有 Google 管理的 Application Integration MCP 服务，也没有已记录的用于集成或版本的 Terraform 资源。仅将 gcloud 用于身份验证、启用 API 和 IAM 绑定。仅将 Terraform 用于区域预配（google_integrations_client）、身份验证配置（google_integrations_auth_config）和 Integration Connectors（google_integration_connectors_connection）。

对于初始项目设置、区域预配和 IAM 角色定义，请使用 application-integration-basics 技能。对于诊断失败或卡住的运行、执行日志和配额错误，请使用 application-integration-troubleshooting 技能。

安全和确认规则

• 只读操作可直接执行：integrations.list、integrations:search、versions.list、versions.get、versions:download、authConfigs.list 和 executions.list。
• 更改状态或执行操作前须确认：在创建、上传、修补、发布、取消发布、测试、执行、安排或删除集成或版本，或修改 IAM 或身份验证配置之前，向用户展示确切的命令和负载，并取得明确确认。
• 安装软件包（pip install）或更改全局 gcloud 设置（例如 gcloud config set auth/impersonate_service_account）前，先询问用户；并先展示确切的命令。
• 绝不在配置变量中存储机密：配置变量（CONFIG_*）以纯文本形式存储和导出。凭据一律使用身份验证配置（projects.locations.authConfigs）或 Secret Manager 访问任务。

前提条件清单

1. 安装 Google Cloud SDK：如果尚未安装 gcloud，请按照安装 gcloud CLI 操作。
2. 结算和项目：确保 Google Cloud 项目已关联有效的结算账号（即使用量未超出免费层级，也必须关联），然后设置目标项目：

   gcloud config set project PROJECT_ID
   

3. 启用所需的 API：

   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 默认区域设置。编写集成之前，必须通过 Cloud 控制台或 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（或为服务账号设置 GOOGLE_APPLICATION_CREDENTIALS）。
   • 对于服务账号模拟：运行 gcloud config set auth/impersonate_service_account SA_EMAIL（需要 roles/iam.serviceAccountTokenCreator）。
6. 验证 IAM 角色：
   • 创建、上传或编辑草稿：roles/integrations.integrationEditor（涵盖 versions:upload，该操作需要 integrations.integrationVersions.create，以及 versions:publish）
   • 发布或取消发布：roles/integrations.integrationDeployer 或 roles/integrations.integrationEditor（仅有 roles/integrations.integrationDeployer 可以发布现有版本，但无法通过 versions:upload 上传），此外还需将 roles/integrations.serviceAgent 授予 Application Integration 服务 Agent（service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com）
   • 调用集成：roles/integrations.integrationInvoker
   • 以运行身份服务账号执行操作：2026 年 10 月 15 日或之后创建、且使用 API 或 Private 以外任意触发器的集成（例如 Schedule、Cloud Scheduler、Cloud Pub/Sub、Salesforce 或 Connector Event；Private 触发器与 API 触发器一样不受此限制，因此唯一触发器为 Private 的子集成可在未设置 runAsServiceAccount 的情况下发布）若未设置 runAsServiceAccount，则无法测试或发布（区域治理要求所有集成都设置该项）；只要设置了 runAsServiceAccount，发布或测试该版本的用户就需要对其拥有 roles/iam.serviceAccountUser（运行时，调用方或触发器服务账号也需要对其拥有 roles/iam.serviceAccountUser）。

决策流程

目标	操作	端点 / 方法
检查某个区域中的现有集成	列出集成，然后列出版本	GET .../integrations 然后 GET .../versions
将集成版本导出到源代码管理	下载版本 JSON	GET .../versions/VERSION_ID:download?fileFormat=JSON
从 JSON 创建集成或添加新的 DRAFT 版本	上传版本 JSON（如果集成不存在，则创建集成；否则添加新的 DRAFT 版本；仍需执行 :publish）	POST .../integrations/INTEGRATION_NAME/versions:upload
创建全新集成，并在名称冲突时失败	使用 newIntegration=true 创建首个 DRAFT 版本（如果 INTEGRATION_NAME 已存在，则返回 ALREADY_EXISTS）	POST .../integrations/INTEGRATION_NAME/versions?newIntegration=true
编辑现有的 DRAFT 版本	检查 lockHolder，然后执行 patch 或上传	PATCH .../versions/VERSION_ID?updateMask=...
编辑 ACTIVE（已发布）集成	上传或创建新的 DRAFT 版本	POST .../integrations/INTEGRATION_NAME/versions:upload
将特定环境的 URL 或 ID 外置	定义 CONFIG_<NAME>，并在发布时提供	integrationConfigParameters + versions:publish
存储 API 密钥、OAuth 凭据或证书	创建身份验证配置文件	POST .../authConfigs
在生产环境部署前测试集成	发布到非生产项目并调用 :execute	POST .../versions/VERSION_ID:publish 然后 POST .../integrations/INTEGRATION_NAME:execute
部署 DRAFT 以处理实时流量	使用 configParameters 发布版本	POST .../versions/VERSION_ID:publish
同步调用已发布的集成	使用 api_trigger/TRIGGER_NAME 调用 :execute	POST .../integrations/INTEGRATION_NAME:execute
异步调用已发布的集成	使用 scheduleTime 调用 :schedule	POST .../integrations/INTEGRATION_NAME:schedule
在项目之间推广版本（CI/CD）	下载 JSON -> 上传到目标项目 -> 发布	:download -> :upload -> :publish

每种方法的完整请求参数、查询筛选条件和 IAM 权限，请参阅 references/rest-api-cheatsheet.md。

核心创作工作流

1. 列出集成并下载版本

列出 LOCATION 中的集成，并列出特定 INTEGRATION_NAME 的版本：

TOKEN="$(gcloud auth print-access-token)"

# List integrations in the region
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)
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_ID 是版本 name 字段末尾的 UUID）下载为可移植 JSON：

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. 了解 IntegrationVersion 结构

IntegrationVersion JSON 对象包含四个主要数组和版本级设置：

• triggerConfigs：启动工作流的入口点。每个条目都需要一个唯一的 triggerNumber，以及 triggerType（例如 API 或 PRIVATE_TRIGGER）、可选的 triggerId（如果省略，则根据 properties 自动生成；对于 API 触发器，格式为 api_trigger/TRIGGER_NAME），以及指向第一个 taskId 的 startTasks。
• taskConfigs：工作单元。每个条目都需要 task（任务类型，例如公开上传示例中的 EmailTask，或发现枚举说明中的 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；上传或创建的草稿 JSON 中顶层的 value 会被丢弃，因此各环境的值应在发布时放入 configParameters）。
• runAsServiceAccount：专用的用户管理服务帐号电子邮件地址。设置此项且任务未配置身份验证配置文件（authConfig）时，它会用于为 Connector（Connectors）、REST（Call REST Endpoint）和 Cloud Function 任务生成身份验证令牌；任务上配置的身份验证配置文件优先于 runAsServiceAccount。

始终使用 triggerConfigs、taskConfigs 和 integrationParameters。切勿使用已弃用的 triggerConfigsInternal、taskConfigsInternal 或 integrationParametersInternal。字段架构、ValueType 结构以及最简 IntegrationVersion JSON 模板，请参阅 references/integration-version-json.md。

3. 创建或上传 DRAFT 版本

每个集成最多允许 100 个版本和 100 个任务，且 INTEGRATION_NAME 最多可包含 64 个字符。调用 versions:upload 会创建一个新的 DRAFT 版本：如果 INTEGRATION_NAME 尚不存在，则自动创建集成；如果已存在，则添加下一个 DRAFT 版本（例如，上传到版本 5 会创建版本 6）。上传的版本处于 DRAFT 状态，仍需调用 versions:publish 才能接收流量。仅当你明确希望在 INTEGRATION_NAME 已存在时调用失败并返回 ALREADY_EXISTS，才使用 POST .../versions?newIntegration=true（传入 IntegrationVersion JSON 请求体）。

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

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

4. 版本状态和编辑锁规则

状态	含义	可编辑？	可提供触发器服务？
DRAFT	正在编辑的版本；其编辑锁由作者（lockHolder 邮箱）持有，自上次更新起有效 15 分钟	是（仅限 lockHolder）	否
ACTIVE	已发布、正在提供实时流量服务的版本	否	是
SNAPSHOT	先前的草稿（其他作者在控制台接手时产生）或未发布的版本（PREVIOUSLY_PUBLISHED）	否	否
ARCHIVED	通过 versions.delete 软删除（无法恢复；在 Integration 版本文档页面上列为 DELETED）	否	否

• 编辑锁强制规则：DRAFT 版本的编辑锁由其作者（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 控制台中点击 接管，这会将现有草稿转换为 SNAPSHOT 并创建新的 DRAFT。

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

• 配置变量（CONFIG_<NAME>）：用于非机密环境值（后端主机名、Pub/Sub 主题、连接名称）。在草稿的 integrationConfigParameters 中定义（将任何默认值放在 parameter.defaultValue 中，因为草稿顶层的 value 会被丢弃），并在调用 versions:publish 时通过 configParameters 传入各环境的值。注意事项：发布时 configParameters 中的键必须与 integrationConfigParameters 中的某个键完全一致，包括反引号（例如，"`CONFIG_target_url`"）；未知键会被静默忽略，而不会被拒绝（versions:publish 会返回 200，且保留默认值）。配置变量不能用于配置 Integration Connectors 实体操作或动作。
• 身份验证配置文件（authConfigs）：用于 API 密钥、OAuth 2.0 凭据、JWT、OIDC 令牌、SSL/TLS 证书和服务账号。身份验证配置文件是区域资源（projects/PROJECT_ID/locations/LOCATION/authConfigs/AUTH_CONFIG_ID），下载 Integration 版本时不会包含这些资源。请在每个目标项目中通过 POST .../authConfigs 或 Terraform google_integrations_auth_config 创建它们。

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

• 推荐的测试方式：在非生产项目中发布版本（versions:publish）来测试集成，然后在该项目中调用 integrations:execute。
  • 关于 integrations:test 的说明：v1 REST API 提供了用于测试 DRAFT 的 POST .../integrations/INTEGRATION_NAME:test，该接口要求提供 TestIntegrationsRequest.clientId（“必填。此值用于标识将代表其执行事件的客户端。”），但公开文档没有说明应传入什么值。不要臆造 clientId 值；请改为发布到非生产项目并调用 :execute。（草稿测试也无法运行 Approval、Suspend 或 Timer 任务，并且只有在发布后，Call REST Endpoint 身份验证配置文件的更改才会生效。）
• 发布（versions:publish）：将版本部署为 ACTIVE 并释放任何编辑锁（如果版本已经是 ACTIVE 或 ARCHIVED，或者版本为 DRAFT 且其 lockHolder 与调用方不同，则会失败）。之前处于 ACTIVE 状态的版本会自动取消发布，依赖服务也会切换到新发布的版本。
  • 注意：发布新版本会自动取消先前版本的所有挂起执行。
  • 注意：由于最终一致性，新版本发布后，先前版本可能会继续运行最多 10 分钟。
• 取消发布（versions:unpublish）：将 ACTIVE 版本转为 SNAPSHOT（标记为 PREVIOUSLY_PUBLISHED；如果版本不是 ACTIVE，则会失败），并停止触发器和依赖服务。

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

7. 执行（同步）与调度（异步）

只有 ACTIVE（已发布）版本才能通过 execute 或 schedule 调用。对于 API 触发器，triggerId 始终为 api_trigger/TRIGGER_NAME（其中 TRIGGER_NAME 最长为 64 个字符）。在 execute 中将 INTEGRATION_NAME 设为 -，会运行该区域内所有共享 triggerId 的已发布集成。

方法	模式	最大超时	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，或者某个任务使用了失败策略 IGNORE 或 NONE 并带有备用路径，那么即使某个任务失败，HTTP 调用仍会返回 200 OK。务必通过 executions.list?filter=execution_id="EXECUTION_ID" 验证执行记录（检查 executionDetails.state、每个任务的 taskExecutionState，以及 Execution.responseParameters 中的 ErrorInfo；当 doNotPropagateError 为 true 时，错误也会作为 PostWithTriggerIdExecutionException 返回在事件参数中）。不要依赖旧版/已弃用的 executionFailed 字段。

有关所有触发器类型、ValueType 输入格式、OpenAPI 规范生成，以及解除挂起和审批处理，请参阅 references/triggers-and-execution.md。

端到端版本和 API 工作流示例

在下载和上传的 IntegrationVersion JSON 中，EmailTask 在 taskConfigs[].parameters 内使用四个用户可见的参数键："To"（收件人地址的 stringArray）、"Subject"（stringValue）、"BodyFormat"（stringValue，例如 "PLAIN_TEXT"）和 "TextBody"（stringValue）。以下两个可运行示例还会设置 "runAsServiceAccount": "RUN_AS_SA"（将 RUN_AS_SA 替换为专用服务账号邮箱，例如 order-workflow-sa@PROJECT_ID.iam.gserviceaccount.com；受治理约束的项目需要运行身份服务账号才能发布，且调用方需要对此账号拥有 roles/iam.serviceAccountUser）。执行 EmailTask 会发送真实邮件，因此运行前务必确认收件人地址（RECIPIENT_EMAIL），并就每条会改变状态的命令（上传、发布和执行）征得用户确认。

示例 1：使用 curl 上传、发布和调用工作流

此示例上传可运行的 IntegrationVersion JSON（如果 INTEGRATION_NAME 尚不存在，versions:upload 会自动创建它；如果已存在，则会添加一个新的 DRAFT 版本），发布该草稿，并调用 :execute。调用方必须对 RUN_AS_SA 拥有 roles/iam.serviceAccountUser（受治理约束的项目需要运行身份服务账号才能发布）。由于 EmailTask 会发送真实邮件，运行上传、发布和执行调用前，请确认 RECIPIENT_EMAIL 并征得用户确认。

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)
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)
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)
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)
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}'

示例 2：Python Discovery 客户端工作流（基于 API 参考构建）

docs.cloud.google.com 上没有发布官方 Python 示例；以下工作流基于 v1 API Discovery 文档（google-api-python-client）构建。调用方必须对 RUN_AS_SA 拥有 roles/iam.serviceAccountUser（受治理约束的项目需要运行身份服务账号才能发布）。由于 EmailTask 会发送真实邮件，运行前请确认 RECIPIENT_EMAIL，并就每次会改变状态的调用（upload、publish、execute）征得用户确认。请先使用 pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3" 安装依赖。

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

常见任务注意事项和限制

• 数据限制：集成数据的累计总量（包括输入和输出）上限为 30 MB。超过 10 MB 后，会自动禁用本地执行日志记录。
• 数据映射：输入和输出类型必须匹配（使用 TO_STRING、TO_INT 等进行转换）。务必设置回退值，否则空值输入会导致任务失败。
• 调用 REST 端点：只能访问公共互联网（无法访问 VPC 内部主机）。HTTP 4xx 和 5xx 响应会导致任务失败。请求上限为 20 MB，响应上限为 34 MB，最多可同时发起 100 次调用。
• JavaScript：使用 V8 引擎（Rhino 已于 January 24, 2025 弃用）。切勿移除 executesScript(event) 入口点。脚本请求大小上限为 25 MB。
• Connectors 任务：需要有效的 Integration Connectors 连接（需单独计费）。超时时间为 3 分钟；Application Integration 配额将进出连接的数据限制为 8 MB（Integration Connectors 配额列出的 Connectors 任务负载上限为 10 MB；响应上限为 20 MB）。
• Approval 与 Suspend：可通过 POST .../executions/EXECUTION_ID/suspensions/SUSPENSION_ID:resolve 并使用请求体 {"suspension": {"eventExecutionInfoId": "EXECUTION_ID", "integration": "INTEGRATION_NAME", "taskId": "TASK_ID", "state": "LIFTED"}}（或 "REJECTED"）批准或拒绝 Approval 任务；这与 Cloud 控制台中的 Approve/Reject 按钮执行相同的调用，并且需要 integrations.suspensions.resolve 权限。Suspend 任务通过 POST .../integrations/INTEGRATION_NAME/executions/EXECUTION_ID/suspensions/SUSPENSION_ID:lift 恢复（其中 - 可替代 INTEGRATION_NAME、EXECUTION_ID 或 SUSPENSION_ID，前提是 EXECUTION_ID 或 SUSPENSION_ID 至少有一个为具体值；可选参数 suspensionResult 默认值为 Resolved），这需要 integrations.suspensions.lift 权限。列出暂停项（suspensions.list）需要 integrations.suspensions.list 权限。roles/integrations.suspensionResolver（以及 roles/integrations.integrationAdmin）包含全部三项权限；恢复执行还需要在集成的运行身份服务账号上拥有 roles/iam.serviceAccountUser，且必须先取得用户确认，剩余执行部分会以异步模式运行。
• 循环和子集成：For Each Loop 和 While Loop 最多允许迭代 8,000 次；For Each Parallel 最多允许迭代 10,000 次（默认并行度为 50）。对于子集成调用（Call Integration、For Each Loop、For Each Parallel），仅在 SYNC 模式下，子级响应/输出参数才会返回给父级（ASYNC 调用不会返回输出参数）；如果子集成运行时间超过 2 分钟或包含 Approval 任务，请避免使用 SYNC 模式。

完整的任务目录、限制、变量引用语法和重试策略，请参阅 references/tasks-and-gotchas.md。

在环境之间推广（CI/CD）

要将集成从开发环境推广到预发布或生产环境：

1. 将特定于环境的值（端点、项目 ID、连接名称）外部化为 CONFIG_<NAME> 配置变量。
2. 先在目标项目中配置目标区域、运行身份服务账号、Integration Connectors 连接和身份验证配置文件（authConfigs）（上传版本不会创建这些基础设施资源）。
3. 下载已测试版本的 JSON（versions:download?fileFormat=JSON），将其与各环境的配置文件一同提交到 Git；上传前，将 .runAsServiceAccount 改写为目标环境的运行身份服务账号（jq --arg sa "$RUN_AS_SA" '.runAsServiceAccount = $sa' integration.json > integration.env.json）；然后通过 Cloud Build 或 CI 运行器执行 versions:upload 和 versions:publish（如果目标项目中尚不存在该集成，versions:upload 会自动创建它，并生成一个由 :publish 激活的 DRAFT）。

请参阅 references/cicd-promotion.md，了解完整的推广检查清单和可直接使用的 Cloud Build 流水线。

清理与成本管理

• 定价：即使使用量处于每月免费额度内，项目也必须关联有效的结算账号。Application Integration 提供每月免费额度，适用于执行次数、处理的数据量和 Google 服务连接器节点；超过额度后，执行次数、处理的数据量和 Integration Connectors 节点将产生费用。请在 Application Integration 定价页面查看当前额度和费率，并使用 Google Cloud 价格计算器估算费用。
• 取消发布以停止触发器：运行 POST .../versions/VERSION_ID:unpublish（需先获得用户确认），以停止计划任务、Pub/Sub 或 API 触发器。
• 删除版本或集成：DELETE .../versions/VERSION_ID 会将单个版本归档（删除所有版本会删除该集成）。DELETE .../integrations/INTEGRATION_NAME 会永久删除该集成及其所有版本。
• 连接器节点：取消发布或删除集成不会删除 Integration Connectors 连接。请在 https://console.cloud.google.com/connectors/connections 删除未使用的连接，以停止按小时计费的节点费用。

参考指南

• REST API 速查表：v1 和 v2 端点、参数、筛选器及 IAM 权限。
• IntegrationVersion JSON 参考：triggerConfigs、taskConfigs、integrationParameters、ValueType 和配置变量的架构。
• 触发器与执行参考：触发器类型、triggerId 格式、:execute 与 :schedule 的区别、OpenAPI 生成，以及解除或处理暂停状态。
• 任务与注意事项参考：各任务的规则、配额、变量引用语法和错误处理策略。
• CI/CD 推广参考：跨项目推广检查清单、环境配置模式和 Cloud Build 工作流。