インタラクティブな Google Chat アプリを Google Workspace アドオンに変換する

Google Chat API のインタラクション イベントを使用する Google Chat アプリをビルドして公開している場合は、Google Chat アプリのクイックスタートに基づくアプリなど、このページで、Google Chat を拡張する Google Workspace アドオンに変換する方法について説明します。

変換することで、Google Chat アプリは Google Workspace アドオン フレームワークを使用できるようになり、Google Chat 内および Google Workspace 全体で統合と機能の新たな可能性が開かれます。たとえば、Gmail、カレンダー、ドキュメントなどの他の Google Workspace ホスト アプリケーションとともに、Chat アプリを拡張する単一の Google Workspace アドオンを Google Workspace Marketplace で配布できます。

制限事項

変換を開始する前に、Google Chat を拡張する Google Workspace アドオンの制限事項 を確認して、Google Chat アプリを変換しても 重要な機能が失われないようにしてください。

ステップ 1: 既存の Google Chat アプリのコードをコピーする

変換プロセスではコードの変更が必要です。本番環境の Google Chat アプリに影響を与えないように、コードのコピーを作成して作業します。

Apps Script

  1. 既存の Google Chat アプリの Google Apps Script プロジェクトを開きます。
  2. 左側の [概要] をクリックします。
  3. 右側の [**コピーを作成**] をクリックします。
  4. 左側の [プロジェクトの設定] をクリックします。
  5. [Google Cloud プロジェクト] で、[プロジェクトを変更] をクリックします。
  6. 既存の Google Chat アプリ プロジェクトに関連付けられているプロジェクト番号を入力します。
  7. [プロジェクトを設定] をクリックします。

HTTP

既存のコードベースのフォークまたはコピーを作成し、本番環境の Google Chat アプリとは別の新しいサービスとしてデプロイします。

アプリが Google Cloud にデプロイされ、Google Cloud プロジェクトに関連付けられた機能（デフォルトの App Engine ID など）に依存している場合は、新しいコードを既存の Google Chat アプリ プロジェクトに関連付けられたサービスにデプロイする必要があります。

ステップ 2: コピーしたコードを変更する

Google Chat を拡張する Google Workspace アドオンでは、Chat API のインタラクション イベントで構築された Google Chat アプリとは異なるリクエストとレスポンスの構造が使用されます。リクエストとレスポンスに Google Chat API のEventではなく Google Workspace アドオンのEventObjectを使用するようにコードを更新する必要があります。コード変換ガイドを使用してコードを変更します。

ステップ 3: テストユーザーの Google Workspace アドオン構成を有効にする

Google Cloud コンソールを使用して、Google Chat アプリの Google Workspace アドオンの設定を構成します。

  1. Google Cloud コンソールで Google Chat API の構成ページに移動します。

    Google Chat API の構成ページに移動

  2. [インタラクティブ機能] で、[インタラクティブ機能を有効にする] をオンにします。

  3. [Google Workspace アドオンに変換] で、 [アドオンに変換] をクリックします。

  4. [アドオンの構成設定を有効にする] を有効にします。

  5. [可視性] セクションに、テストユーザーのメールアドレスを追加します。

  6. 必要に応じて、ステップ 2 でコピーして変更した Google Chat アプリのコードのデプロイ エンドポイント URL または Apps Script デプロイ ID で [接続設定] を更新します。

  7. [保存してテスト] をクリックします。

ステップ 4: 変換されたアプリをテストする

ステップ 3 で構成したテストユーザー アカウントを使用して、Google Workspace アドオンの機能を十分にテストします。すべての機能とインタラクションを確認します。

ステップ 5: すべてのユーザーの変換を完了する

変換された Google Workspace アドオンが正しく動作することを確認したら、すべてのユーザーが利用できるようにします。

  1. Google Cloud コンソールで Google Chat API の構成ページに移動します。

    Google Chat API の構成ページに移動

  2. [インタラクティブ機能] で、[アドオンに変換] をクリックします。サイドパネルが開きます。

  3. サイドパネルで [アドオンに変換] をクリックします。

  4. プロジェクト ID を入力して [変換] をクリックします。

これで、Google Chat アプリは Google Chat を拡張する Google Workspace アドオンになりました。

省略可: 使用されていない Google Cloud リソースをクリーンアップまたは解放する

