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

Собирайте контакты и управляйте ими в Google Chat

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

Посмотрите приложение Чат в действии:

Рис. 1. Приложение Chat отвечает на команду косой черты /about текстовым сообщением и кнопкой, открывающей контактную форму.
Рисунок 2. Приложение «Чат» открывает диалоговое окно, в котором пользователи могут ввести информацию о контакте.
Рисунок 3. Приложение Chat возвращает диалоговое окно подтверждения, чтобы пользователи могли просмотреть и подтвердить информацию перед отправкой.
Рисунок 4. После того, как пользователь отправит форму, приложение Chat отправляет личное текстовое сообщение для подтверждения отправки.
Рисунок 5. Приложение «Чат» также предлагает пользователям добавить контакт из карточки в сообщении.

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

Аккаунт Google Workspace для бизнеса или предприятия с доступом к Google Chat .

Цели

Проектируйте и создавайте пользовательские интерфейсы (UI) в виде объектов card и отображайте их в сообщениях и диалогах.
Получайте и обрабатывайте информацию, которую пользователи отправляют с помощью виджетов ввода форм .
Отвечайте на команды с косой чертой , отправляя сообщения, содержащие текст, карточки и дополнительные виджеты.

Архитектура

Приложение Chat создано на основе Google Apps Script и использует события взаимодействия для обработки пользователей чата и ответа на них.

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

Пользователь открывает прямое сообщение с помощью приложения Chat или добавляет приложение Chat в существующее пространство.
Приложение «Чат» предлагает пользователю добавить контакт, создав и отобразив контактную форму в виде объекта card . Чтобы представить контактную форму, приложение Chat отвечает пользователям следующим образом:
- Отвечает на @упоминания и прямые сообщения сообщением-карточкой, содержащей контактную форму.
- Отвечает на команду /addContact , открывая диалог с контактной формой.
- Отвечает на команду косой черты /about текстовым сообщением с кнопкой «Добавить контакт» , которую пользователи могут нажать, чтобы открыть диалоговое окно с контактной формой.
При отображении контактной формы пользователь вводит контактную информацию в следующие поля и виджеты:
- Имя и фамилия : виджет textInput , который принимает строки.
- Birthdate : виджет dateTimePicker , который принимает только даты.
- Тип контакта : виджет selectionInput с переключателями, который позволяет пользователям выбирать и отправлять одно строковое значение ( Personal или Work ).
- Кнопка «Просмотреть и отправить» : массив buttonList с виджетом button , который пользователь нажимает, чтобы отправить введенные значения.
Приложение Google Chat обрабатывает событие взаимодействия CARD_CLICKED для обработки значений, которые вводит пользователь, и отображает значения в карточке подтверждения.
Пользователь просматривает карточку подтверждения и нажимает кнопку «Отправить», чтобы завершить ввод контактной информации.
Приложение Google Chat отправляет личное текстовое сообщение, подтверждающее отправку.

Подготовьте окружающую среду

В этом разделе показано, как создать и настроить проект Google Cloud для приложения Chat.

Создайте проект Google Cloud

Консоль Google Cloud

В консоли Google Cloud выберите > IAM и администрирование > Создать проект .
Перейти к созданию проекта
В поле «Имя проекта » введите описательное имя вашего проекта.
Необязательно: Чтобы изменить идентификатор проекта , нажмите «Изменить» . Идентификатор проекта нельзя изменить после его создания, поэтому выберите идентификатор, который соответствует вашим потребностям на протяжении всего срока существования проекта.
В поле «Местоположение » нажмите «Обзор» , чтобы отобразить возможные местоположения для вашего проекта. Затем нажмите «Выбрать» .
Внимание! Не можете найти свою организацию в Google Workspace?
Это означает, что вы не вошли в учетную запись Google Workspace. Некоторые функции, описанные в документации для разработчиков Google Workspace, доступны только для проектов, связанных с организацией.
Нажмите Создать . Консоль Google Cloud перейдет на страницу панели инструментов, и ваш проект будет создан в течение нескольких минут.

интерфейс командной строки gcloud

