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

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

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

制限事項

変換を開始する前に、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. [アドオンの構成設定を有効にする] を有効にします。

  4. [公開設定] セクションで、テストユーザーのメールアドレスを追加します。

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

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

ステップ 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 のインタラクション 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 アドオンに変換する場合、変換前に作成されたメッセージのカード操作には特別な処理が必要です。Google Workspace アドオンはカードの action.function に完全な HTTP URL を使用しますが、Google Chat API インタラクション イベントで構築された Google 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 Workspace アドオンに変換する際に、リクエストが Google から送信されたことを確認するロジックを更新する必要があります。

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

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

Google Workspace アドオンの一意のサービス アカウント メールアドレスは、Google Cloud コンソールの Google Chat API 構成ページの [Convert to Google Workspace add-ons] セクションで確認できます。

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

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