Google Chat アプリを Google Workspace アドオンに変換した後、使用されなくなった Google Chat アプリで使用されているリソースに対して Google Cloud アカウントに課金されないように、必要に応じてリソースをオフにすることを検討してください。

コード変換ガイド

このセクションでは、Google Chat API のインタラクション Event 形式と Google Workspace アドオンの EventObject 形式のマッピングについて詳しく説明します。

リクエスト マッピング

次の表は、Google Chat API Event のフィールドが Google Workspace アドオン EventObjectの対応するフィールドにどのようにマッピングされるかを示しています。

Google Chat API interaction Event フィールド Google Workspace アドオンの EventObject フィールド メモ
action.actionMethodName なし カードのインタラクションの場合、メソッド名を commonEventObject.parameters のパラメータとして渡すことができます。最初のダイアログを開くをご覧ください。
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 イベントの種類に応じて、さまざまなペイロードで使用できます。
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 イベントの種類に応じて、さまざまなペイロードで使用できます。
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 イベントの種類に応じて、さまざまなペイロードで使用できます。
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 イベントの種類に応じて、さまざまなペイロードで使用できます。
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 イベントの種類に応じて、さまざまなペイロードで使用できます。
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 イベントの種類に応じて、さまざまなペイロードで使用できます。
token なし 検証は異なる方法で処理されます。HTTP アプリのリクエストの検証をご覧ください。
type なし イベントの種類はトリガーから推測できます。
user chat.user

ユースケース別のリクエスト マッピング

次の表は、Chat API のインタラクション イベントで構築された Google Chat アプリと、Google Chat を拡張する Google Workspace アドオンとの間で、一般的なユースケースのリクエスト ペイロードの違いを示しています。

ユースケース Chat API のインタラクション Event ペイロード Google Workspace アドオン EventObject ペイロード
スペースにアプリを追加した 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
スペースからアプリを削除する 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
ユーザーがアプリを @メンションする 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
ユーザーがアプリを @メンションしてスペースに追加する Google Chat からのリクエストを 1 つ処理する必要があります。
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 Google Chat からのリクエストを 2 つ処理する必要があります。

最初のリクエスト:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

2 番目のリクエスト:
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
スラッシュ コマンド 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
スラッシュ コマンドでスペースにアプリを追加する Google Chat からのリクエストを 1 つ処理する必要があります。
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 Google Chat からのリクエストを 2 つ処理する必要があります。

最初のリクエスト:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

2 番目のリクエスト:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
ユーザーがカードまたはダイアログのボタンをクリックする 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

ダイアログ イベントの場合、common.formInputs にウィジェットの値が含まれます。Google Apps Script の例:

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

ダイアログ イベントの場合、commonEventObject.formInputs にウィジェットの値が含まれます。Google Apps Script の例:

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
ユーザーがアプリのホームカードに情報を送信する 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
ユーザーがクイック コマンドを使用してアプリ コマンドを呼び出す 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
リンクのプレビュー 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
ユーザーがカード メッセージまたはダイアログのウィジェットを更新する 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

ユースケース別のレスポンス マッピング

Google Chat を拡張する Google Workspace アドオンは、Message オブジェクトではなくアクションを返します。次の表は、Google Chat API の Message レスポンス タイプを、Google Workspace アドオンのアクションの同等物にマッピングしています。

ユースケース Google Chat API Message レスポンス Google Workspace アドオンの Chat アクション レスポンス
呼び出されたスペースにメッセージを作成する 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse は省略可能です。詳細については、スラッシュ コマンドに応答するをご覧ください。

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

詳細については、メッセージを送信するをご覧ください。
メッセージを更新する 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

詳細については、メッセージを更新する（Chat）をご覧ください。

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

詳細については、メッセージを更新する（アドオン）をご覧ください。
リンクのプレビュー 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

詳細については、リンクをプレビューする（Chat）をご覧ください。

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

詳細については、リンクをプレビューする（アドオン）をご覧ください。
最初のダイアログを開く 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

詳細については、ダイアログを開く（Chat）をご覧ください。

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
プッシュするカードには、onClick アクションを含むウィジェットを含めることができます。HTTP Google Workspace アドオンの場合は、関数エンドポイントを呼び出すようにこれらのアクションを構成します。
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