В одной из следующих сред разработки получите доступ к Google Cloud CLI ( gcloud ):

Cloud Shell : чтобы использовать онлайн-терминал с уже настроенным интерфейсом командной строки gcloud, активируйте Cloud Shell.
Активировать Cloud Shell
Локальная оболочка : чтобы использовать локальную среду разработки, установите и инициализируйте интерфейс командной строки gcloud.
Чтобы создать облачный проект, используйте команду gcloud projects create :
```
gcloud projects create PROJECT_ID
```
Замените PROJECT_ID , указав идентификатор проекта, который вы хотите создать.

Настройте аутентификацию и авторизацию

Приложения Google Chat требуют настройки экрана согласия OAuth , чтобы пользователи могли авторизовать ваше приложение в приложениях Google Workspace, включая Google Chat.

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

> API и службы > Экран согласия OAuth .
Перейдите на экран согласия OAuth.
В разделе «Тип пользователя» выберите «Внутренний» , затем нажмите «Создать» .
В поле «Имя приложения» введите Contact Manager .
В разделе «Электронная почта поддержки пользователей» выберите свой адрес электронной почты или соответствующую группу Google.
В разделе «Контактная информация разработчика» введите свой адрес электронной почты.
Нажмите «Сохранить и продолжить» .
На странице «Области» нажмите «Сохранить и продолжить» . (Приложению Chat не требуются области OAuth.)
Просмотрите сводку и нажмите «Вернуться на панель мониторинга» .

Создайте и разверните приложение чата

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

При желании вы можете просмотреть весь проект на GitHub.

Посмотреть на GitHub

Вот обзор каждого файла:

main.gs

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

Посмотреть код `main.gs`

приложения-скрипт/контакт-форма-приложение/main.gs

Посмотреть на GitHub

/**
 * Copyright 2024 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Responds to a MESSAGE interaction event in Google Chat.
 *
 * @param {Object} event the MESSAGE interaction event from Chat API.
 * @return {Object} message response that opens a dialog or sends private
 *                          message with text and card.
 */
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1:
        // If the slash command is "/about", responds with a text message and button
        // that opens a dialog.
        return {
          text: "Manage your personal and business contacts 📇. To add a " +
                  "contact, use the slash command `/addContact`.",
          accessoryWidgets: [{
            buttonList: { buttons: [{
              text: "Add Contact",
              onClick: { action: {
                function: "openInitialDialog",
                interaction: "OPEN_DIALOG"
              }}
            }]}
          }]
        }
      case 2:
        // If the slash command is "/addContact", opens a dialog.
        return openInitialDialog();
    }
  }

  // If user sends the Chat app a message without a slash command, the app responds
  // privately with a text and card to add a contact.
  return {
    privateMessageViewer: event.user,
    text: "To add a contact, try `/addContact` or complete the form below:",
    cardsV2: [{
      cardId: "addContactForm",
      card: {
        header: { title: "Add a contact" },
        sections:[{ widgets: CONTACT_FORM_WIDGETS.concat([{
          buttonList: { buttons: [{
            text: "Review and submit",
            onClick: { action: { function : "openConfirmation" }}
          }]}
        }])}]
      }
    }]
  };
}

/**
 * Responds to CARD_CLICKED interaction events in Google Chat.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @return {Object} message responses specific to the dialog handling.
 */
function onCardClick(event) {
  // Initial dialog form page
  if (event.common.invokedFunction === "openInitialDialog") {
    return openInitialDialog();
  // Confirmation dialog form page
  } else if (event.common.invokedFunction === "openConfirmation") {
    return openConfirmation(event);
  // Submission dialog form page
  } else if (event.common.invokedFunction === "submitForm") {
    return submitForm(event);
  }
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @return {Object} a message with an action response to open a dialog.
 */
function openInitialDialog() {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { dialog: { body: { sections: [{
      header: "Add new contact",
      widgets: CONTACT_FORM_WIDGETS.concat([{
        buttonList: { buttons: [{
          text: "Review and submit",
          onClick: { action: { function: "openConfirmation" }}
        }]}
      }])
    }]}}}
  }};
}

