入力変数を使用してデータを収集する

このガイドでは、入力変数を作成する方法について説明します。

実行するには、手順に特定の情報が必要です。たとえば、メールを送信するにはメールアドレスが必要です。この必要な情報を提供するには、入力変数を定義します。定義された入力変数は、通常、ユーザーがステップを設定する際に、ステップの構成カードでユーザーによって設定されます。

入力変数は、アドオンのマニフェストファイルと、ユーザーが入力変数の値を入力できる構成カードを含むコードの 2 か所で定義します。

マニフェストファイルで入力変数を定義する

マニフェストファイルで、inputs[] 配列を使用して入力変数を指定します。inputs[] 配列の各項目には次のプロパティがあります。

id: 入力変数の固有識別子。フローで構成カード入力要素をこの入力変数に関連付けるには、対応するカード要素の名前と一致している必要があります。
description: エンドユーザーに表示する入力変数の説明。
cardinality: 許可される値の数。指定できる値は次のとおりです。
- SINGLE: 1 つの値のみが許可されます。
dataType: 受け入れられる値のタイプ。dataType には、データの型を定義するプロパティ basicType があります。有効な値は次のとおりです。
- STRING: 英数字の文字列。
- INTEGER: 数値。
- TIMESTAMP: 「Unix エポックからの経過時間（ミリ秒単位）」形式のタイムスタンプ。たとえば、2025 年 11 月 27 日 16:49:02 UTC は 1764262142988 と表されます。
- BOOLEAN: true または false。
- EMAIL_ADDRESS: dana@example.com 形式のメールアドレス。

次の例では、計算ステップの 3 つの入力変数を定義しています。最初の 2 つの入力変数は整数で、3 つ目は算術演算です。

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Calculator",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "calculatorDemo",
          "state": "ACTIVE",
          "name": "Calculate",
          "description": "Asks the user for two values and a math operation, then performs the math operation on the values and outputs the result.",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "value1",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "value2",
                "description": "value2",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "operation",
                "description": "operation",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "outputs": [
              {
                "id": "result",
                "description": "Calculated result",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              }
            ],
            "onConfigFunction": "onConfigCalculate",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

コードで入力変数を定義する

このステップのコードには、マニフェストファイルの inputs[] 配列で定義された各入力変数に対して 1 つの入力カードウィジェットを定義する構成カードを返す onConfigFunction() という関数が含まれています。

構成カードで定義された入力ウィジェットには、次の要件があります。

各入力ウィジェットの name は、マニフェストファイル内の対応する入力変数の id と一致している必要があります。
入力ウィジェットのカーディナリティは、マニフェストファイル内の入力変数の cardinality と一致している必要があります。
入力ウィジェットのデータ型は、マニフェストファイルの入力変数の dataType と一致する必要があります。入力変数の dataType が整数の場合、文字列を保持できません。

カードインターフェースの作成については、次のいずれかをご覧ください。

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

次の例では、マニフェストファイルで入力変数を定義するで定義されている入力ウィジェットごとに構成カードを返します。

Apps Script

/**
* Generates and displays a configuration card for the sample calculation step.
*
* This function creates a card with input fields for two values and a drop-down
* for selecting an arithmetic operation.
*
* The input fields are configured to let the user select outputs from previous
* workflow steps as input values using the `hostAppDataSource` property.
*/
function onConfigCalculate() {
  const firstInput = CardService.newTextInput()
    .setFieldName("value1") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setTitle("First Value")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );

  const secondInput = CardService.newTextInput()
    .setFieldName("value2") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setTitle("Second Value")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );

  const selectionInput = CardService.newSelectionInput()
    .setTitle("operation")
    .setFieldName("operation") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setType(CardService.SelectionInputType.DROPDOWN)
    .addItem("+", "+", false)
    .addItem("-", "-", true)
    .addItem("x", "x", false)
    .addItem("/", "/", false);

  const sections = CardService.newCardSection()
    .setHeader("Action_sample: Calculate")
    .setId("section_1")
    .addWidget(firstInput)
    .addWidget(selectionInput)
    .addWidget(secondInput)

  let card = CardService.newCardBuilder()
    .addSection(sections)
    .build();

  return card;
}

前のステップの出力変数を使用する

ワークフローの前のステップの出力変数を受け入れるように入力変数を構成できます。

変数の選択を有効にする

前の手順でユーザーが変数を選択できるようにするには、TextInput ウィジェットと SelectionInput ウィジェットの includeVariables プロパティを使用します。

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

