ステップの構成カードを作成する

Gemini アルファ版プログラム: Flows は、Gemini アルファ版プログラムの一部としてご利用いただけます。

このガイドでは、Google Workspace フローのステップでユーザーがカスタマイズして入力を指定できる構成カードを作成する方法について説明します。

一般に、構成カードを作成するには、他の Google Workspace アドオンと同様にカード インターフェースを作成します。構成カード インターフェースの作成については、以下をご覧ください。

• カード作成ツール: カードの作成と定義に役立つインタラクティブなツール。
• Google Workspace アドオン API リファレンス ドキュメントの Card。
• カードサービス: スクリプトでカードを構成して作成できる Apps Script サービス。
• Google Workspace アドオンのデベロッパー向けドキュメントのカードベースのインターフェース。

一部のカード ウィジェットには、このガイドで説明する Workspace フロー固有の特別な機能があります。

設定カードを定義する

Apps Script マニフェストとコードの両方で構成カードを定義します。

次の例は、ユーザーに Google Chat スペースの選択を求める構成カードを作成する方法を示しています。

マニフェスト ファイルを編集する

マニフェスト ファイルで workflowElements を定義します。

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Sample add-on",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/gsuite_addons/v6/web-24dp/logo_gsuite_addons_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Chat space selector",
          "description": "Lets the user select a space from Google  Chat",
          "workflowAction": {
            "inputs": [
              {
                "id": "chooseSpace",
                "description": "Choose a Chat space",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigSpacePicker",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

コードを編集

アプリケーション コードでカードを返します。

Apps Script

/**
* Generates and displays a configuration card to choose a Chat space
  */
function onConfigSpacePicker() {
  var card = {
    "sections": [
      {
        "header": "Choose a Chat space",
        "widgets": [
          {
            "selectionInput": {
              "name": "value1",
              "label": "First value",
              "type": "MULTI_SELECT",
              "platformDataSource": {
                "hostAppDataSource": {
                  "workflowDataSource": {
                    "includeVariables": true,
                    "type": "SPACE"
                  }
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

入力ウィジェットの予測入力を設定する

SelectionInput ウィジェットのオートコンプリートを設定すると、ユーザーがオプションのリストから選択しやすくなります。たとえば、ユーザーが米国の都市を入力するメニューで Atl の入力を開始した場合、ユーザーが入力を完了する前に、要素が Atlanta を自動提案できます。最大 100 個のアイテムを自動補完できます。

予測入力の候補は、次のデータソースから取得できます。

• サーバーサイドの自動補完: 候補は、ユーザーが定義したサードパーティまたは外部のデータソースから入力されます。
• Google Workspace のデータ: Google Workspace のユーザーや Google Chat のスペースなど、Google Workspace のソースから候補が入力されます。

サーバーサイドの自動補完

SelectionInput ウィジェットを構成して、外部データソースから候補を自動補完できます。たとえば、顧客管理（CRM）システムの販売見込み顧客のリストからユーザーが選択できるようにします。

サーバーサイドのオートコンプリートを実装するには、次の操作を行う必要があります。

1. データソースを定義する: SelectionInput ウィジェットで、RemoteDataSource を指定する DataSourceConfig を追加します。この構成は、予測入力候補を取得する Apps Script 関数を指します。
2. オートコンプリート機能を実装する: この関数は、ユーザーが入力フィールドに入力したときにトリガーされます。関数は、ユーザーの入力に基づいて外部データソースをクエリし、候補のリストを返す必要があります。

次の例では、サーバーサイドの自動補完用に SelectionInput ウィジェットを構成する方法を示します。

Apps Script

// In your onConfig function:
var multiSelect1 =
  CardService.newSelectionInput()
    .setFieldName("value1")
    .setTitle("Server Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setRemoteDataSource(
          CardService.newAction().setFunctionName('getAutocompleteResults')
        )
    )
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setPlatformDataSource(
          CardService.newPlatformDataSource()
            .setHostAppDataSource(
              CardService.newHostAppDataSource()
                .setWorkflowDataSource(
                  CardService.newWorkflowDataSource()
                    .setIncludeVariables(true)
                ))
        )
    );

// ... add widget to card ...

予測入力リクエストを処理する

setFunctionName で指定された関数（getAutocompleteResults）は、ユーザーがフィールドに入力したときにイベント オブジェクトを受け取ります。この関数は、次の条件を満たす必要があります。

1. event.workflow.elementUiAutocomplete.invokedFunction を確認して、想定される関数名と一致していることを確認します。
2. event.workflow.elementUiAutocomplete.query からユーザーの入力を取得します。
3. クエリを使用して外部データソースにクエリを実行します。
4. 必要な形式で最大 100 件の候補を返します。

次の例は、ユーザーのクエリに基づいて候補を返す handleAutocompleteRequest() 関数を実装する方法を示しています。

Apps Script

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results based on the query
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

// In your onConfig function, handle the autocomplete event
function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // ... rest of your card building logic ...
}

Google Workspace データの自動補完

ユーザーの Google Workspace 環境内のデータから自動補完候補を入力することもできます。

• Google Workspace ユーザー: 同じ Google Workspace 組織内のユーザーを入力します。
• Google Chat スペース: ユーザーがメンバーになっている Google Chat スペースを入力します。

これを構成するには、SelectionInput ウィジェットで PlatformDataSource を設定し、WorkflowDataSourceType を USER または SPACE に指定します。

Apps Script

// User Autocomplete
var multiSelect2 =
  CardService.newSelectionInput()
    .setFieldName("value2")
    .setTitle("User Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.USER)
            ))
    );

// Chat Space Autocomplete
var multiSelect3 =
  CardService.newSelectionInput()
    .setFieldName("value3")
    .setTitle("Chat Space Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            ))
    );

例: 予測入力タイプを組み合わせる

次の例は、3 つの SelectionInput ウィジェットを含むカードを作成する onConfig 関数を示しています。この例では、サーバーサイド、ユーザー、スペースの自動補完を示しています。

Apps Script

function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // Server-side autocomplete widget
  var multiSelect1 =
    CardService.newSelectionInput()
      .setFieldName("value1")
      .setTitle("Server Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .addDataSourceConfig(
        CardService.newDataSourceConfig()
          .setRemoteDataSource(
            CardService.newAction().setFunctionName('getAutocompleteResults')
          )
      )
      .addDataSourceConfig(
        CardService.newDataSourceConfig()
          .setPlatformDataSource(
            CardService.newPlatformDataSource()
              .setHostAppDataSource(
                CardService.newHostAppDataSource()
                  .setWorkflowDataSource(
                    CardService.newWorkflowDataSource()
                      .setIncludeVariables(true)
                  ))
          )
      );

  // User autocomplete widget
  var multiSelect2 =
    CardService.newSelectionInput()
      .setFieldName("value2")
      .setTitle("User Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.USER)
              ))
      );

  // Space autocomplete widget
  var multiSelect3 =
    CardService.newSelectionInput()
      .setFieldName("value3")
      .setTitle("Chat Space Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.SPACE)
              ))
      );

  var sectionBuilder =
    CardService.newCardSection()
      .addWidget(multiSelect1)
      .addWidget(multiSelect2)
      .addWidget(multiSelect3);

  var card =
    CardService.newCardBuilder()
      .addSection(sectionBuilder)
      .build();
  return card;
}

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

Workspace Flows 固有の機能

一部のカード ウィジェットには、Workspace フロー固有の特別な機能があります。詳細については、こちらをご覧ください。

TextInput と SelectionInput

TextInput ウィジェットと SelectionInput ウィジェットには、Workspace フロー固有の次の機能があります。

• includeVariables: ユーザーが前のステップから変数を選択できるようにするブール値プロパティ。
• type: 候補を自動補完する列挙値。サポートされている値は次のとおりです。
  • USER: ユーザーの連絡先に登録されている人物の予測入力候補を提供します。
  • SPACE: ユーザーがメンバーになっている Google Chat スペースのオートコンプリート候補を提供します。

includeVariables と type の両方が設定されている場合、入力フィールドはそれらのエクスペリエンスを組み合わせます。ユーザーは、一致する type の変数を選択して、その予測入力候補を表示できます。

• 

  図 1: スペースを選択する際に、ユーザーが予測入力の候補を確認している様子。

• 

  図 2: ユーザーが [➕変数] プルダウンから前のステップの出力変数を選択する。

カードに関する考慮事項と制限事項

• フローを拡張するアドオンでは、popCard()、pushCard()、updateCard() などのカード ナビゲーションはサポートされていません。

• SelectionInput が変数ピッカーで使用されている場合、ウィジェットは "type": "MULTI_SELECT" のみをサポートします。構成カードの他の場所では、SelectionInput は SelectionType のすべての値をサポートしています。

関連トピック

• ステップをビルドする
• 入力変数
• 入力変数を検証する
• 出力変数
• アクティビティとエラーをログに記録する
• フローのイベント オブジェクト