このページは Cloud Translation API によって翻訳されました。

選択入力

SelectionInput ウィジェットには、チェックボックス、ラジオボタン、スイッチ、プルダウンメニューなど、選択可能なアイテムのセットが用意されています。このウィジェットを使用して、定義済みで標準化されたデータをユーザーから収集できます。ユーザーから未定義のデータを収集するには、代わりに TextInput ウィジェットを使用します。

SelectionInput ウィジェットは、ユーザーが均一なデータを入力するのに役立つ提案と、変更時のアクションをサポートしています。これは、選択入力フィールドで変更（ユーザーによるアイテムの選択や選択解除など）が発生したときに実行される Actions です。

チャットアプリは、選択されたアイテムの値を受信して処理できます。フォーム入力の操作について詳しくは、フォームデータを受信するをご覧ください。

例

このセクションでは、SelectionInput ウィジェットを使用するカードの例を示します。この例では、さまざまなタイプのセクション入力を使用します。

チェックボックス
ラジオボタン
スイッチ
プルダウンメニュー
複数選択メニュー

例 1: チェックボックス

以下では、チェックボックスを使用する SelectionInput ウィジェットを使用して、連絡先がプロフェッショナルか個人用かを指定するようユーザーに求めるダイアログが表示されます。

例 2: ラジオボタン

以下に、ラジオボタンを使用する SelectionInput ウィジェットを使用して、連絡先が仕事用か個人用かを指定するようユーザーに求めるダイアログが表示されます。

例 3: スイッチ

次のダイアログは、スイッチを使用する SelectionInput ウィジェットを使用して、連絡先が仕事用か個人用かを指定するようユーザーに求めるダイアログです。

次のダイアログは、プルダウンメニューを使用する SelectionInput ウィジェットを使用して、連絡先がプロフェッショナルか個人用かを指定するようユーザーに求めるダイアログです。

以下は、複数選択メニューから連絡先を選択するようにユーザーに求めるダイアログを表示します。

複数選択メニュー用の追加のデータソース

次のセクションでは、複数選択メニューを使用して、Google Workspace アプリや外部データソースなどの動的ソースからデータを収集する方法について説明します。

Google Workspace のデータソース

複数選択メニューの項目は、Google Workspace の次のデータソースから入力できます。

Google Workspace ユーザー: 同じ Google Workspace 組織内のユーザーにのみ入力できます。
Chat スペース: 複数選択メニューで項目を入力するユーザーは、自身が Google Workspace 組織に属しているスペースのみを表示および選択できます。

Google Workspace データソースを使用するには、platformDataSource フィールドを指定します。他の選択入力タイプとは異なり、SectionItem オブジェクトは Google Workspace から動的に取得されるため、省略します。

次のコードは、Google Workspace ユーザーの複数選択メニューを示しています。ユーザーに情報を入力するには、選択入力で commonDataSource を USER に設定します。

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

次のコードは、Chat スペースの複数選択メニューを示しています。スペースに入力するために、選択入力で hostAppDataSource フィールドを指定します。また、複数選択メニューでは、defaultToCurrentSpace が true に設定され、現在のスペースがメニューのデフォルト選択になります。

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Google Workspace の外部にあるデータソース

複数選択メニューを使用して、サードパーティまたは外部のデータソースからアイテムを入力することもできます。たとえば、複数選択メニューを使用すると、ユーザーが顧客管理（CRM）システムの見込み顧客のリストから見込み顧客を選択しやすくなります。

外部データソースを使用するには、externalDataSource フィールドを使用して、データソースからアイテムを返す関数を指定します。

外部データソースへのリクエストを減らすために、ユーザーがメニューに入力する前に複数選択メニューに表示されるおすすめのアイテムを含めることができます。たとえば、ユーザーの最近検索した連絡先を入力できます。外部データソースから候補のアイテムを入力するには、SelectionItem オブジェクトを指定します。

次のコードは、ユーザーの外部連絡先セットからのアイテムの選択メニューを示しています。メニューには、デフォルトで 1 件の連絡先が表示され、getContacts 関数を実行して外部データソースからアイテムを取得して入力できます。

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 2,
    "externalDataSource": {
      "function": "getContacts"
    },
    "items": [
      {
        "text": "Contact 3",
        "value": "contact-3",
        "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
        "bottomText": "Contact three description",
        "selected": false
      }
    ]
  }
}

