application-integration-basics

Application Integration の基本

Application Integration は、Google Cloud サービスとサードパーティの SaaS アプリケーションを接続するための、Google Cloud のサーバーレスで自動スケーリングする Integration-Platform-as-a-Service（iPaaS）です。トリガー、タスク、データマッピング、Integration Connectors の接続で構成されるイベント駆動型ワークフローを実行し、サーバーの管理は不要です。このスキルを使って、Application Integration がワークロードに適しているかを判断し、プロジェクトとリージョンを設定し、IAM と実行用サービスアカウントを構成し、適切な API またはツールインターフェースを選択し、プラットフォームの制限を考慮した設計を行います。

Application Integration とカスタムのグルーコードの使い分け

Application Integration を選ぶ場合...	カスタムコード（Cloud Run / Cloud Functions）を選ぶ場合...
事前構築済みの Integration Connectors を使って、SaaS アプリ（CRM、ERP、データベース、Google Cloud サービス）を接続する場合。	サブ秒のレイテンシやカスタムのバイナリプロトコルが必要な場合。
API、Pub/Sub、Cloud Scheduler、Salesforce、Connector Event の各トリガーによるイベント駆動型ワークフローをオーケストレーションする場合。	ワークフロー全体のデータが 30 MB を超える場合（API トリガーの入力と Connector のペイロードは 8 MB を超える場合）。
コンテナをデプロイせずに、Data Mapping または Jsonnet を使って JSON／配列データを視覚的に変換する場合。	同期実行が 2 分を超える場合、または非同期実行が 10 分を超える場合。
人による確認のためにワークフローを一時停止する場合（Approval または Suspend タスクで最大 31 日間）。	Private Service Connect コネクタを使わずに、VPC 専用の HTTP エンドポイントを直接呼び出す必要がある場合（Call REST Endpoint はパブリックインターネットにのみアクセスします）。
ADK の ApplicationIntegrationToolset を使って、エンタープライズワークフローやコネクタを AI エージェントのツールとして公開する場合。	JavaScript（V8）や Jsonnet のタスクを超える任意の言語パッケージや、メモリ内での大規模な計算が必要な場合。

安全性と確認のルール

• 読み取り専用の確認は自由に実行できます：事前に確認を求めずに、gcloud services list、gcloud projects get-iam-policy、および https://integrations.googleapis.com/v1/... または https://connectors.googleapis.com/v1/... への HTTP GET 呼び出しを実行できます。
• 状態を変更する前に、必ずユーザーの明示的な確認を得てください：以下の操作を行う前に、実行するコマンドまたはリクエストペイロードを正確に提示し、ユーザーの承認を待ってください。
  • API を有効にする（gcloud services enable）。
  • リージョンをプロビジョニングする（clients:provision、または google_integrations_client に対する terraform apply）。特に顧客管理の暗号鍵（CMEK）を使う場合は注意してください。リージョンで CMEK を有効にすると、元に戻すことはできません。
  • IAM ポリシーを変更する（gcloud projects add-iam-policy-binding または gcloud iam service-accounts add-iam-policy-binding）。
  • インテグレーション、バージョン、認証プロファイル、または接続を作成、アップロード、公開、非公開化、実行、テスト、削除する。
• インテグレーション、バージョン、認証プロファイル、または接続を無人で削除する破壊的なスクリプトを、決してまとめて実行しないでください。
• パッケージをインストールする（pip install）場合や、gcloud config set auth/impersonate_service_account などのグローバルな gcloud 設定を変更する場合は、必ず事前にユーザーに確認してください。最初に実行するコマンドを正確に提示してください。

インターフェースの選択

Application Integration には gcloud integrations コマンドグループ（および gcloud connectors コマンドグループ）がなく、Google が管理するリモート MCP サーバーもありません。REST API が主要な制御および実行インターフェースです。

