Создайте карту конфигурации для шага

В этом руководстве объясняется, как создать карточку конфигурации, которая позволяет пользователям настраивать параметры и вводить данные для определенного шага в Google Workspace Studio.

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

  • Конструктор карточек — интерактивный инструмент, который помогает создавать и определять карточки.
  • Карта в справочной документации по API дополнений Google Workspace.
  • Card Service — это сервис Apps Script, позволяющий скриптам настраивать и создавать карточки.
  • Интерфейсы на основе карточек в документации для разработчиков дополнений Google Workspace.

Некоторые виджеты-карточки обладают специальными функциями и возможностями, специфичными для Workspace Studio, которые подробно описаны в этом руководстве.

Определите конфигурационную карту

Определите конфигурационную карточку как в манифесте Apps Script, так и в коде.

В следующем примере показано, как создать карточку конфигурации, которая предлагает пользователям выбрать пространство для чата Google.

Отредактируйте файл манифеста.

В файле манифеста определите workflowElements .

JSON 

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Chat space selector",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/gsuite_addons/v6/web-24dp/logo_gsuite_addons_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Chat space selector",
          "description": "Lets the user select a space from Google  Chat",
          "workflowAction": {
            "inputs": [
              {
                "id": "chooseSpace",
                "description": "Choose a Chat space",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigSpacePicker",
            "onExecuteFunction": "onExecuteSpacePicker"
          }
        }
      ]
    }
  }
}

Отредактируйте код

В коде приложения верните карту.

Apps Script 

/**
 * Generates and displays a configuration card to choose a Chat space
 */
function onConfigSpacePicker() {

  const selectionInput = CardService.newSelectionInput()
    .setTitle("First Value")
    .setFieldName("chooseSpace")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            )
        )
    );

  const cardSection = CardService.newCardSection()
    .setHeader("Select Chat Space")
    .setId("section_1")
    .addWidget(selectionInput)

  var card = CardService.newCardBuilder()
    .addSection(cardSection)
    .build();

  return card;
}

function onExecuteSpacePicker(e) {
}

Настройте автозаполнение для виджетов ввода.

Для виджетов SelectionInput можно настроить автозаполнение, чтобы помочь пользователям выбирать из списка вариантов. Например, если пользователь начинает вводить Atl в меню, отображающем города США, ваш элемент может автоматически предложить Atlanta до того, как пользователь закончит ввод. Автозаполнение может поддерживать до 100 элементов.

Подсказки автозаполнения могут поступать из следующих источников данных:

  • Автозаполнение на стороне сервера: подсказки формируются из стороннего или внешнего источника данных, который вы определяете.
  • Данные Google Workspace: Предложения формируются на основе данных из источников Google Workspace, таких как пользователи Google Workspace или пространства Google Chat.

Автозаполнение на стороне сервера

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

Для реализации автозаполнения на стороне сервера необходимо:

  1. Определите источник данных: в виджете SelectionInput добавьте DataSourceConfig , указывающий RemoteDataSource . Эта конфигурация указывает на функцию Apps Script, которая получает подсказки автозаполнения.
  2. Реализуйте функцию автозаполнения: эта функция срабатывает, когда пользователь вводит текст в поле ввода. Функция должна запрашивать данные из внешнего источника на основе ввода пользователя и возвращать список подсказок.

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

Apps Script 

// In your onConfig function:
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)
                ))
        )
    );

// ... add widget to card ...

Обработайте запрос автозаполнения.

Функция, указанная в setFunctionName (например, getAutocompleteResults ), получает объект события, когда пользователь вводит текст в поле. Эта функция должна:

  1. Проверьте значение event.workflow.elementUiAutocomplete.invokedFunction , чтобы убедиться, что оно соответствует ожидаемому имени функции.
  2. Получите ввод пользователя из event.workflow.elementUiAutocomplete.query .
  3. Выполните запрос к внешнему источнику данных, используя соответствующий запрос.
  4. Возвращает до 100 предложений в требуемом формате.

В следующем примере показано, как реализовать функцию handleAutocompleteRequest() для возврата подсказок на основе запроса пользователя:

Apps Script 

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 based on the query
  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();
}

// In your onConfig function, handle the autocomplete event
function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // ... rest of your card building logic ...
}

Особенности и ограничения использования карты