使用輸入變數收集資料

本指南說明如何建立輸入變數。

如要執行步驟，必須提供特定資訊。舉例來說，傳送電子郵件時需要電子郵件地址。如要提供這項必要資訊，請定義輸入變數。定義輸入變數後，使用者通常會在設定步驟時，透過步驟的設定卡片設定這些變數。

在兩個位置定義輸入變數：外掛程式的資訊清單檔案，以及程式碼中的設定資訊卡 (使用者可在其中輸入輸入變數的值)。

在資訊清單檔案中定義輸入變數

在資訊清單檔案中，使用 inputs[] 陣列指定輸入變數。inputs[] 陣列中的每個項目都具有下列屬性：

  • id：輸入變數的專屬 ID。如要讓流程將設定資訊卡輸入元素與這個輸入變數建立關聯，必須與對應資訊卡元素的名稱相符。
  • description：向使用者顯示的輸入變數說明。
  • cardinality：允許的值數量。可能的值包括：
    • SINGLE：只能輸入一個值。
  • dataType：可接受的值類型。dataType 具有 basicType 屬性，可定義資料類型。有效值包括：
    • STRING：英數字元字串。
    • INTEGER：數字。
    • TIMESTAMP：ISO 8601 格式的時間戳記。舉例來說，在 ISO 8601 中，2025 年 3 月 15 日會表示為 2025-03-15。
    • BOOLEAN：true 或 false。
    • EMAIL_ADDRESS：格式為 dana@example.com 的電子郵件地址。

以下範例會為計算機步驟定義三個輸入變數。前兩個輸入變數是整數，第三個則是算術運算。

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"
          }
        }
      ]
    }
  }
}

在程式碼中定義輸入變數

這個步驟的程式碼包含名為 onConfigFunction() 的函式，該函式會傳回設定資訊卡，為資訊清單檔案 inputs[] 陣列中定義的每個輸入變數定義一個輸入資訊卡小工具。

設定資訊卡中定義的輸入小工具須符合下列規定：

  • 每個輸入小工具的 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 card also includes a "Save"
 * button to save the step configuration for the workflow.
 *
 * The input fields are configured to let the user select outputs from previous
 * workflow steps as input values using the `hostAppDataSource` property.
 */
function onConfigFunction() {
  var card = {
    "sections": [
      {
        "header": "Step example: Calculate",
        "widgets": [
          {
            "textInput": {
              "name": "value1", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "First value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "selectionInput": {
              "name": "operation", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "Operation",
              "type": "DROPDOWN",
              "items": [
                {
                  "text": "+",
                  "value": "+",
                },
                {
                  "text": "-",
                  "value": "-",
                },
                {
                  "text": "x",
                  "value": "x",
                },
                {
                  "text": "/",
                  "value": "/",
                }
              ]
            }
          },
          {
            "textInput": {
              "name": "value2", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "Second value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

驗證輸入變數

最佳做法是驗證使用者輸入的值是否適當。請參閱「驗證輸入變數」。