インターフェース	対応範囲	認証
REST API（curl）	v1 の全機能：リージョンのプロビジョニング、インテグレーション、バージョン、ダウンロード／アップロード、公開、実行、スケジュール、実行履歴、一時停止、authConfigs、テンプレート。	Authorization: Bearer $(gcloud auth print-access-token)
Python ディスカバリークライアント	googleapiclient.discovery.build("integrations", "v1") 経由の v1 の全機能（および build("integrations", "v2") 経由の v2。専用の Cloud Client Library はありません）。pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3" でインストールします。	Application Default Credentials（gcloud auth application-default login）
Terraform（hashicorp/google）	インフラストラクチャのみ：google_integrations_client（リージョンの設定）、google_integrations_auth_config、google_integration_connectors_*。インテグレーションのワークフローバージョンは管理しません。	ADC または Terraform プロバイダーの認証情報
ADK（ApplicationIntegrationToolset）	公開済みの API トリガーインテグレーション、または Integration Connectors のアクション／エンティティを、ADK エージェント用のツールとして公開します（Python v0.1.0 以降、Java v0.3.0 以降）。	ADC（gcloud auth application-default login）またはサービスアカウントの JSON
Cloud コンソール	ビジュアルなドラッグ＆ドロップエディター、簡易／詳細のリージョン設定、Approval タスクの解決、OAuth 2.0 認可コードの同意フロー。	ブラウザーでの Google Cloud サインイン

• gcloud は、API の有効化（gcloud services enable）、アクセストークンの表示（gcloud auth print-access-token）、IAM の管理、Cloud Logging の読み取り（gcloud logging read）など、一般的な Google Cloud タスクにのみ使用してください。
• Integration Connectors には、ワークフローから外部 MCP サーバーをコネクターのターゲットとして呼び出せる、アウトバウンドの MCP コネクター（MCP v1 および v2）があります。これはアウトバウンドコネクターであり、Application Integration を制御するための Google 管理 MCP サーバーではありません。
• REST 呼び出しでは、常にグローバルエンドポイント https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/... を一貫して使用してください。
• ドラフトのテストに関する注意（integrations:test）：v1 REST API には POST .../integrations/INTEGRATION_NAME:test が存在しますが、必須の TestIntegrationsRequest.clientId の値は公開ドキュメントに記載されていないため、値を推測しないでください。本番以外のプロジェクトにインテグレーションを公開し、:execute を呼び出してテストしてください。
• 認証の設定、curl コマンド、Python ディスカバリークライアントの使用パターン、ADK ApplicationIntegrationToolset の設定については、references/api-access.md を参照してください。

リージョン設定の手順

Application Integration はリージョン単位です。対象リージョンが Application Integration locations でサポートされていることを確認してください。ユーザーに希望がない場合は、サポートが充実しているデフォルトのリージョンとして us-central1 を使用してください。リージョンは、すべての REST パスで LOCATION に指定します。Application Integration には gcloud のデフォルトリージョン設定は適用されません。プロビジョニングはリージョンごとに行います。us-central1 をプロビジョニングしても、europe-west1 はプロビジョニングされません。PROJECT_ID で使用する LOCATION ごとに、リージョンのプロビジョニングを繰り返してください。設定の前に、アクティブな請求先アカウントが PROJECT_ID に関連付けられていることを確認してください。使用量が月間無料枠の範囲内であっても、アクティブな請求先アカウントが必要です（Application Integration の料金ページを参照）。

1. 必須 API の確認と有効化

まず、すでに有効になっている API を確認します（読み取り専用）：

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

ユーザーの確認を得た後、必須 API を有効にします（CMEK を設定する場合に限り、cloudkms.googleapis.com を追加します）：

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

2. 呼び出し元の IAM ロール設定を確認する

Application Integration の設定には、roles/integrations.integrationAdmin、roles/connectors.admin、roles/editor（CMEK を使用する場合は roles/cloudkms.admin も）が必要です。現在のバインディングを読み取り専用で確認します。

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

3. リージョン（LOCATION）をプロビジョニングする

ユーザーの確認を得てから、サポートされている次の 3 つの方法のいずれかを選択します。

• オプション A：REST（clients:provision）

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

  プロビジョニングが成功すると、応答は {} になります（clients:provision は runAsServiceAccount を適用しません。各インテグレーションバージョンで実行 ID を設定するには、IntegrationVersion.runAsServiceAccount を使用してください）。リージョンがすでにプロビジョニングされている場合も {} が返されます。この呼び出しによって、既存のリージョンの設定が変更されることはありません。既存のリージョンで HTTP 呼び出しや暗号化を変更するには、コンソールの「Regions」ページを使用してください（リージョンがすでに ACTIVE の場合、clients:provision の cloudKmsConfig、enableHttpCall、enableManagedAiFeatures は適用されません）。PROJECT_ID がすでに Apigee Integration に登録されている場合、プロビジョニングは失敗します。