外部データソースの場合は、ユーザーが複数選択メニューで入力を開始したアイテムをオートコンプリートすることもできます。たとえば、米国の都市が入力されるメニューにユーザーが Atl と入力し始めた場合、ユーザーが入力を完了する前に Chat アプリは Atlanta を自動候補として提示できます。オートコンプリートには最大 100 個のアイテムを指定できます。

アイテムをオートコンプリートするには、外部データソースに対してクエリを実行し、ユーザーが複数選択メニューに入力するたびにアイテムを返す関数を作成します。この関数は次のことを行う必要があります。

メニューのユーザー操作を表すイベントオブジェクトを渡します。
インタラクションイベントの invokedFunction 値が、externalDataSource フィールドの関数と一致することを確認します。
関数が一致すると、外部データソースから推奨アイテムを返します。ユーザーの入力内容に基づいてアイテムを提案するには、autocomplete_widget_query キーの値を取得します。この値は、ユーザーがメニューに入力した内容を表します。

次のコードは、外部データリソースのアイテムをオートコンプリートします。前述の例では、Chat アプリは関数 getContacts がトリガーされたタイミングに基づいてアイテムを提案します。

Apps Script

apps-script/selection-input/on-widget-update.gs

GitHub で表示

/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

Node.js

node/selection-input/on-widget-update.js

GitHub で表示

/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

JSON 表現とフィールド

JSON 表現

