サービスの概要
ユーザーがサポートされているホスト アプリケーション(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 つのレスポンス タイプのいずれかのインスタンスである必要があります。
RenderActions: 新しいカードのレンダリング、カードスタックの移動、UI アクション({"action": {"navigations": [...]}}や{"renderActions": ...}など)の実行を行います。SubmitFormResponse: カードのレンダリング手順とオプションの状態更新インジケーター({"renderActions": {...}, "stateChanged": true}など)を使用して、ユーザー フォームの送信アクションに応答します。GetAutocompletionResponse: ウィジェットの予測入力フィールド({"autoComplete": {"items": [...]}}など)に動的なテキスト候補を提供します。DataActions: コールバック({"hostAppDataAction": {...}}など)によってトリガーされたドキュメントのミューテーションまたは Chat スペースのアクションを実行します。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
- リクエスト スキーマ フラグメント: