Google Workspace アドオンのエンドポイント インターフェース


サービスの概要

ユーザーがサポートされているホスト アプリケーション(Gmail、Google カレンダー、Google ドライブ、Google Chat、Google ドキュメント、Google スプレッドシート、Google スライド、Workspace Studio)で操作をトリガーすると、ホストは設定されたアドオンのコールバック URL(/*)に HTTP POST イベント ペイロードを送信します。

アドオン エンドポイントは、EventObject リクエスト ペイロードを受信し、レスポンス: HandleEventResponse で説明されている 5 つの有効な JSON レスポンス タイプのいずれかを返す必要があります。


Webhook エンドポイントの契約

メソッド エンドポイント パス リクエストの本文 レスポンスの本文
POST /*(または構成済みのコールバック パス) EventObject 5 種類の回答のいずれか

リクエスト: EventObject

EventObject には、最上位のメタデータ、共通イベント フィールド、ホスト アプリケーションのコンテキストの詳細が含まれています。

共通コンテキストと認可コンテキスト

  • commonEventObject: ユーザーの言語 / 地域、ホステッド アプリケーションの列挙型(GMAIL、CALENDAR、DRIVE、CHAT、DOCS、SHEETS、SLIDES、WORKFLOW)、ユーザーのプラットフォーム、タイムゾーン、ウィジェット フォームの入力値(formInputs)、カスタム パラメータ。CommonEventObject をご覧ください。
  • authorizationEventObject: ユーザー OAuth アクセス トークン、ユーザー ID トークン、システム認可スコープ。詳しくは、AuthorizationEventObject をご覧ください。

ホステッド アプリケーションのイベント オブジェクト

コールバックを呼び出すアプリケーションに応じて、次のいずれかのホスト オブジェクトが存在します。

  • Gmail: メッセージ ID、スレッド ID、一時アクセス トークン、メッセージ受信者リスト(toRecipients、ccRecipients、bccRecipients)。GmailEventObject をご覧ください。
  • カレンダー: 予定 ID、定期的な予定の ID、カレンダー ID、主催者情報、参加者、会議データ、エントリ ポイント。CalendarEventObject をご覧ください。
  • ドライブ: 選択したファイルまたはフォルダ(selectedItems)と、現在のカーソル アイテムのメタデータ(activeCursorItem)。DriveEventObject をご覧ください。
  • Chat: イベントタイプ(ADDED_TO_SPACE、REMOVED_FROM_SPACE、MESSAGE、CARD_CLICKED)、スペースのメタデータ、ユーザーの詳細、ペイロード データ。ChatEventObject をご覧ください。
  • Workspace Studio: アクションの呼び出し、トリガー ライフサイクル イベント、要素の構成、リソースの取得、変数データマップ。WorkflowEventObject をご覧ください。
  • ドキュメント: ドキュメント ID、タイトル、ファイル スコープの権限フラグ、一致した URL パターン。DocsEventObject をご覧ください。
  • スプレッドシート: スプレッドシート ID、タイトル、ファイル スコープの権限フラグ、一致した URL パターン。SheetsEventObject をご覧ください。
  • スライド: プレゼンテーション ID、タイトル、ファイル スコープの権限フラグ、一致した URL パターン。SlidesEventObject をご覧ください。

レスポンス: HandleEventResponse

Webhook エンドポイントから返される HTTP レスポンスは、タグなしのルート JSON オブジェクトです。これは、次の 5 つのレスポンス タイプのいずれかのインスタンスである必要があります。

  1. RenderActions: 新しいカードのレンダリング、カードスタックの移動、UI アクション({"action": {"navigations": [...]}} や {"renderActions": ...} など)の実行を行います。
  2. SubmitFormResponse: カードのレンダリング手順とオプションの状態更新インジケーター({"renderActions": {...}, "stateChanged": true} など)を使用して、ユーザー フォームの送信アクションに応答します。
  3. GetAutocompletionResponse: ウィジェットの予測入力フィールド({"autoComplete": {"items": [...]}} など)に動的なテキスト候補を提供します。
  4. DataActions: コールバック({"hostAppDataAction": {...}} など)によってトリガーされたドキュメントのミューテーションまたは Chat スペースのアクションを実行します。
  5. AuthorizationError: 外部のサードパーティ認証情報を承認するようユーザーに求めるか、追加の Google OAuth スコープ({"basicAuthorizationPrompt": {"authorizationUrl": "..."}} など)をリクエストします。

スタンドアロンの OpenAPI 3.0 仕様と JSON スキーマ

コールバック エンドポイントのサーバースタブ、SDK クライアント ライブラリ、ペイロード検証スキーマを自動的に生成するには、次の仕様ファイルを参照してください。

  • OpenAPI 3.0.3 仕様: addon_callback_openapi.json
  • JSON スキーマ定義: endpoint_interface.schema.json
    • リクエスト スキーマ フラグメント: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject
    • レスポンス スキーマ フラグメント: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse