Эта страница переведена с помощью Cloud Translation API.

Соберите данные с помощью входной переменной

В этом руководстве объясняется, как создать входную переменную.

Для выполнения шагов требуется определенная информация. Например, для отправки электронного письма необходим адрес электронной почты. Чтобы предоставить шагам эту необходимую информацию, определите входные переменные. После определения входные переменные обычно устанавливаются пользователем на карточке конфигурации шага во время его настройки.

Задать входную переменную можно в двух местах: в файле манифеста дополнения и в коде с помощью карточки конфигурации, где пользователи могут вводить значения для входных переменных.

Определите входную переменную в файле манифеста.

В файле манифеста укажите входные переменные с помощью массива inputs[] . Каждый элемент массива inputs[] имеет следующие свойства:

id : Уникальный идентификатор входной переменной. Чтобы связать элемент ввода конфигурационной карточки с этой входной переменной, он должен совпадать с именем соответствующего элемента карточки.
description : Описание входной переменной, отображаемое конечным пользователям.
cardinality : количество допустимых значений. Возможные значения:
- SINGLE : Допускается только одно значение.
dataType : Тип принимаемых значений. basicType dataType определяет тип данных. Допустимые значения:
- STRING : Буквенно-цифровая строка.
- INTEGER : Число.
- TIMESTAMP : Временная метка в формате "миллисекунды с начала эпохи Unix". Например, 27 ноября 2025 г., 16:49:02 UTC, представляется как 1764262142988 .
- BOOLEAN : либо истинно, либо ложно.
- 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": "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"
          }
        }
      ]
    }
  }
}

Определите входную переменную в коде.

В коде этого шага есть функция onConfigFunction() , которая возвращает карточку конфигурации, определяющую один виджет карточки ввода для каждой входной переменной, определенной в массиве inputs[] файла манифеста.

Элементы ввода, определенные в конфигурационной карточке, должны соответствовать следующим требованиям:

name каждого элемента ввода должно совпадать с id соответствующей входной переменной в файле манифеста.
Мощность поля ввода должна совпадать с cardinality входной переменной, указанной в файле манифеста.
Тип данных виджета ввода должен совпадать с dataType переменной ввода, указанным в файле манифеста. Если переменная ввода имеет dataType integer, она не может содержать строку.

Для получения помощи в создании интерфейсов для карт воспользуйтесь одним из следующих вариантов:

Конструктор карточек : интерактивный инструмент, который можно использовать для создания и определения карточек.
Карточка : в справочной документации по API дополнения Google Workspace.
Card Service : Сервис 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;
}

Используйте выходные переменные из предыдущих шагов.

Вы можете настроить входные переменные таким образом, чтобы они принимали выходные переменные из предыдущих шагов рабочего процесса.

Включить выбор переменных

Чтобы пользователи могли выбирать переменные из предыдущих шагов, используйте свойство includeVariables в виджетах TextInput и SelectionInput .

Виджеты TextInput и SelectionInput обладают следующими функциями, специфичными для Workspace Studio:

includeVariables : Логическое свойство, позволяющее пользователям выбирать переменные из предыдущих шагов. Для отображения средства выбора переменных на последующих шагах, как начальное событие, так и как минимум одна соответствующая выходная переменная должны соответствовать выбранной переменной.
type : Перечисляемое значение, которое автоматически дополняет подсказки. Поддерживаемые значения:
- USER : Предоставляет подсказки для автозаполнения для людей из контактов пользователя.
- SPACE : Предоставляет подсказки для автозаполнения в чатах Google, участником которых является пользователь.

Если заданы параметры includeVariables и type , поле ввода объединяет их возможности. Пользователи могут выбрать переменную соответствующего type из выпадающего меню и увидеть подсказки автозаполнения.

Рисунок 4: Пользователь просматривает подсказки автозаполнения при выборе пространства.
Рисунок 5: Пользователь выбирает выходную переменную предыдущего шага из выпадающего списка «Переменные».

Выберите только одну выходную переменную с помощью меню переполнения.

Вы можете настроить виджет SelectionInput таким образом, чтобы пользователи могли выбрать одну выходную переменную из предыдущего шага с помощью меню переполнения.

Если установить для SelectionInputType значение OVERFLOW_MENU , виджет будет выступать в качестве специального средства выбора переменных. В отличие от использования includeVariables с TextInput , которое преобразует значения переменных в строки, OVERFLOW_MENU сохраняет исходный тип данных выбранной переменной.

Apps Script

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

Позвольте пользователям объединять текст и выходные переменные.

Вы можете настроить виджеты TextInput для управления взаимодействием пользователей с текстом и выводом переменных с помощью setInputMode() .

RICH_TEXT : Позволяет пользователям объединять текст и выходные переменные. В результате получается единая объединенная строка.
PLAIN_TEXT : Ограничивает ввод. Пользователи могут либо вводить текст, либо выбирать одну выходную переменную. Выбор переменной заменяет любой существующий текст. Используйте этот режим для принудительного использования определенных типов данных, определенных в манифесте.

На следующем изображении показаны два виджета TextInput . Первый настроен как RICH_TEXT и содержит текст и переменную вывода. Второй настроен как 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) {
}

Настройка кнопок выбора переменных

Вы можете настроить кнопку выбора переменных, задав размер кнопки и подпись.

Размер пуговицы

Чтобы задать размер кнопки, используйте setVariableButtonSize() с одним из следующих перечислений VariableButtonSize :

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 пользователя:

Пользователи Google Workspace: заполнение данных о пользователях в рамках одной организации Google Workspace.
Пространства Google Chat: Заполните пространства Google Chat, в которых пользователь является участником.

Для настройки этого параметра задайте PlatformDataSource в виджете SelectionInput , указав 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)
            ))
    );

Пример: Объединение типов автозаполнения

В следующем примере показана функция onConfig , которая создает карточку с тремя виджетами SelectionInput , демонстрируя автозаполнение на стороне сервера, пользователя и пространства:

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

Используйте выходные переменные из предыдущих шагов.

Включить выбор переменных

Выберите только одну выходную переменную с помощью меню переполнения.

Apps Script

Позвольте пользователям объединять текст и выходные переменные.

JSON

Apps Script

Настройка кнопок выбора переменных

Размер пуговицы

Метка кнопки

Пример: Настройка средства выбора переменных

JSON

Apps Script

Настройте автозаполнение данных в Google Workspace.

Apps Script

Пример: Объединение типов автозаполнения

JSON

Apps Script

Проверьте входную переменную.

Связанные темы

Соберите данные с помощью входной переменной