• オプション B：Cloud コンソール https://console.cloud.google.com/integrations を開き、LOCATION を選択して、Quick setup（API を有効化し、デフォルトのサービスアカウントを作成して、Google 管理の暗号化を使用します）または Advanced setup（CMEK、HTTP 呼び出し、AI 機能、ガバナンス、変数のマスキングを設定します）をクリックします。後から別のリージョンを追加するには、「Regions > Provision new region」に移動します。

• オプション C：Terraform（google_integrations_client） hashicorp/google の google_integrations_client リソースを使用します。google_integrations_client に run_as_service_account を設定しないでください。この引数はプロバイダー v8.0.0（2026 年 8 月 26 日）で削除されており、clients:provision の runAsServiceAccount フィールドに対応していましたが、このフィールドも適用されません。代わりに、各インテグレーションバージョンで実行 ID（IntegrationVersion.runAsServiceAccount）を設定してください。

4. リージョンへのアクセスを簡易確認する

リージョンに対して読み取り専用のリスト呼び出しを実行します。200 OK が返されれば、LOCATION で API にアクセスできる目安になります。

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

すべての ProvisionClientRequest フィールド、CMEK とガバナンスのオプション、Terraform の完全な例については、references/provisioning-and-terraform.md を参照してください。

コアコンセプトの概要

• インテグレーションとトリガー：インテグレーションは、1 つ以上のトリガーによって開始されるワークフローです。同期待ちの実行（SYNC）は完了を待って出力を返します（integrations.execute、コンソールでのテスト、同期型のCall Integration）。非同期実行（ASYNC）は、完了を待たずに実行されます（integrations.schedule、Schedule、Cloud Scheduler、Cloud Pub/Sub、Salesforce トリガー、一時停止または承認後に再開される実行）。
• タスク：トリガーの後に連鎖して実行される作業単位です（Data Mapping、Call REST Endpoint、Connectors、V8 上のJavaScript、Cloud Function、Approval、Suspend、Timer、ループ、Call Integrationなど）。
• バージョンと編集ロック：編集できるのはDRAFTバージョンのみです（最終更新から 15 分間、作成者にロックされます）。トリガーから実行されるのはACTIVE（公開済み）バージョンのみです。バージョンを公開すると、それまでのアクティブバージョンは自動的に公開解除され、そのバージョンで一時停止中の実行はすべてキャンセルされます。公開を解除すると、アクティブバージョンはSNAPSHOT（PREVIOUSLY_PUBLISHED）に移行します。versions.deleteを呼び出すと、バージョンはARCHIVEDにソフト削除されます（インテグレーションのバージョンに関するドキュメントページではDELETEDとして表示されます）。
• 変数：
  • インテグレーション変数：明示的な入力（IN）、出力（OUT）、IN_OUT、またはIN_OUT_TYPE_UNSPECIFIEDの内部変数（$varName$）です。
  • タスク変数：自動生成されるタスク出力で、`Task_<taskId>_<variableName>`という名前です。ここでtaskIdはtaskConfigs[].taskIdに含まれるタスク番号のみです（例：taskIdが"1"の場合は$`Task_1_responseBody`$）。
  • システム変数：キーはバッククォートで囲まれています（`ExecutionId`、`ExecutionMode`、`ErrorInfo`［message、code］、`IntegrationName`、`Region`、`ProjectId`）。$`ExecutionId`$のように参照してください（$ExecutionId$は存在しないインテグレーション変数を指すため、エラーになります）。
  • 構成変数（プレビュー）：integrationConfigParametersで定義される環境固有の値です（デフォルト値はparameter.defaultValueに設定します。ドラフトの最上位にあるvalueは破棄されます）。公開時にconfigParametersで環境ごとの値を指定します（名前は`CONFIG_<NAME>`です）。configParametersのキーは、integrationConfigParameters内のキーとバッククォートも含めて完全に一致する必要があります。たとえば"`CONFIG_target_url`"です。一致しないキーは黙って無視されるため、公開は 200 を返し、デフォルト値がそのまま使われます。構成変数にシークレットを保存しないでください。平文でエクスポートされます。代わりに認証プロファイル（authConfigs）または Secret Manager タスクを使用してください。