/**
 * Returns the second step as a dialog or card message that lets users confirm details.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} returns a dialog or private card message.
 */
function openConfirmation(event) {
  const name = fetchFormValue(event, "contactName") ?? "";
  const birthdate = fetchFormValue(event, "contactBirthdate") ?? "";
  const type = fetchFormValue(event, "contactType") ?? "";
  const cardConfirmation = {
    header: "Your contact",
    widgets: [{
      textParagraph: { text: "Confirm contact information and submit:" }}, {
      textParagraph: { text: "<b>Name:</b> " + name }}, {
      textParagraph: {
        text: "<b>Birthday:</b> " + convertMillisToDateString(birthdate)
      }}, {
      textParagraph: { text: "<b>Type:</b> " + type }}, {
      buttonList: { buttons: [{
        text: "Submit",
        onClick: { action: {
          function: "submitForm",
          parameters: [{
            key: "contactName", value: name }, {
            key: "contactBirthdate", value: birthdate }, {
            key: "contactType", value: type
          }]
        }}
      }]}
    }]
  };

  // Returns a dialog with contact information that the user input.
  if (event.isDialogEvent) {
    return { action_response: {
      type: "DIALOG",
      dialogAction: { dialog: { body: { sections: [ cardConfirmation ]}}}
    }};
  }

  // Updates existing card message with contact information that the user input.
  return {
    actionResponse: { type: "UPDATE_MESSAGE" },
    privateMessageViewer: event.user,
    cardsV2: [{
      card: { sections: [cardConfirmation]}
    }]
  }
}

/**
  * Validates and submits information from a dialog or card message
  * and notifies status.
  *
  * @param {Object} event the interactive event with parameters.
  * @return {Object} a message response that opens a dialog or posts a private
  *                  message.
  */
function submitForm(event) {
  const contactName = event.common.parameters["contactName"];
  // Checks to make sure the user entered a contact name.
  // If no name value detected, returns an error message.
  if (!contactName) {
    const errorMessage = "Don't forget to name your new contact!";
    if (event.dialogEventType === "SUBMIT_DIALOG") {
      return { actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "INVALID_ARGUMENT",
          userFacingMessage: errorMessage
        }}
      }};
    } else {
      return {
        privateMessageViewer: event.user,
        text: errorMessage
      };
    }
  }

  // The Chat app indicates that it received form data from the dialog or card.
  // Sends private text message that confirms submission.
  const confirmationMessage = "✅ " + contactName + " has been added to your contacts.";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return {
      actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "OK",
          userFacingMessage: "Success " + contactName
        }}
      }
    }
  } else {
    return {
      actionResponse: { type: "NEW_MESSAGE" },
      privateMessageViewer: event.user,
      text: confirmationMessage
    };
  }
}

/**
 * Extracts form input value for a given widget.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @param {String} widgetName a unique ID for the widget, specified in the widget's name field.
 * @returns the value inputted by the user, null if no value can be found.
 */
function fetchFormValue(event, widgetName) {
  const formItem = event.common.formInputs[widgetName][""];
  // For widgets that receive StringInputs data, the value input by the user.
  if (formItem.hasOwnProperty("stringInputs")) {
    const stringInput = event.common.formInputs[widgetName][""].stringInputs.value[0];
    if (stringInput != null) {
      return stringInput;
    }
  // For widgets that receive dateInput data, the value input by the user.
  } else if (formItem.hasOwnProperty("dateInput")) {
    const dateInput = event.common.formInputs[widgetName][""].dateInput.msSinceEpoch;
     if (dateInput != null) {
       return dateInput;
     }
  }

  return null;
}

/**
 * Converts date in milliseconds since epoch to user-friendly string.
 *
 * @param {Object} millis the milliseconds since epoch time.
 * @return {string} Display-friend date (English US).
 */
function convertMillisToDateString(millis) {
  const date = new Date(millis);
  const options = { year: 'numeric', month: 'long', day: 'numeric' };
  return date.toLocaleDateString('en-US', options);
}

contactForm.gs

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

Посмотреть код `contactForm.gs`

