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

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

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

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

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

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

  • id: 入力変数の固有識別子。フローで構成カードの入力要素をこの入力変数に関連付けるには、対応するカード要素の名前と一致する必要があります。
  • description: エンドユーザーに表示する入力変数の説明。
  • cardinality: 許可される値の数。指定できる値は次のとおりです。
    • SINGLE: 1 つの値のみが許可されます。
  • dataType: 受け入れられる値のタイプ。dataType には、データの型を定義するプロパティ basicType があります。有効な値は次のとおりです。
    • STRING: 英数字の文字列。
    • INTEGER: 数値。
    • TIMESTAMP: ISO 8601 形式のタイムスタンプ。たとえば、ISO 8601 では、2025 年 3 月 15 日は 2025-03-15 と表されます。
    • 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": "actionElement",
          "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 が整数の場合、文字列を保持できません。

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

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

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;
}

入力変数を検証する

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