application-integration-authoring

アプリケーション統合の作成

Google Cloud Application Integration のワークフローは、REST API（https://integrations.googleapis.com/v1/...）またはディスカバリーベースの Google API Python クライアント（googleapiclient.discovery.build("integrations", "v1")）を通じて、プログラムから作成、バージョン管理、公開、実行できます。

gcloud integrations コマンドグループはなく、Application Integration 用の Google 管理 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 config set auth/impersonate_service_account などのグローバルな gcloud 設定の変更を行う前に、ユーザーに確認してください。まず正確なコマンドを提示してください。
• シークレットを構成変数に保存しないでください：構成変数（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 のロケーションで対象のリージョンがサポートされていることを確認してください。ユーザーに希望がない場合は、広くサポートされているデフォルトとして 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（integrations.integrationVersions.create が必要な versions:upload と versions:publish が対象です）
   • 公開または公開解除：roles/integrations.integrationDeployer または roles/integrations.integrationEditor（roles/integrations.integrationDeployer だけでは既存バージョンを公開できますが、versions:upload によるアップロードはできません）。また、Application Integration のサービスエージェント（service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com）に roles/integrations.serviceAgent が付与されている必要があります。
   • インテグレーションの呼び出し：roles/integrations.integrationInvoker
   • 実行用サービスアカウントとして動作する場合：2026 年 10 月 15 日以降に作成された、API トリガーまたは Private トリガー以外のトリガー（Schedule、Cloud Scheduler、Cloud Pub/Sub、Salesforce、Connector Event など）を持つインテグレーションは、runAsServiceAccount が設定されていないとテストまたは公開できません（Private トリガーは API トリガーと同様に対象外のため、Private トリガーのみを持つサブインテグレーションは runAsServiceAccount を設定せずに公開できます）。リージョンのガバナンスで、すべてのインテグレーションに設定が必要な場合もあります。runAsServiceAccount を設定した場合、バージョンを公開またはテストするユーザーは、そのサービスアカウントに対する roles/iam.serviceAccountUser が必要です（実行時には、呼び出し元またはトリガーのサービスアカウントに、そのサービスアカウントに対する roles/iam.serviceAccountUser が必要です）。

意思決定フロー

目標	アクション	エンドポイント／メソッド
リージョン内の既存の統合を確認する	統合を一覧表示し、次にバージョンを一覧表示します	GET .../integrations then 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 .../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 then 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 オブジェクトには、4 つの主要な配列とバージョンレベルの設定が含まれます。

• triggerConfigs：ワークフローを開始するエントリポイントです。各エントリには、一意の triggerNumber、triggerType（API や PRIVATE_TRIGGER など）、省略可能な triggerId（省略した場合は properties から自動生成されます。API トリガーの場合は api_trigger/TRIGGER_NAME）、および最初の taskId を指す startTasks が必要です。
• taskConfigs：作業単位です。各エントリには、task（タスクの種類。公開アップロードサンプルの EmailTask や、ディスカバリー enum の説明にある FieldMappingTask など）、一意の taskId、parameters、nextTasks、および省略可能な failurePolicy または errorCatcherId が必要です。
• integrationParameters：入力、出力、一時変数です（key、STRING_VALUE や JSON_VALUE などの dataType、IN、OUT、IN_OUT、IN_OUT_TYPE_UNSPECIFIED のいずれかの inputOutputType、および defaultValue）。
• integrationConfigParameters：環境固有の設定変数の定義です（キーが `CONFIG_<NAME>` の parameter と 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 が必要です。POST .../versions?newIntegration=true（IntegrationVersion JSON 本文を渡す）は、INTEGRATION_NAME がすでに存在する場合に呼び出しを ALREADY_EXISTS で失敗させたいときに限り使用してください。

# 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	編集中のバージョンです。最終更新から15分間、作成者（lockHolder のメールアドレス）が編集ロックを保持します	はい（lockHolder のみ）	いいえ
ACTIVE	ライブトラフィックを処理する公開済みバージョンです	いいえ	はい
SNAPSHOT	過去のドラフト（コンソールで別の作成者が引き継いだ場合）または未公開のバージョン（PREVIOUSLY_PUBLISHED）です	いいえ	いいえ
ARCHIVED	versions.delete によって論理削除されたバージョンです（復元できません。Integration versions のドキュメントページでは 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 コンソールで Take Over をクリックしてください（既存のドラフトが 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）であり、統合バージョンをダウンロードしても含まれません。各対象プロジェクトで 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. 実行（同期）とスケジュール（非同期）

execute または schedule で呼び出せるのは、ACTIVE（公開済み）バージョンのみです。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 内で、顧客に表示される次の 4 つのパラメータキーを使用します。「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 をアップロードし（versions:upload は、まだ存在しない場合は INTEGRATION_NAME を自動的に作成し、存在する場合は新しい 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 Client ワークフロー（API リファレンスを基に作成）

公式の Python サンプルは docs.cloud.google.com では公開されていません。以下のワークフローは、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などで型変換します）。必ずフォールバック値を設定してください。設定しないと、入力がnullの場合にタスクが失敗します。
• RESTエンドポイントの呼び出し：パブリックインターネットにのみアクセスできます（VPC内部のホストにはアクセスできません）。HTTP 4xxおよび5xxレスポンスでは失敗します。リクエストは最大20 MB、レスポンスは最大34 MBで、同時呼び出しは最大100件です。
• JavaScript：V8エンジンを使用します（Rhinoは2025年1月24日に非推奨となりました）。エントリーポイントのexecutesScript(event)は削除しないでください。スクリプトリクエストの最大サイズは25 MBです。
• Connectorsタスク：アクティブなIntegration Connectors接続が必要です（別途課金されます）。タイムアウトは3分です。Application Integrationのクォータでは、接続との間で送受信できるデータは8 MBまでです（Integration Connectorsのクォータでは、Connectorsタスクのペイロード上限は10 MB、レスポンスの上限は20 MBです）。
• 承認と一時停止の違い：承認タスクは、POST .../executions/EXECUTION_ID/suspensions/SUSPENSION_ID:resolveに本文{"suspension": {"eventExecutionInfoId": "EXECUTION_ID", "integration": "INTEGRATION_NAME", "taskId": "TASK_ID", "state": "LIFTED"}}（または"REJECTED"）を指定して、承認または却下できます。これはCloudコンソールの［承認］／［却下］ボタンと同じ呼び出しで、integrations.suspensions.resolveが必要です。一時停止タスクを再開するには、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が必要です。これら3つの権限はすべて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分を超える場合や、承認タスクを含む場合は、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 を生成します）。

昇格のチェックリスト全文と、そのまま使用できる Cloud Build パイプラインについては、references/cicd-promotion.md をご覧ください。

クリーンアップとコスト管理

• 料金：使用量が月間無料枠内に収まる場合でも、プロジェクトに有効な請求先アカウントを関連付ける必要があります。Application Integration では、実行、処理データ、Google サービスコネクタノードに月間無料枠が適用されます。無料枠を超えると、実行、処理データ、Integration Connectors ノードに料金が発生します。現在の上限と料金は、Application Integration の料金ページで確認し、Google Cloud Pricing Calculator で費用を見積もってください。
• トリガーを停止するには非公開にする：ユーザーの確認後、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 のワークフロー。