입력 변수로 데이터 수집

이 가이드에서는 입력 변수를 만드는 방법을 설명합니다.

단계를 실행하려면 특정 정보가 필요합니다. 예를 들어 이메일을 보내려면 이메일 주소가 필요합니다. 이 필수 정보를 제공하는 단계를 정의하려면 입력 변수를 정의하세요. 정의되면 사용자가 단계를 설정하는 동안 단계의 구성 카드에서 입력 변수를 설정하는 것이 일반적입니다.

입력 변수를 두 곳에 정의합니다. 하나는 부가기능의 매니페스트 파일이고 다른 하나는 사용자가 입력 변수의 값을 입력할 수 있는 구성 카드가 있는 코드입니다.

매니페스트 파일에서 입력 변수 정의

매니페스트 파일에서 inputs[] 배열을 사용하여 입력 변수를 지정합니다. inputs[] 배열의 각 항목에는 다음 속성이 있습니다.

  • 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 형식의 이메일 주소입니다.

다음 예에서는 계산기 단계의 입력 변수 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[] 배열에 정의된 각 입력 변수에 대해 하나의 입력 카드 위젯을 정의하는 구성 카드를 반환하는 onConfigFunction()라는 함수가 포함되어 있습니다.

구성 카드에 정의된 입력 위젯에는 다음 요구사항이 있습니다.

  • 각 입력 위젯의 name는 매니페스트 파일에서 해당 입력 변수의 id와 일치해야 합니다.
  • 입력 위젯의 카디널리티는 매니페스트 파일의 입력 변수 cardinality와 일치해야 합니다.
  • 입력 위젯의 데이터 유형은 매니페스트 파일의 입력 변수 dataType와 일치해야 합니다. 입력 변수의 dataType이 정수인 경우 문자열을 보유할 수 없습니다.

카드 인터페이스를 빌드하는 데 도움이 필요하면 다음 옵션 중 하나를 참고하세요.

  • 카드 빌더: 카드를 빌드하고 정의하는 데 사용할 수 있는 대화형 도구입니다.
  • 카드: 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 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
      }]
    }
  };
}

입력 변수 유효성 검사

사용자가 적절한 값을 입력했는지 확인하는 것이 좋습니다. 입력 변수 검증을 참고하세요.