• 一時停止：Suspendタスクは最大 31 日間一時停止し、Suspensions API（suspensions:lift。省略可能なsuspensionResultを指定できます。integrations.suspensions.liftが必要です）を使って再開します。Approvalタスクは承認者にメールを送信し、Cloud コンソール UI またはsuspensions:resolve（stateは"LIFTED"または"REJECTED"、integrations.suspensions.resolveが必要です）から承認または却下できます。一時停止の一覧表示（suspensions.list）にはintegrations.suspensions.listが必要です。3 つすべての権限はroles/integrations.suspensionResolver（およびroles/integrations.integrationAdmin）に含まれます。また、再開にはインテグレーションの実行サービスアカウントに対するroles/iam.serviceAccountUserも必要です。解除または解決を行う前に、必ずユーザーに確認してください。Timerタスクは自動的に再開します。
• 認証プロファイル（authConfigs）：再利用可能なリージョン別の認証情報レコードです（projects/PROJECT_ID/locations/LOCATION/authConfigs/AUTH_CONFIG_ID）。インテグレーションバージョンのダウンロードには含まれません。

バージョンの状態、トリガーの種類、タスクのカテゴリ、変数、一時停止、認証プロファイルの詳細については、references/core-concepts.mdを参照してください。

IAM と実行サービスアカウントの要件

主な IAM ロールとサービスエージェント

• 開発者およびオペレーターのロール：roles/integrations.integrationAdmin（認証プロファイルの完全な CRUD と削除）、roles/integrations.integrationEditor（integrations.integrationVersions.create と integrations.integrationVersions.deploy を含む、作成／アップロード／編集／テスト／呼び出し／キャンセル／再実行／公開）、roles/integrations.integrationDeployer（integrations.integrationVersions.deploy による公開／公開解除。list／get／deploy の権限はありますが、create の権限はないため、既存のバージョンは公開できますが、アップロードはできません）、roles/integrations.integrationInvoker（呼び出し／キャンセル／再実行）、roles/integrations.integrationViewer（インテグレーションとログの表示）、roles/integrations.suspensionResolver（一時停止の一覧表示、解除、解決：integrations.suspensions.list、integrations.suspensions.lift、integrations.suspensions.resolve。suspensionResolver だけでは実行レコードを読み取れないため、taskExecutionDetails を調査するか :troubleshoot を実行するには roles/integrations.integrationViewer も付与してください。または、実行 ID とタスク ID が含まれる承認メールのリンクを使用してください）。
• サービスエージェント：
  • Application Integration サービスエージェント：service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com（roles/integrations.serviceAgent が付与されます）。
  • Integration Connectors サービスエージェント：[email protected]（roles/connectors.serviceAgent が付与されます）。

実行時サービスアカウントに関する必須ルール（2026 年 10 月 15 日から有効）

1. 明示的な ID が必要：2026 年 10 月 15 日以降に作成されたインテグレーション（および後日、既存のインテグレーション）では、実行ごとに明示的な ID が必要です。ID には、トリガーを実行する呼び出し元、またはインテグレーションのバージョンごとに IntegrationVersion.runAsServiceAccount で設定するユーザー管理の実行時サービスアカウントを指定します（clients:provision によるリージョンのプロビジョニングでは runAsServiceAccount は適用されません）。
2. API トリガーまたは Private トリガー以外のトリガーでは、実行時サービスアカウントが必要：2026 年 10 月 15 日以降に作成されたインテグレーションで、API トリガーまたは Private トリガー以外（スケジュール、Cloud Scheduler、Cloud Pub/Sub、Eventarc、Salesforce、Connector Event など）のトリガーを使用する場合、runAsServiceAccount が設定されていなければ、テストも公開もできません。Private トリガーは API トリガーと同様に対象外のため、トリガーが Private のみのサブインテグレーションは、runAsServiceAccount を設定せずに公開できます。
3. リージョンのガバナンス：リージョンでガバナンスが有効になっている場合は、API トリガーのインテグレーションを含む、すべての新しいインテグレーションとバージョンで実行時サービスアカウントが必須です。
4. サービスアカウントユーザー（roles/iam.serviceAccountUser）：バージョンに runAsServiceAccount が設定されている場合、そのバージョンを公開またはテストするユーザー（またはプリンシパル）は、そのサービスアカウント（またはそのサービスアカウントを所有するプロジェクト）に対する roles/iam.serviceAccountUser を持っている必要があります。実行時には、呼び出し元またはトリガーのサービスアカウント、および一時停止を解決または解除するユーザーも、そのサービスアカウントに対する roles/iam.serviceAccountUser を持っている必要があります。
5. ベストプラクティス：インテグレーションごとに、専用で権限を最小限に絞ったユーザー管理サービスアカウントを 1 つ作成してください。runAsServiceAccount が設定されていて、タスクレベルの認証プロファイルが設定されていない場合、Connector、Call REST Endpoint、Cloud Function タスク用のトークンが発行されます（タスクに OAuth 2.0 または OIDC の認証プロファイルが設定されている場合は、runAsServiceAccount より優先されます）。