JSON 表現
{ "name": string, "label": string, "type": enum (`SelectionType`), "items": [ { object (`SelectionItem`) } ], "onChangeAction": { object (`Action`) }, "multiSelectMaxSelectedItems": integer, "multiSelectMinQueryLength": integer, // Union field `multi_select_data_source` can be only one of the following: "externalDataSource": { object (`Action`) }, "platformDataSource": { object (`PlatformDataSource`) } // End of list of possible types for union field `multi_select_data_source`. }

{
  "name": string,
  "label": string,
  "type": enum (SelectionType),
  "items": [
    {
      object (SelectionItem)
    }
  ],
  "onChangeAction": {
    object (Action)
  },
  "multiSelectMaxSelectedItems": integer,
  "multiSelectMinQueryLength": integer,

  // Union field multi_select_data_source can be only one of the following:
  "externalDataSource": {
    object (Action)
  },
  "platformDataSource": {
    object (PlatformDataSource)
  }
  // End of list of possible types for union field multi_select_data_source.
}

フィールド
`name`	`string` フォーム入力イベントでの選択入力を識別する名前。フォーム入力の操作について詳しくは、フォームデータを受信するをご覧ください。
`label`	`string` ユーザーインターフェースの選択入力フィールドの上に表示されるテキスト。ユーザーがアプリに必要な情報を入力するのに役立つテキストを指定します。たとえば、ユーザーがプルダウンメニューから作業チケットの緊急度を選択する場合、ラベルは「緊急」や「緊急性を選択」などになります。
`type`	`enum (SelectionType)` `SelectionInput` ウィジェットでユーザーに表示されるアイテムのタイプ。選択タイプでは、さまざまな操作がサポートされています。たとえば、ユーザーは 1 つ以上のチェックボックスは選択でき、プルダウンメニューから選択できる値は 1 つのみです。
`items[]`	`object (SelectionItem)` 選択可能な項目の配列。たとえば、ラジオボタンやチェックボックスの配列です。最大 100 個のアイテムをサポートします。
`onChangeAction`	`object (Action)` 指定すると、選択が変更されたときにフォームが送信されます。指定しない場合は、フォームを送信する別のボタンを指定する必要があります。フォーム入力の操作について詳しくは、フォームデータを受信するをご覧ください。
`multiSelectMaxSelectedItems`	`integer` 複数選択メニューの場合、ユーザーが選択できる項目の最大数。最小値は 1 アイテムです。指定しない場合のデフォルトは 3 アイテムです。
`multiSelectMinQueryLength`	`integer` 複数選択メニューの場合、Chat アプリがクエリする前にユーザーが入力したテキスト文字数によってオートコンプリートされ、メニューに候補が表示されます。指定しない場合のデフォルトは、静的データソースの場合は 0 文字、外部データソースの場合はデフォルトで 3 文字です。
共用体フィールド `multi_select_data_source`。Chat アプリのみ。複数選択メニューの場合、選択項目に入力されるデータソース。 `multi_select_data_source` は次のいずれかになります。
`externalDataSource`	`object (Action)` リレーショナルデータベースなどの外部データソース。
`platformDataSource`	`object (PlatformDataSource)` Google Workspace のデータソース。

SelectionType

列挙型
`CHECK_BOX`	チェックボックスのセット。ユーザーは 1 つ以上のチェックボックスを選択できます。
`RADIO_BUTTON`	ラジオボタンのセット。ユーザーはラジオボタンを 1 つ選択できます。
`SWITCH`	スイッチのセット。ユーザーは 1 つまたは複数のスイッチをオンにできます。
`DROPDOWN`	プルダウンメニュー。メニューから 1 つのアイテムを選択できます。
`MULTI_SELECT`	Chat アプリでサポートされますが、Google Workspace アドオンではサポートされません。静的データまたは動的データ用の複数選択メニュー。ユーザーがメニューバーから 1 つ以上のアイテムを選択します。ユーザーは値を入力して動的データを入力することもできます。たとえば、ユーザーが Google Chat スペースの名前を入力し始めると、ウィジェットが自動的にスペースの候補を表示します。複数選択メニューの項目にデータを入力するには、次のいずれかのタイプのデータソースを使用します。静的データ: アイテムはウィジェットで `SelectionItem` オブジェクトとして指定されます。最大 100 アイテム。 Google Workspace データ: アイテムは、Google Workspace ユーザーや Google Chat スペースなどの Google Workspace のデータを使用して入力されます。外部データ: アイテムは Google Workspace の外部の外部データソースから入力されます。複数選択メニューの実装方法の例については、 `SelectionInput` ウィジェットのページをご覧ください。

SelectionItem

JSON 表現
{ "text": string, "value": string, "selected": boolean, "startIconUri": string, "bottomText": string }

フィールド
`text`	`string` ユーザーにアイテムを特定または説明するテキスト。
`value`	`string` このアイテムに関連付けられている値。クライアントはこれをフォーム入力値として使用する必要があります。フォーム入力の操作について詳しくは、フォームデータを受信するをご覧ください。
`selected`	`boolean` デフォルトでアイテムが選択されるかどうかを指定します。選択入力で受け入れられる値が 1 つのみの場合（ラジオボタンやプルダウンメニューなど）、このフィールドを 1 つのアイテムにのみ設定します。
`startIconUri`	`string` 複数選択メニューの場合、アイテムの `text` フィールドの横に表示されるアイコンの URL。PNG ファイルと JPEG ファイルがサポートされます。`HTTPS` の URL を指定する必要があります。例: `https://developers.google.com/chat/images/quickstart-app-avatar.png`
`bottomText`	`string` 複数選択メニューの場合、アイテムの `text` フィールドの下に表示されるテキストの説明またはラベル。

行動

フォーム送信時の動作を記述するアクション。たとえば、Apps Script スクリプトを呼び出してフォームを処理できます。アクションがトリガーされると、フォームの値がサーバーに送信されます。

JSON 表現
{ "function": string, "parameters": [ { object (`ActionParameter`) } ], "loadIndicator": enum (`LoadIndicator`), "persistValues": boolean, "interaction": enum (`Interaction`) }

フィールド
`function`	`string` 要素を含む要素がクリックされたとき、または相互にアクティブになったときに呼び出すカスタム関数。使用例については、インタラクティブなカードを作成するをご覧ください。
`parameters[]`	`object (ActionParameter)` アクションパラメータのリスト。
`loadIndicator`	`enum (LoadIndicator)` アクションの呼び出し中にアクションが表示する読み込みインジケーターを指定します。
`persistValues`	`boolean` フォームの値がアクション後に保持されるかどうかを示します。デフォルト値は `false` です。 `true` の場合、アクションがトリガーされた後もフォームの値が残ります。アクションの処理中にユーザーが変更できるようにするには、`LoadIndicator` を `NONE` に設定します。Chat アプリのカードメッセージの場合は、アクションの `ResponseType` も `UPDATE_MESSAGE` に設定し、アクションを含むカードと同じ `cardId` を使用する必要があります。 `false` の場合、アクションがトリガーされるとフォームの値がクリアされます。アクションの処理中はユーザーが変更できないようにするには、`LoadIndicator` を `SPINNER` に設定します。
`interaction`	`enum (Interaction)` （省略可）ダイアログを開くときに必要です。ユーザー操作（カードメッセージのボタンをクリックするなど）に応じて実行する処理。指定しない場合、アプリは通常どおり `action` を実行して（リンクのオープンや関数の実行など）、応答します。 `interaction` を指定することで、アプリは特別なインタラクティブな方法で応答できます。たとえば、`interaction` を `OPEN_DIALOG` に設定すると、アプリでダイアログを開くことができます。指定すると、読み込みインジケーターは表示されません。 Chat アプリでサポートされますが、Google Workspace アドオンではサポートされません。アドオンに指定すると、カード全体が削除され、クライアントには何も表示されません。

ActionParameter

アクションメソッドが呼び出されたときに提供する文字列パラメータのリスト。たとえば、今すぐスヌーズ、1 日スヌーズ、来週の 3 つのスヌーズボタンを考えてみましょう。action method = snooze() を使用して、スヌーズの種類とスヌーズ時間を文字列パラメータのリストに渡すこともできます。

詳細については、CommonEventObject をご覧ください。

JSON 表現
{ "key": string, "value": string }

フィールド

フィールド
`key`	`string` アクションスクリプトのパラメータの名前。
`value`	`string` パラメータの値。

key

string

アクションスクリプトのパラメータの名前。

value

string

パラメータの値。

LoadIndicator

アクションの呼び出し中にアクションが表示する読み込みインジケーターを指定します。

列挙型
`SPINNER`	コンテンツが読み込み中であることを示すスピナーを表示します。
`NONE`	何も表示されません。

インタラクション

（省略可）ダイアログを開くときに必要です。

ユーザー操作（カードメッセージのボタンをクリックするなど）に応じて実行する処理。

指定しない場合、アプリは通常どおり action を実行して（リンクのオープンや関数の実行など）、応答します。

interaction を指定することで、アプリは特別なインタラクティブな方法で応答できます。たとえば、interaction を OPEN_DIALOG に設定すると、アプリでダイアログを開くことができます。

指定すると、読み込みインジケーターは表示されません。

Chat アプリでサポートされますが、Google Workspace アドオンではサポートされません。アドオンに指定すると、カード全体が削除され、クライアントには何も表示されません。

列挙型

INTERACTION_UNSPECIFIED デフォルト値。action は通常どおり実行されます。

列挙型
`INTERACTION_UNSPECIFIED`	デフォルト値。`action` は通常どおり実行されます。
`OPEN_DIALOG`	ダイアログを開きます。これは、Chat アプリがユーザーとやり取りする際に使用する、ウィンドウ形式のカードベースのインターフェースです。カードメッセージのボタンクリックに応答する Chat アプリでのみサポートされます。 Google Workspace アドオンではサポートされていません。アドオンに指定すると、カード全体が削除され、クライアントには何も表示されません。

OPEN_DIALOG

ダイアログを開きます。これは、Chat アプリがユーザーとやり取りする際に使用する、ウィンドウ形式のカードベースのインターフェースです。

カードメッセージのボタンクリックに応答する Chat アプリでのみサポートされます。

Google Workspace アドオンではサポートされていません。アドオンに指定すると、カード全体が削除され、クライアントには何も表示されません。

トラブルシューティング

Google Chat アプリまたはカードからエラーが返されると、Chat のインターフェースに「エラーが発生しました」または「リクエストを処理できませんでした」というメッセージが表示されます。Chat の UI にエラーメッセージが表示されなくても、Chat アプリやチャットカードで予期しない結果（カードメッセージが表示されないなど）が生成される場合があります。

Chat の UI にエラーメッセージが表示されない場合もありますが、Chat アプリのエラーロギングが有効になっている場合は、わかりやすいエラーメッセージとログデータを使用してエラーを修正できます。エラーの表示、デバッグ、修正方法については、Google Chat のエラーのトラブルシューティングと修正をご覧ください。

選択入力

例

例 1: チェックボックス

例 2: ラジオボタン

例 3: スイッチ

例 4: プルダウン メニュー

例 5: 複数選択メニュー

複数選択メニュー用の追加のデータソース

Google Workspace のデータソース

JSON

JSON

Google Workspace の外部にあるデータソース

JSON

Apps Script

Node.js

JSON 表現とフィールド

SelectionType

SelectionItem

行動

ActionParameter

LoadIndicator

インタラクション

トラブルシューティング

例 4: プルダウンメニュー