입력 변수로 데이터 수집

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

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

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

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

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

  • id: 입력 변수의 고유 식별자입니다. 흐름에서 구성 카드 입력 요소를 이 입력 변수와 연결하도록 하려면 해당 카드 요소의 이름과 일치해야 합니다.
  • description: 최종 사용자에게 표시할 입력 변수에 대한 설명입니다.
  • cardinality: 허용되는 값의 수입니다. 가능한 값은 다음과 같습니다.
    • SINGLE: 값은 하나만 허용됩니다.
  • dataType: 허용되는 값의 유형입니다. dataType에는 데이터 유형을 정의하는 basicType 속성이 있습니다. 유효한 값으로 다음이 포함되어 있습니다.
    • STRING: 영숫자 문자열입니다.
    • INTEGER: 숫자
    • TIMESTAMP: 'Unix 에포크 이후 밀리초' 형식의 타임스탬프입니다. 예를 들어 2025년 11월 27일 16시 49분 2초(UTC)는 1764262142988로 표시됩니다.
    • 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": "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[] 배열에 정의된 각 입력 변수에 대해 하나의 입력 카드 위젯을 정의하는 구성 카드를 반환하는 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 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;
}

이전 단계의 출력 변수 사용

워크플로의 이전 단계에서 출력 변수를 허용하도록 입력 변수를 구성할 수 있습니다.

변수 선택 사용 설정

사용자가 이전 단계에서 변수를 선택할 수 있도록 하려면 TextInputSelectionInput 위젯에서 includeVariables 속성을 사용하세요.

TextInputSelectionInput 위젯에는 다음과 같은 Workspace Studio 전용 기능이 있습니다.

  • includeVariables: 사용자가 이전 단계에서 변수를 선택할 수 있도록 하는 불리언 속성입니다. 변수 선택기가 이후 단계에 표시되려면 시작 이벤트와 하나 이상의 해당 출력 변수가 모두 변수에 매핑되어야 합니다.
  • type: 추천을 자동 완성하는 열거형 값입니다. 지원되는 값은 다음과 같습니다.
    • USER: 사용자 연락처에 있는 사람에 대한 자동 완성 추천을 제공합니다.
    • SPACE: 사용자가 회원으로 속한 Google Chat 스페이스에 대한 자동 완성 제안을 제공합니다.

includeVariablestype이 모두 설정되면 입력 필드에서 두 환경을 결합합니다. 사용자는 드롭다운 메뉴에서 일치하는 type의 변수를 선택하고 자동 완성 추천을 확인할 수 있습니다.

  • Google Chat 스페이스의 자동 완성 추천입니다.
    그림 4: 사용자가 스페이스를 선택할 때 자동 완성 추천을 검토합니다.
  • 변수 메뉴를 사용하면 사용자가 이전 단계의 출력 변수를 선택할 수 있습니다.
    그림 5: 사용자가 ➕변수 드롭다운에서 이전 단계의 출력 변수를 선택합니다.

더보기 메뉴를 사용하여 출력 변수를 하나만 선택

사용자가 오버플로 메뉴를 사용하여 이전 단계에서 단일 출력 변수를 선택할 수 있도록 SelectionInput 위젯을 구성할 수 있습니다.

SelectionInputTypeOVERFLOW_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: 사용자가 텍스트와 출력 변수를 결합할 수 있습니다. 결과는 연결된 단일 문자열입니다.
  • PLAIN_TEXT: 입력을 제한합니다. 사용자는 텍스트를 입력하거나 단일 출력 변수를 선택할 수 있습니다. 변수를 선택하면 기존 텍스트가 대체됩니다. 이 모드를 사용하여 매니페스트에 정의된 특정 데이터 유형을 적용합니다.

다음 이미지는 두 개의 TextInput 위젯을 보여줍니다. 첫 번째는 RICH_TEXT로 구성되며 텍스트와 출력 변수가 있습니다. 두 번째는 PLAIN_TEXT로 구성되어 있으며 출력 변수만 허용합니다.

  • RICH_TEXT 및 PLAIN_TEXT로 구성된 텍스트 입력 위젯
    그림 3: RICH_TEXTPLAIN_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를 설정하여 WorkflowDataSourceTypeUSER 또는 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)
            ))
    );

예: 자동 완성 유형 결합

다음 예에서는 서버 측, 사용자, 스페이스 자동 완성 기능을 보여주는 세 개의 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();
}

입력 변수 유효성 검사

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