詳細については、ダイアログを開く（アドオン）をご覧ください。
ダイアログを閉じる 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

詳細については、ダイアログを閉じる（Chat）をご覧ください。

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

詳細については、ダイアログを閉じる（アドオン）をご覧ください。
外部システムに接続する（構成をリクエスト） 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

詳細については、外部システムに接続するをご覧ください。

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

詳細については、Google Workspace アドオンをサードパーティ サービスに接続するをご覧ください。
インタラクティブ ウィジェットの項目を自動補完する 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

詳細については、複数選択メニューを追加するをご覧ください。

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

詳細については、Google Chat ユーザーから情報を収集して処理するをご覧ください。

変換前に作成されたメッセージのカードのインタラクションを処理する

HTTP Google Chat アプリを Google Workspace アドオンに変換する場合、変換前に作成されたメッセージのカードのインタラクションには特別な処理が必要です。 アドオンでは、カードの action.function に完全な HTTP URL が使用されますが、Google Chat API のインタラクション イベントで構築された Chat アプリでは関数名が使用されます。次の表に、これらの違いをまとめます。

Google Chat API のインタラクション イベントで構築された Google Chat アプリ Google Chat を拡張する Google Workspace アドオン
構成 Google Cloud コンソールで、すべてのイベントに対して単一のエンドポイントを構成します。カードのインタラクションを実装する場合、カードの action には実行する関数の名前のみが含まれます。カードクリック イベントに対して共通の HTTP エンドポイントが呼び出されます。

詳細については、ダイアログを開く（Chat）をご覧ください。



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 必要に応じて、Google Cloud コンソールでイベントごとのエンドポイントを構成できますが、カードクリック イベントは含まれません。カードのインタラクションを実装する場合、カードの action には呼び出す HTTP エンドポイントの完全な URL を含める必要があります。ボタンごとに一意の HTTP エンドポイントを設定することも、共通のエンドポイントを使用して action.parameters のパラメータとしてアクションを渡すこともできます。

詳細については、ダイアログを開く（アドオン）をご覧ください。



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

変換前に作成されたメッセージでカードのインタラクションが機能するようにするには、Google Chat API の構成ページでカードのインタラクション URL を構成します。

この URL は、アプリを変換する前に作成されたメッセージのインタラクションにのみ使用されます。ユーザーがこれらのメッセージのいずれかを操作すると、元の action.function 値が __action_method_name__ というパラメータとして渡されます。

例: カードのクリック

カードのインタラクション URL を https://.../card-interaction-handler として構成し、ユーザーが次のアクションを含む過去のメッセージのカードをクリックした場合:

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

構成したカードのインタラクション URL に、次の形式でイベントが配信されます。

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

例: 複数選択メニュー

ユーザーが外部データソースを含む複数選択メニューを操作した場合:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

構成したカードのインタラクション URL に、次の形式でイベントが配信されます。

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

HTTP トリガーで [すべてのトリガーに共通の HTTP エンドポイント URL を使用する] をオンにすると、共通の URL が [ボタンをクリックした] イベントにも使用されます。

Chat を拡張する HTTP Google Workspace アドオンのリクエストを確認する

HTTP ベースの Google Chat アプリの場合、Google からのリクエストであることを確認するロジックは、Google Workspace アドオンに変換するときに更新する必要があります。

リクエストの検証における主な違いは次のとおりです。

アプリの種類 対象ユーザー サービス アカウントのメール
Google Chat API のインタラクション イベントで構築された Google Chat アプリ プロジェクト番号 chat@system.gserviceaccount.com
Google Chat を拡張する Google Workspace アドオン HTTP エンドポイントのみ プロジェクトごとのサービス アカウントのメール

Google Workspace アドオンの一意のサービス アカウントのメールアドレスは、Google Cloud コンソールの Google Chat API の構成ページの [Google Workspace アドオンに変換] セクションにあります。

アップグレードした Google Workspace アドオンでリクエストを確認するには:

  1. Cloud Run functions を使用している場合は、アドオンごとのサービス アカウントに roles/cloudfunctions.invoker ロールを付与します。 IAM でアクセスを承認するをご覧ください。
  2. トークン検証コードを更新して、Google Workspace アドオンのサービス アカウントのメールアドレスを使用して Bearer トークンの署名を確認します。Google からのリクエストを検証するをご覧ください。