IAM ロールの完全な表、サービスエージェントの権限、認証情報の優先順位ルール、gcloud IAM コマンドについては、references/iam-and-service-accounts.md を参照してください。

設計時に考慮すべき主なクォータと上限

上限	値	設計への影響
SYNC の実行タイムアウト	2 分	2 分を超えるワークフローには、非同期トリガーまたは integrations.schedule を使用してください。タイムアウトした同期実行は CANCELLED になります。
ASYNC の実行タイムアウト	10 分	1 回の非同期実行が 10 分を超える場合は、重い処理をサブインテグレーションまたは外部ジョブに分割してください。
実行の最大存続期間	31 日	Approval または Suspend タスクで一時停止している時間も含まれます（最大 44,640 分）。
インテグレーションのデータ総量	30 MB	入力／出力変数と、プライベートトリガーのサブインテグレーションで共有されます。10 MB を超えると、ローカルロギングが無効になり、再試行が機能しなくなり、モニタリングで実行がスキップされます。
API トリガーの入力サイズ	8 MB	すべての入力変数の累積サイズです。これを超えるペイロードは、ワークフローの開始前に失敗します。
コネクタのデータ量とタイムアウト	入出力 8 MB、タイムアウト 3 分	Application Integration のクォータでは、コネクションとの間で送受信されるデータの累積量は 8 MB、コネクタの応答は 20 MB に制限されます（Integration Connectors のクォータでは、Connectors タスクのペイロードは 10 MB に制限されます）。カスタムクエリは 180 秒、50,000 行に制限されます。
同時実行数	1 プロジェクト・1 リージョンあたり 50、1 インテグレーションあたり 10（デフォルト）	どちらの同時実行数の上限も調整できます。単一のインテグレーションに集中して実行が発生した場合、50 ではなく 1 インテグレーションあたり 10 の上限に達します。実行リクエストのレートクォータは、プロジェクトの Cloud Quotas ページに表示され、そこで調整できます。
インテグレーション／タスク／バージョン数	1,000／100／100	1 プロジェクトあたり最大 1,000 個のインテグレーション、1 インテグレーションあたり最大 100 個のタスクと 100 個のバージョンを作成できます。
公開の反映	最大 10 分	結果整合性のため、新しいバージョンの公開後も、古いバージョンが最大 10 分間実行され続けることがあります。

タスク固有のすべてのペイロード上限、ループ反復回数の上限、Integration Connectors のノード上限、料金の詳細については、references/limits.md を参照してください。

関連スキル

• application-integration-basics（このスキル）：概念、API の有効化、リージョンのプロビジョニング、IAM ロールと実行用サービスアカウント、インターフェースの選択肢（REST、Python クライアント、Terraform、ADK）、クォータと上限。
• application-integration-authoring：REST API を使ったインテグレーションの構築、アップロード、バージョン管理、構成変数の設定、公開、実行、テスト、トリガー ID、タスク固有の注意点、ダウンロード／アップロードを使ったプロジェクト間の CI/CD プロモーション。
• application-integration-troubleshooting：失敗または停止した実行の診断、実行とタスクの状態および ErrorInfo の確認、実行の一覧表示とフィルタリング、Cloud Logging と Cloud Monitoring、一時停止と承認、Integration Connectors のコネクションの健全性、IAM／実行用／クォータのエラー。

リファレンスファイル

• references/core-concepts.md：トリガー、実行モード、タスクの種類、バージョンのライフサイクル、編集ロック、変数、一時停止、認証プロファイル。
• references/iam-and-service-accounts.md：Application Integration と Integration Connectors の事前定義済み IAM ロール、サービスエージェント、実行用サービスアカウントのルール、IAM コマンド。
• references/provisioning-and-terraform.md：REST clients:provision によるリージョンごとのプロビジョニング、Cloud コンソールでのクイック／詳細セットアップ、CMEK に関する注意点、Terraform の google_integrations_*／google_integration_connectors_* リソース。
• references/api-access.md：エンドポイント、認証、curl の例、Python google-api-python-client のディスカバリーパターン、ADK ApplicationIntegrationToolset、MCP コネクタに関する補足。
• references/limits.md：タイムアウト、ペイロード上限、同時実行クォータ、ループ／タスクの上限、Integration Connectors の上限、料金プラン。