Собирайте и обрабатывайте информацию от пользователей Google Chat.

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

В Google Chat дополнения отображаются пользователям как приложения Google Chat. Дополнительную информацию см. в обзоре расширения Google Chat .

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

• Настройте параметры. Например, чтобы позволить пользователям настраивать параметры уведомлений или настраивать и добавлять приложение Chat в одно или несколько пространств.
• Создавайте или обновляйте информацию в других приложениях Google Workspace. Например, разрешите пользователям создавать события Календаря Google.
• Разрешите пользователям получать доступ и обновлять ресурсы в других приложениях или веб-службах. Например, приложение чата может помочь пользователям обновить статус заявки в службу поддержки непосредственно из пространства чата.

Предварительные условия

Создавайте формы с помощью карточек

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

• Сообщения чата, содержащие одну или несколько карточек.
• Диалоги — карточки, открывающиеся в новом окне из сообщений и домашних страниц.

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

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

  • Текстовые входы ( textInput ) для произвольного или предлагаемого текста.

  • Входные данные выбора ( selectionInput ) — это выбираемые элементы пользовательского интерфейса, такие как флажки, переключатели и раскрывающиеся меню. Виджеты ввода выбора также могут заполнять и предлагать элементы из данных Google Workspace (например, из области чата) или динамического источника данных. Подробную информацию см. в следующем разделе «Добавление меню с множественным выбором» .

  • Средства выбора даты и времени ( dateTimePicker ) для записей даты и времени.

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

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

Дополнительные примеры интерактивных виджетов, которые можно использовать для сбора информации, см. в разделе «Разработка интерактивной карточки или диалогового окна» документации API Google Chat.

Добавить меню с множественным выбором

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

Вы можете заполнить элементы для меню с множественным выбором из следующих источников данных:

• Данные Google Workspace , которые включают пользователей или чат-группы, участником которых является пользователь. Меню содержит элементы только из одной организации Google Workspace.
• Внешние источники данных , например реляционная база данных. Например, вы можете использовать меню с множественным выбором, чтобы помочь пользователю выбрать из списка потенциальных клиентов из системы управления взаимоотношениями с клиентами (CRM).

Заполнение элементов из источника данных Google Workspace

Чтобы использовать источники данных Google Workspace, укажите поле platformDataSource в виджете SelectionInput . В отличие от других типов ввода выбора, вы опускаете объекты SelectionItem , поскольку эти элементы выбора динамически извлекаются из Google Workspace.

Следующий код показывает меню с множественным выбором пользователей Google Workspace. Чтобы заполнить пользователей, вход выбора устанавливает commonDataSource в USER :

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

Следующий код показывает меню с множественным выбором пространств чата. Для заполнения пробелов входные данные выбора указывают поле hostAppDataSource . Меню множественного выбора также устанавливает для defaultToCurrentSpace значение true , что делает текущее пространство выбором по умолчанию в меню:

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Заполнение элементов из внешнего источника данных

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

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

Следующий код показывает меню с множественным выбором, которое запрашивает и заполняет элементы из внешнего источника данных:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "externalDataSource": { "function": "FUNCTION" },
    // Suggested items loaded by default.
    // The list is static here but it could be dynamic.
    "items": [FUNCTION]
  }
}

Замените FUNCTION URL-адресом HTTP или именем функции скрипта приложений, которая запрашивает внешнюю базу данных. Полный пример, показывающий, как вернуть предложенные элементы, см. в разделе «Предложение элементов с множественным выбором» .

Получайте данные от интерактивных виджетов

Каждый раз, когда пользователи нажимают кнопку, ее действие в приложении чата запускается с информацией о взаимодействии. В commonEventObject полезных данных события объект formInputs содержит любые значения, которые вводит пользователь.

Вы можете получить значения из объекта commonEventObject.formInputs. WIDGET_NAME , где WIDGET_NAME — это поле name , указанное вами для виджета. Значения возвращаются как определенный тип данных для виджета.

Ниже показана часть объекта события, в которой пользователь ввел значения для каждого виджета:

{
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

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

После того как приложение Chat получит данные, оно сможет выполнить любое из следующих действий:

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

Предлагать множественный выбор элементов

Если карточка содержит меню с множественным выбором, которое заполняет элементы из внешнего источника данных , приложение Chat может возвращать предлагаемые элементы на основе того, что пользователи вводят в меню. Например, если пользователь начинает вводить Atl для меню, в котором представлены города в США, ваше приложение Chat может автоматически предложить Atlanta до того, как пользователь завершит ввод. Приложение «Чат» может предложить до 100 элементов.

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

1. Обработка объекта события , который приложение Chat получает, когда пользователи вводят данные в меню.
2. Из объекта события получите значение, введенное пользователем, которое представлено в поле event.commonEventObject.parameters["autocomplete_widget_query"] .
3. Запросите источник данных, используя введенное пользователем значение, чтобы получить один или несколько SelectionItems которые можно будет предложить пользователю.
4. Верните предложенные элементы, вернув действие RenderActions с modifyCard .

В следующем примере кода показано, как приложение Chat динамически предлагает элементы в меню с множественным выбором на карточке. Когда пользователь вводит данные в меню, функция или конечная точка, указанная в поле externalDataSource виджета, запрашивает внешний источник данных и предлагает элементы, которые пользователь может выбрать.

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.selectionInput = function selectionInput(req, res) {
  if (req.method === 'GET' || !req.body.chat) {
    return res.send('Hello! This function is meant to be used ' +
        'in a Google Chat Space.');
  }
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.send(queryContacts(req.body));
  }
  // Replies with a card that contains the multiselect menu.
  return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "FUNCTION_URL" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
};

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact"3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the interactive event.
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Перенос данных на другую карту

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

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

Чтобы перенести ввод данных из исходной карты, вы можете создать виджет button с actionParameters , которые содержат name виджета и значение, введенное пользователем, как показано в следующем примере:

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

Где WIDGET_NAME — это name виджета, а USER_INPUT_VALUE — это то, что вводит пользователь. Например, для ввода текста, который собирает имя человека, имя виджета — contactName , а значение примера — Kai O

Когда пользователь нажимает кнопку, ваше приложение Chat получает объект события, из которого вы можете получать данные .

Ответ на отправку формы

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

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

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle message payloads in the event object
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle button clicks on the card
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

Чтобы обработать и закрыть диалоговое окно, вы возвращаете объект RenderActions , который указывает, хотите ли вы отправить подтверждающее сообщение, обновить исходное сообщение или карточку или просто закрыть диалоговое окно. Инструкции см. в разделе Закрытие диалогового окна .

Устранение неполадок

Когда приложение или карточка Google Chat возвращает ошибку, в интерфейсе Chat отображается сообщение «Что-то пошло не так». или «Невозможно обработать ваш запрос». Иногда в пользовательском интерфейсе чата не отображается сообщение об ошибке, но приложение или карточка чата выдает неожиданный результат; например, сообщение с карточкой может не появиться.

Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, доступны описательные сообщения об ошибках и данные журнала, которые помогут вам исправить ошибки, если включено ведение журнала ошибок для приложений чата. Информацию о просмотре, отладке и исправлении ошибок см. в разделе «Устранение неполадок и исправление ошибок Google Chat» .