includeVariables: ユーザーが前のステップから変数を選択できるようにするブール値プロパティ。後の手順で変数ピッカーを表示するには、開始イベントと少なくとも 1 つの対応する出力変数の両方を変数にマッピングする必要があります。
type: 候補を自動補完する列挙値。サポートされている値は次のとおりです。
- USER: ユーザーの連絡先に登録されている人物の予測入力候補を提供します。
- SPACE: ユーザーがメンバーになっている Google Chat スペースのオートコンプリート候補を提供します。

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

図 4: スペースを選択する際に、ユーザーがオートコンプリートの候補を確認する。
図 5: ユーザーが [➕変数] プルダウンから前のステップの出力変数を選択する。

オーバーフローメニューで出力変数を 1 つだけ選択する

SelectionInput ウィジェットを構成して、ユーザーがオーバーフローメニューを使用して前のステップの単一の出力変数を選択できるようにすることができます。

SelectionInputType を OVERFLOW_MENU に設定すると、ウィジェットは専用の変数ピッカーとして機能します。TextInput で includeVariables を使用すると、変数の値が文字列に変換されますが、OVERFLOW_MENU では、選択した変数の元のデータ型が保持されます。

Apps Script

const selectionInput = CardService.newSelectionInput()
  .setFieldName("variable_picker_1")
  .setTitle("Variable Picker")
  .setType(
    CardService.SelectionInputType.OVERFLOW_MENU
  );

ユーザーがテキストと出力変数を組み合わせられるようにする

setInputMode() を使用して、ユーザーがテキストと出力変数を操作する方法を制御するように TextInput ウィジェットを構成できます。

RICH_TEXT: ユーザーがテキストと出力変数を組み合わせることができます。結果は 1 つの連結された文字列になります。
PLAIN_TEXT: 入力を制限します。テキストを入力するか、単一の出力変数を選択できます。変数を選択すると、既存のテキストが置き換えられます。このモードを使用して、マニフェストで定義された特定のデータ型を適用します。

次の画像は、2 つの TextInput ウィジェットを示しています。1 つ目は RICH_TEXT として構成され、テキストと出力変数が含まれています。2 つ目は PLAIN_TEXT として構成され、出力変数のみが許可されます。

図 3: RICH_TEXT と PLAIN_TEXT として構成されたテキスト入力ウィジェット。

すべての TextInput ウィジェットの入力モードを明示的に設定することをおすすめします。

さまざまな入力モードで TextInput ウィジェットを構成するためのマニフェストファイルを次に示します。

JSON

{
  "timeZone": "America/Toronto",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Text and output variable demo",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "richTextDemo",
          "state": "ACTIVE",
          "name": "Rich Text Demo",
          "description": "Show the difference between rich text and plain text TextInput widgets",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "First user input",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              },
              {
                "id": "value2",
                "description": "Second user input",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfiguration",
            "onExecuteFunction": "onExecution"
          }
        }
      ]
    }
  }
}

さまざまな入力モードで TextInput ウィジェットを構成するコードは次のとおりです。

Apps Script

function onConfiguration() {
  const input1 = CardService.newTextInput()
    .setFieldName("value1")
    .setId("value1")
    .setTitle("Rich Text")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    )
    // Set input mode to RICH_TEXT to allow mixed text and variables.
    .setInputMode(CardService.TextInputMode.RICH_TEXT);

  const input2 = CardService.newTextInput()
    .setFieldName("value2")
    .setId("value2")
    .setTitle("Plain text")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    )
    // Set input mode to PLAIN_TEXT to enforce single variable selection.
    .setInputMode(CardService.TextInputMode.PLAIN_TEXT);

  const section = CardService.newCardSection()
    .addWidget(input1)
    .addWidget(input2);

  const card = CardService.newCardBuilder()
    .addSection(section)
    .build();

  return card;
}

function onExecution(e) {
}

変数ピッカーのボタンをカスタマイズする

ボタンのサイズとラベルを設定することで、変数ピッカーボタンをカスタマイズできます。

ボタンのサイズ

ボタンのサイズを設定するには、次の VariableButtonSize 列挙型のいずれかを使用して setVariableButtonSize() を使用します。

UNSPECIFIED: デフォルト。ボタンは、サイドパネルではコンパクトに、その他のコンテキストではフルサイズで表示されます。
COMPACT: ボタンにプラス記号（+）のみが表示されます。
FULL_SIZE: ボタンにテキストラベル全体が表示されます。