приложения-скрипт/контакт-форма-приложение/contactForm.gs

Посмотреть на GitHub

/**
 * Copyright 2024 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

appsscript.json

Манифест Apps Script , который определяет и настраивает проект Apps Script для приложения Chat.

Посмотреть код `appsscript.json`

приложения-скрипт/контакт-форма-приложение/appsscript.json

Посмотреть на GitHub

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "chat": {}
}

Найдите номер и идентификатор своего облачного проекта

В консоли Google Cloud перейдите к своему облачному проекту.
Перейдите в консоль Google Cloud.
Нажмите «Настройки и утилиты» > «Настройки проекта» .
Обратите внимание на значения в полях Номер проекта и Идентификатор проекта . Вы будете использовать их в следующих разделах.

Создайте проект скрипта приложений.

Чтобы создать проект Apps Script и связать его с проектом Cloud:

Нажмите следующую кнопку, чтобы открыть проект «Управление контактами в приложениях Google Chat Script».
Открыть проект
Нажмите Обзор .
На странице обзора нажмите Сделайте копию .
Назовите свою копию проекта Apps Script:
1. Нажмите «Копия управления контактами в Google Chat» .
2. В названии проекта введите Contact Manager - Google Chat app
3. Нажмите «Переименовать» .

Установите облачный проект проекта Apps Script.

В проекте Apps Script нажмите Настройки проекта .
В разделе «Проект Google Cloud Platform (GCP)» нажмите «Изменить проект» .
В поле «Номер проекта GCP» вставьте номер вашего облачного проекта.
Нажмите Установить проект . Проект Cloud и проект Apps Script теперь связаны.

Создание развертывания скрипта приложений

Теперь, когда весь код готов, разверните проект Apps Script. Идентификатор развертывания используется при настройке приложения Chat в Google Cloud.

В Apps Script откройте проект приложения Chat.
Перейти к скрипту приложений
Нажмите «Развертывание» > «Новое развертывание» .
Если надстройка еще не выбрана, рядом с пунктом «Выбрать тип» щелкните «Типы развертывания». и выберите «Дополнение» .
В поле «Описание» введите описание этой версии, например Test of Contact Manager .
Нажмите «Развернуть» . Apps Script сообщает об успешном развертывании и предоставляет идентификатор развертывания.
Нажмите Копировать », чтобы скопировать идентификатор развертывания, а затем нажмите «Готово» .

Настройте приложение Chat в консоли Google Cloud.

В этом разделе показано, как настроить API Google Chat в консоли Google Cloud, используя информацию о вашем приложении Chat, включая идентификатор развертывания, которое вы только что создали из проекта Apps Script.

В консоли Google Cloud нажмите Меню > продукты > Google Workspace > Библиотека продуктов > Google Chat API > Управление > Конфигурация .
Перейти к настройке API чата
В поле «Имя приложения» введите Contact Manager .
В URL-адресе аватара введите https://developers.google.com/chat/images/contact-icon.png .
В поле «Описание» введите Manage your personal and business contacts .
Установите переключатель «Включить интерактивные функции» во включенное положение.
В разделе «Функциональность» установите флажки « Получать сообщения 1:1» и «Присоединяться к группам и групповым беседам» .
В разделе «Настройки подключения » выберите «Скрипт приложений» .
В поле «Идентификатор развертывания » вставьте идентификатор развертывания Apps Script, который вы скопировали в предыдущем разделе при создании развертывания Apps Script.
В разделе «Команды косой черты » настройте команды косой черты /about и /addContact :
1. Нажмите «Добавить команду косой черты» , чтобы настроить первую команду косой черты.
2. В поле Имя введите /about .
3. В поле «Идентификатор команды» введите 1 .
4. В поле «Описание » введите Learn how to use this Chat app to manage your contacts .
5. Выбрать Открывает диалоговое окно .
6. Нажмите Готово .
7. Нажмите «Добавить команду косой черты» , чтобы настроить другую команду косой черты.
8. В поле Имя введите /addContact
9. В поле «Идентификатор команды» введите 2 .
10. В поле «Описание» введите Submit information about a contact .
11. Выбрать Открывает диалоговое окно .
12. Нажмите Готово .
В разделе «Видимость » установите флажок «Сделать это приложение чата доступным для определенных людей и групп в YOUR DOMAIN и введите свой адрес электронной почты.
В разделе «Журналы» выберите «Записывать ошибки в журнал» .
Нажмите Сохранить . Появится сообщение о сохранении конфигурации.

Приложение Chat готово к установке и тестированию в Chat.

Протестируйте приложение Чат

Чтобы протестировать приложение Chat, откройте пространство для прямых сообщений в приложении Chat и отправьте сообщение:

Откройте Google Chat, используя учетную запись Google Workspace, которую вы указали при добавлении себя в качестве доверенного тестировщика.
Перейти в чат Google
Нажмите новый чат» .
В поле «Добавить 1 или несколько человек» введите название вашего приложения чата.
Выберите приложение чата из результатов. Откроется прямое сообщение.
Примечание. Если вы не видите свое приложение Chat в списке результатов, убедитесь, что вы включили свою учетную запись Google Workspace в настройки видимости на странице конфигурации Chat API в консоли Google Cloud.

В новом прямом сообщении в приложении Chat введите /addContact и нажмите Enter .
В открывшемся диалоге введите контактную информацию:
1. В текстовом поле Имя и фамилия введите имя.
2. В поле выбора даты рождения выберите дату.
3. В разделе «Тип контакта» выберите переключатель « Рабочий» или «Личный» .
Нажмите «Просмотреть» и «Отправить» .
В диалоговом окне подтверждения проверьте предоставленную вами информацию и нажмите «Отправить» . Приложение чата отвечает текстовым сообщением с надписью ✅ CONTACT NAME has been added to your contacts. .
При желании вы также можете протестировать и отправить контактную форму следующими способами:
- Используйте косую черту /about . Приложение чата отвечает текстовым сообщением и кнопкой дополнительного виджета с надписью Add a contact . Вы можете нажать кнопку, чтобы открыть диалоговое окно с контактной формой.
- Отправьте в приложение «Чат» прямое сообщение без косой черты, например Hello . Приложение «Чат» отвечает текстовым сообщением и карточкой с контактной формой.

Очистить

Чтобы избежать списания средств с вашей учетной записи Google Cloud за ресурсы, используемые в этом руководстве, мы рекомендуем вам удалить проект Cloud.

Внимание: Удаление проекта имеет следующие последствия:

Все в проекте удалено. Если для этого руководства вы использовали существующий проект, то при его удалении вы также удаляете всю другую работу, выполненную в этом проекте.
Пользовательские идентификаторы проектов теряются. Создавая этот проект, вы, возможно, создали собственный идентификатор проекта, который хотите использовать в будущем. Чтобы сохранить URL-адреса, использующие идентификатор проекта, например URL-адрес на сайте appspot.com, удалите выбранные ресурсы внутри проекта, а не удаляйте весь проект.

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

В консоли Google Cloud перейдите на страницу «Управление ресурсами» . Нажмите Меню > IAM и администрирование > ресурсами .
Зайдите в диспетчер ресурсов
В списке проектов выберите проект, который хотите удалить, и нажмите «Удалить .
В диалоговом окне введите идентификатор проекта и нажмите «Завершить работу», чтобы удалить проект.

Собирайте контакты и управляйте ими в Google Chat

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

Цели

Архитектура

Подготовьте окружающую среду

Создайте проект Google Cloud

Консоль Google Cloud

интерфейс командной строки gcloud

Настройте аутентификацию и авторизацию

Создайте и разверните приложение чата

Посмотреть код main.gs

Посмотреть код contactForm.gs

Посмотреть код appsscript.json

Найдите номер и идентификатор своего облачного проекта

Создайте проект скрипта приложений.

Установите облачный проект проекта Apps Script.

Создание развертывания скрипта приложений

Настройте приложение Chat в консоли Google Cloud.

Протестируйте приложение Чат

Очистить

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

Посмотреть код `main.gs`

Посмотреть код `contactForm.gs`

Посмотреть код `appsscript.json`