Integration Connectors

解決する課題

外部の SaaS やデータベースと連携するたびに、認証方式・APIの作法・エラー処理・ページネーションを個別に実装するのは手間がかかり、保守の負担も大きくなります。Integration Connectors は、こうした接続先ごとの差異を共通インターフェースの背後に隠し、設定ベースで接続を用意できるようにします。

• 多数の SaaS やデータベースに対して、接続ごとに別々の認証・APIコードを書きたくない
• 接続先の エンティティ操作（作成・取得・更新・削除）やアクションを、共通の作法で呼び出したい
• 認証情報の管理や ページネーション・リトライといった定型処理をコネクタ側に任せたい
• 連携処理を Application Integration や Workflows から、追加実装なしに呼び出したい
• 接続の 稼働状況や利用量をマネージドに監視し、自前のインテグレーション基盤の運用負荷を下げたい

主要概念と用語

• コネクタ（Connector）: 特定の接続先（SaaS、データベース、メッセージングなど）への接続方法を定義した部品。種類ごとに用意されている
• 接続（Connection）: コネクタをもとに、認証情報やエンドポイントなどを設定して作った具体的な接続インスタンス。リージョン単位で作成する
• エンティティ（Entity）: 接続先が公開するデータのまとまり（テーブルやオブジェクトに相当）。一覧・取得・作成・更新・削除といった標準操作を共通の作法で行える
• アクション（Action）: エンティティ操作に収まらない、接続先固有の処理（特定のAPI呼び出しなど）を実行する単位
• コネクションノード: 接続のスループットを担う処理単位。負荷に応じてノード数の下限・上限を設定し、自動でスケールする
• エンドポイントアタッチメント / Private Service Connect: VPC内や非公開の接続先へ、プライベートにアクセスするための仕組み
• カスタムコネクタ: 提供済みコネクタにない接続先に対し、OpenAPI 仕様などをもとに独自のコネクタを定義する機能

仕様・制限・クォータ

• 接続は リージョン単位のリソースとして作成し、認証情報や接続先設定を持つ
• 各接続には コネクションノードが割り当てられ、ノード数の下限・上限を指定するとトラフィックに応じて自動スケールする。ノード数はスループットと課金の双方に影響する
• 1回の呼び出しで扱える ペイロードサイズや、エンティティ一覧の取得件数（ページネーション単位） には上限があり、大量データは分割して扱う
• 利用できる コネクタの種類・対応する操作（エンティティ操作かアクションか） は接続先ごとに異なるため、目的の操作が提供されているか事前に確認する
• プロジェクトあたりの 接続数や同時実行などにクォータがあり、一部は引き上げ申請が可能
• 具体的なノード単価、上限件数、対応コネクタの一覧などは変動するため、最新は公式ドキュメントで確認すること

内部の仕組み

Integration Connectors は、接続先ごとの差異（認証方式・API形式・ページネーション・エラーの返し方）を吸収する変換層として動作します。利用者は共通の「エンティティ操作」や「アクション」という抽象を呼び出すだけで、コネクタが実際の接続先APIへの変換を肩代わりします。

• 接続を作成すると、その背後で コネクションノードがプロビジョニングされ、リクエストを処理する。負荷に応じてノードが増減する
• 認証情報は接続設定として安全に保持され、各リクエスト時にコネクタが 適切な認証ヘッダーやトークンを付与する
• エンティティの一覧取得では、コネクタが接続先の ページネーションを内部で処理し、利用者は共通の作法で結果を受け取れる
• 非公開の接続先に対しては、Private Service Connect やエンドポイントアタッチメントを介してプライベート経路でアクセスする

設計パターン / ベストプラクティス

• オーケストレーションからの呼び出し: 接続を直接アプリに埋め込むのではなく、Application Integration や Workflows のステップとして呼び出し、連携の流れ全体をオーケストレーション側に集約する
• 冪等性の確保: 上位のリトライにより同じ操作が再実行されうるため、作成・更新を伴う呼び出しは冪等に設計する
• ノード数の適正化: 想定トラフィックに合わせてコネクションノードの下限・上限を設定し、過剰なプロビジョニングと処理詰まりの双方を避ける
• プライベート接続の活用: VPC内のデータベースなど非公開の接続先へは、公開経路ではなく Private Service Connect 経由で接続する
• 大量データの分割処理: 一括取得ではなくページネーションやフィルタを活用し、1回あたりのペイロードを抑える
• 未提供の接続先: 標準コネクタにない接続先は、カスタムコネクタや、汎用的なHTTP呼び出しと併用して補う

運用・監視

• 各接続の 稼働状態とコネクションノードの利用状況をコンソールで確認し、スケール設定が妥当かを点検する
• Cloud Monitoring で接続ごとのリクエスト数・エラー率・レイテンシなどのメトリクスを監視し、アラートを設定する
• Cloud Logging に呼び出しログが出力され、失敗時にどの接続のどの操作で何が起きたかを追跡できる
• 接続先の 認証情報の失効や権限変更は連携全体を止めうるため、期限のある資格情報はローテーションと監視を組み込む
• 接続先APIの レート制限に注意し、上位のリトライ設定と合わせて流量を制御する

コスト

Integration Connectors は、接続のスループットを担う コネクションノードの数と稼働時間が主な課金要素です。ノードはトラフィックに応じて自動スケールするため、設定した下限・上限が固定費と上限費の双方を左右します。

セキュリティ

• 接続の認証情報は安全に保持され、機密値は Secret Manager 等から参照する設計にして、定義への直書きを避ける
• 非公開の接続先へは Private Service Connect / エンドポイントアタッチメントでプライベートに接続し、公開インターネットへの露出を避ける
• 接続の作成・利用・管理には適切な IAM ロールを分離して付与し、最小権限を徹底する
• 保存データは暗号化され、要件に応じて CMEK（顧客管理鍵） での保護にも対応する
• 接続先ごとの認証情報は ローテーションし、失効や漏えい時の影響範囲を狭める

関連サービス・比較

Integration Connectors は単体ではなく、連携の流れを定義する Application Integration（iPaaS）から呼び出して使うのが基本です。Application Integration が「いつ・どの順で連携するか」を担い、Integration Connectors が「各接続先へどう接続するか」を担います。

ハンズオン / CLI例

# 利用可能なコネクタ(プロバイダ/コネクタの種類)を一覧する
gcloud integration-connectors providers list \
  --location=asia-northeast1

# 既存の接続を一覧する
gcloud integration-connectors connections list \
  --location=asia-northeast1

# 特定の接続の詳細(状態・ノード設定など)を確認する
gcloud integration-connectors connections describe MY_CONNECTION \
  --location=asia-northeast1

# 接続が公開しているエンティティの種類を一覧する
gcloud integration-connectors connections runtime-entity-types list \
  --connection=MY_CONNECTION \
  --location=asia-northeast1