ボタンのラベル

ボタンのテキストを設定するには、setVariableButtonLabel() を使用します。

例: 変数ピッカーのカスタマイズ

次の例は、さまざまな変数選択ツールボタンのサイズとカスタムラベルを使用して TextInput ウィジェットを構成する方法を示しています。

図 1: ウェブでの変数選択ツールボタンのカスタマイズ。
図 2: アドオンのサイドパネルでの変数選択ボタンのカスタマイズ。

変数ピッカーボタンをカスタマイズするためのマニフェストファイルを次に示します。

JSON

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.locale"
  ],
  "addOns": {
    "common": {
      "name": "Variable button customization",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "variable_picker_customization",
          "state": "ACTIVE",
          "name": "Variable Picker demo",
          "description": "List all possible variable picker customization options",
          "workflowAction": {
            "onConfigFunction": "onUpdateCardConfigFunction",
            "onExecuteFunction": "onUpdateCardExecuteFunction"
          }
        }
      ]
    }
  }
}

変数ピッカーボタンをカスタマイズするコードは次のとおりです。

Apps Script

function onUpdateCardConfigFunction(event) {
  const textInput1 = CardService.newTextInput()
    .setFieldName("value1")
    .setTitle("Regular variable picker button")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
      )
    );

  const textInput2 = CardService.newTextInput()
    .setFieldName("value2")
    .setTitle("Size: Unspecified")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
      )
    );

  const textInput3 = CardService.newTextInput()
    .setFieldName("value3")
    .setTitle("Size: Full size")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonSize(CardService.VariableButtonSize.FULL_SIZE)
      )
    );

  const textInput4 = CardService.newTextInput()
    .setFieldName("value4")
    .setTitle("Size: Compact")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonSize(CardService.VariableButtonSize.COMPACT)
      )
    );

  const textInput5 = CardService.newTextInput()
    .setFieldName("value5")
    .setTitle("Custom button label")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonLabel("New button label!")
      )
    );

  var cardSection = CardService.newCardSection()
    .addWidget(textInput1)
    .addWidget(textInput2)
    .addWidget(textInput3)
    .addWidget(textInput4)
    .addWidget(textInput5)
    .setId("section_1");

  var card = CardService.newCardBuilder().addSection(cardSection).build();

  return card;
}

function onUpdateCardExecuteFunction(event) {
}

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 関数を示しています。この例では、サーバーサイド、ユーザー、スペースの自動補完を示しています。

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Autocomplete Demo",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "autocomplete_demo",
          "state": "ACTIVE",
          "name": "Autocomplete Demo",
          "description": "Provide autocompletion in input fields",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "A multi-select field with autocompletion",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigAutocomplete",
            "onExecuteFunction": "onExecuteAutocomplete"
          }
        }
      ]
    }
  }
}

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
  let autocompleteResponse = AddOnsResponseService.newUpdateWidget()
    .addSuggestion(
      query + " option 1",
      query + "_option1",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 1 bottom text"
    )
    .addSuggestion(
      query + " option 2",
      query + "_option2",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 2 bottom text"
    ).addSuggestion(
      query + " option 3",
      query + "_option3",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 3 bottom text"
    );

  const modifyAction = AddOnsResponseService.newAction()
    .addModifyCard(
      AddOnsResponseService.newModifyCard()
        .setUpdateWidget(autocompleteResponse)
    );

  return AddOnsResponseService.newRenderActionBuilder()
    .setAction(modifyAction)
    .build();
}

入力変数を検証する

ベストプラクティスとして、ユーザーが適切な値を入力したことを検証します。入力変数を検証するをご覧ください。

入力変数を使用してデータを収集する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

マニフェスト ファイルで入力変数を定義する

JSON

コードで入力変数を定義する

Apps Script

前のステップの出力変数を使用する

変数の選択を有効にする

オーバーフロー メニューで出力変数を 1 つだけ選択する

Apps Script

ユーザーがテキストと出力変数を組み合わせられるようにする

JSON

Apps Script

変数ピッカーのボタンをカスタマイズする

ボタンのサイズ

ボタンのラベル

例: 変数ピッカーのカスタマイズ

JSON

Apps Script

Google Workspace データの自動補完を構成する

Apps Script

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

JSON

Apps Script

入力変数を検証する

関連トピック

入力変数を使用してデータを収集する

マニフェストファイルで入力変数を定義する

オーバーフローメニューで出力変数を 1 つだけ選択する