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

Отправляйтесь в отпуск с приложением Google Chat

1. Введение

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

В этом практическом занятии вы научитесь создавать чат-приложение — «Приложение для учета посещаемости в чате» — которое добавляет ответственных за уведомления об отпуске в Gmail и планирует встречи в Google Календаре. Создав приложение для учета посещаемости в чате на основе Google Apps Script , вы сможете легко получить доступ к другим сервисам Google, таким как Drive, Gmail, Calendar, Docs, Sheets и многим другим.

Что вы узнаете

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

Что вам понадобится

Доступ к интернету и веб-браузеру.
Учетная запись Google Workspace с доступом к Google Chat .
Базовые навыки работы с JavaScript — Google Apps Script поддерживает только JavaScript.

2. Получите пример кода.

Чтобы посмотреть код для каждого шага в этом примере, вы можете либо скачать ZIP-файл, либо клонировать репозиторий GitHub.

Папки step-NN в каталоге apps-script/attendance-chat-app содержат конечное состояние каждого шага этого практического занятия. Они предназначены для справки.

Скачать код

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

Распакуйте загруженный ZIP-файл. В результате будет распакована корневая папка ( google-chat-samples ), содержащая по одной папке для каждого шага этого практического задания в папке apps-script/attendance-chat-app .

Клонируйте репозиторий GitHub.

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

git clone https://github.com/googleworkspace/google-chat-samples

3. Создайте обработчики событий для Google Chat.

Создайте проект Apps Script.

Для создания проекта Apps Script выполните следующие действия:

Перейдите в файл script.new .
Нажмите на «Безымянный проект» .
Переименуйте скрипт в приложение «Чат для учета посещаемости» и нажмите «Переименовать» .

События в Google Чате

Большинство взаимодействий Apps Script с чатом основаны на событиях. Взаимодействие между пользователем, приложением чата и самим чатом обычно происходит в следующей последовательности:

Пользователь инициирует действие, например, добавляет приложение чата в пространство, начинает личное сообщение (DM) с помощью приложения чата или удаляет приложение чата из пространства.
Данная акция запускает событие, ориентированное на приложение «Чат» внутри приложения «Чат».
Чат вызывает соответствующий обработчик событий, определенный в скрипте приложения «Чат».

Чат генерирует 4 события, которые может отслеживать ваше приложение:

ADDED_TO_SPACE : Это событие происходит, когда пользователь добавляет приложение чата в пространство или отправляет личное сообщение (DM). В Apps Script для обработки этого события определяется функция onAddToSpace() .
REMOVED_FROM_SPACE : Это событие происходит, когда пользователь удаляет приложение Chat из пространства или личных сообщений. В ответ на это событие в Chat не отправляется никакая информация. В Apps Script для обработки этого события определяется функция onRemoveFromSpace() .
MESSAGE : Это событие происходит, когда пользователь отправляет сообщение в приложение «Чат», либо напрямую в личных сообщениях, либо в виде упоминания (@mention) в пространстве. В Apps Script вы определяете функцию onMessage() для обработки этого события.
CARD_CLICKED : Это событие происходит, когда пользователь нажимает кнопку с назначенным ей действием. В Apps Script для реагирования на это событие определяется функция onCardClick() .

Замените содержимое файла Code.gs следующим кодом, определяющим обработчики событий ADDED_TO_SPACE и REMOVE_FROM_SPACE . (Обработчики событий MESSAGE и CARD_CLICKED вы добавите позже в этом практическом занятии.)

Code.gs

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onAddToSpace(event) {
  console.info(event);
  var message = 'Thank you for adding me to ';
  if (event.space.type === 'DM') {
    message += 'a DM, ' + event.user.displayName + '!';
  } else {
    message += event.space.displayName;
  }
  return { text: message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onRemoveFromSpace(event) {
  console.info(event);
  console.log('Chat app removed from ', event.space.name);
}

4. Опубликуйте и протестируйте приложение чата.

Обновите файл манифеста скрипта.

Прежде чем опубликовать приложение в Chat, необходимо обновить манифест скрипта.

Нажмите «Настройки проекта» . .
Установите флажок «Показать файл манифеста "appsscript.json" в редакторе» .
Редактор кликов .
Щелкните файл appsscript.json .
Добавьте строку "chat": {} в файл манифеста.

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

appsscript.json

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "chat": {}
}

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

Прежде чем запускать и тестировать приложение «Чат», необходимо создать проект Google Cloud, включить и настроить API чата, а также опубликовать приложение «Чат» в своей организации Google Workspace.

В консоли Google Cloud перейдите в меню. > IAM и администрирование > Создать проект .
В поле «Название проекта» введите описательное название.
При появлении запроса выберите Организацию и платежный аккаунт .
Нажмите «Создать» .
После завершения создания проекта в правом верхнем углу страницы появится уведомление. Щелкните по пункту « Создать проект: <Название проекта>» , чтобы открыть проект.
Нажмите «Меню» > API и сервисы > Учетные данные .
Нажмите на экран согласия OAuth .
В поле «Название приложения» введите «Приложение для чата по учету посещаемости» .
При появлении запроса введите адрес электронной почты службы поддержки пользователей и контактную информацию разработчика.
Нажмите «Сохранить и продолжить» .
Нажмите «Настройки и утилиты». > Настройки проекта .
Скопируйте номер проекта .
Вернитесь в редактор App Script и нажмите «Настройки проекта» . .
В разделе «Проект Google Cloud Platform (GCP)» нажмите «Изменить проект» .
Нажмите на номер проекта GCP и введите номер проекта.
Нажмите «Установить проект» .

Опубликуйте приложение в чате.

Чтобы опубликовать ваше приложение чата в Google Chat, выполните следующие действия:

В редакторе Apps Script нажмите «Развернуть» > «Новое развертывание» .
Рядом с пунктом «Выберите тип» нажмите «Включить типы развертывания». .
Выберите «Дополнение» и нажмите «Развернуть» .
Скопируйте идентификатор развертывания и нажмите «Готово» .
В консоли Google Cloud перейдите в меню. > API и сервисы > Библиотека .
Найдите Google Chat API . Выберите API из списка результатов.
На странице Google Chat API нажмите «Включить» .
После включения API нажмите «Конфигурация» . Игнорируйте любые сообщения с просьбой создать учетные данные.
На странице «Настройки» выполните следующие действия:

Снимите флажок «Создать это приложение чата как надстройку для рабочей области» и нажмите «ОТКЛЮЧИТЬ» для подтверждения.
В поле «Название приложения» введите «Приложение для чата по учету посещаемости» .
Для указания URL-адреса аватара введите https://goo.gl/kv2ENA .
В поле «Описание» введите Apps Script codelab Chat app .
В разделе «Функциональность» выберите «Получать сообщения один на один» .
В разделе «Настройки подключения» выберите проект Apps Script и вставьте идентификатор развертывания вашего скрипта в текстовое поле.
В разделе «Разрешения» выберите «Конкретные люди и группы в вашем домене» . В текстовом поле под раскрывающимся меню введите свой адрес электронной почты, связанный с вашей организацией Google Workspace.
Нажмите « Сохранить ».

Примечание : При попытке включить API Google Chat с помощью учетной записи @gmail.com вы получите следующую ошибку:

API-интерфейс "chat.googleapis.com" не существует, или у вас нет разрешения на доступ к нему.

Убедитесь, что вы вошли в систему с помощью учетной записи Google Workspace и/или воспользуйтесь переключателем учетных записей в правом верхнем углу консоли Cloud, чтобы переключиться на учетную запись Google Workspace. Если вы создали свой скрипт с помощью учетной записи @gmail.com, вам необходимо предоставить к нему доступ вашей учетной записи Google Workspace.

После сохранения изменений убедитесь, что на странице Google Chat API статус приложения отображается как LIVE — доступно пользователям .

Протестируйте приложение для чата

Чтобы протестировать ваше приложение в Google Chat, выполните следующие действия:

Откройте Google Чат .
Отправьте новое личное сообщение в приложение «Чат», нажав кнопку «Начать чат». > Найти приложения .
На странице поиска приложений найдите приложение «Чат для учета посещаемости» .
Рядом с приложением «Чат для учета посещаемости» нажмите «Добавить» > «Чат» .

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

5. Определите формат ответа в виде карточки.

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

Ответы на карточки

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

На следующем изображении показан ответ в виде карточки, состоящий из трех разделов: заголовка, виджета «ключ/значение», виджета изображения и текстовой кнопки.

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

Code.gs

const DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
const HEADER = {
  header: {
    title : 'Attendance Chat app',
    subtitle : 'Log your vacation time',
    imageUrl : DEFAULT_IMAGE_URL
  }
};

/**
 * Creates a card-formatted response.
 * @param {object} widgets the UI components to send
 * @return {object} JSON-formatted response
 */
function createCardResponse(widgets) {
  return {
    cards: [HEADER, {
      sections: [{
        widgets: widgets
      }]
    }]
  };
}

/**
 * Responds to a MESSAGE event triggered
 * in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return JSON-formatted response
 */
function onMessage(event) {
  const userMessage = event.message.text;

  const widgets = [{
    "textParagraph": {
      "text": "You said: " + userMessage
    }
  }];

  return createCardResponse(widgets);
}

Функция onMessage() , добавленная на этом шаге, считывает исходное сообщение пользователя и формирует ответ в виде простого виджета TextParagraph . Затем функция onMessage() вызывает createCardResponse() , которая помещает виджет TextParagraph в раздел одной карточки. Приложение чата возвращает объект JavaScript, созданный с помощью ответа на карточку, обратно в Google Chat.

Протестируйте приложение для чата

Чтобы протестировать это приложение, вернитесь в личные сообщения в Google Chat и напишите сообщение (подойдет любое).

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

Для получения дополнительной информации о структуре объектов событий, отправляемых Google Chat, см. справочник по форматам событий .

6. Реагируйте на нажатия кнопок в карточках.

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

Интерактивные карты

В ответах в виде карточек могут содержаться кнопки двух типов: текстовые кнопки, отображающие только текстовые кнопки; и кнопки с изображением, отображающие кнопку с простым значком или изображением без текста. Как текстовые кнопки, так и кнопки с изображением поддерживают одно из двух действий onClick (как определено в JSON-ответе, отправленном в Google Chat): openLink или action . Как следует из названия, openLink открывает указанную ссылку в новой вкладке браузера.

Объект action определяет пользовательское действие, которое должна выполнить кнопка. В объекте действия можно указать несколько произвольных значений, включая уникальное actionMethodName и набор пар ключ/значение.

Указание объекта action для кнопки создает интерактивную карточку . Когда пользователь нажимает кнопку в сообщении, Google Chat генерирует событие CARD_CLICKED и отправляет запрос обратно приложению, отправившему исходное сообщение. Затем приложению необходимо обработать событие, сгенерированное Google Chat, и вернуть ответ в пространство.

Замените функцию onMessage() в Code.gs следующим кодом. Этот код создаст две кнопки: « Установить отпуск в Gmail» и «Заблокировать день в календаре» в карточке, отправленной в чат Google.

Code.gs

const REASON = {
  SICK: 'Out sick',
  OTHER: 'Out of office'
};
/**
 * Responds to a MESSAGE event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 */
function onMessage(event) {
  console.info(event);
  const reason = REASON.OTHER;
  const name = event.user.displayName;
  const userMessage = event.message.text;

  // If the user said that they were 'sick', adjust the image in the
  // header sent in response.
  if (userMessage.indexOf('sick') > -1) {
    // Hospital material icon
    HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
    reason = REASON.SICK;
  } else if (userMessage.indexOf('vacation') > -1) {
    // Spa material icon
    HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
  }

  const widgets = [{
    textParagraph: {
      text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
    }
  }, {
    buttons: [{
      textButton: {
        text: 'Set vacation in Gmail',
        onClick: {
          action: {
            actionMethodName: 'turnOnAutoResponder',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }, {
      textButton: {
        text: 'Block out day in Calendar',
        onClick: {
          action: {
            actionMethodName: 'blockOutCalendar',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }]
  }];
  return createCardResponse(widgets);
}

Для обработки события CARD_CLICKED необходимо добавить функцию onCardClick() в скрипт вашего чат-приложения. Добавьте следующий код, определяющий функцию onCardClick() : Code.gs

Code.gs

/**
 * Responds to a CARD_CLICKED event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onCardClick(event) {
  console.info(event);
  let message = '';
  const reason = event.action.parameters[0].value;
  if (event.action.actionMethodName == 'turnOnAutoResponder') {
    turnOnAutoResponder(reason);
    message = 'Turned on vacation settings.';
  } else if (event.action.actionMethodName == 'blockOutCalendar') {
    blockOutCalendar(reason);
    message = 'Blocked out your calendar for the day.';
  } else {
    message = "I'm sorry; I'm not sure which button you clicked.";
  }
  return { text: message };
}

В ответ на клики пользователя приложение «Чат» теперь выполняет одно из двух действий: устанавливает в Gmail в качестве автоматического ответа на сообщение «нет на рабочем месте» или планирует встречу на весь день в календаре пользователя. Для выполнения этих задач приложение вызывает расширенную службу Gmail и службу календаря .

Добавьте следующий код в свой скрипт, чтобы интегрировать приложение «Чат» с Gmail и Календарем.

Code.gs

const ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
 * Turns on the user's vacation response for today in Gmail.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function turnOnAutoResponder(reason) {
  let currentTime = (new Date()).getTime();
  Gmail.Users.Settings.updateVacation({
    enableAutoReply: true,
    responseSubject: reason,
    responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Chat app!</i>",
    restrictToContacts: true,
    restrictToDomain: true,
    startTime: currentTime,
    endTime: currentTime + ONE_DAY_MILLIS
  }, 'me');
}

/**
 * Places an all-day meeting on the user's Calendar.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function blockOutCalendar(reason) {
  CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}

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

В редакторе Apps Script рядом с пунктом «Службы» нажмите «Добавить службу». .
Выберите API Gmail .
Нажмите на кнопку «Панель управления API Google Cloud Platform» ниже, чтобы открыть консоль Google Cloud .
Нажмите «Включить API и сервисы» .
Найдите Gmail API и нажмите на ссылку Gmail API.
На странице API Gmail нажмите «Включить» .

Протестируйте приложение для чата

Чтобы протестировать эту версию вашего приложения для чата, откройте личное сообщение, которое вы создали на предыдущих шагах в Google Chat , и напишите: «Я уезжаю в отпуск» . Приложение должно ответить карточкой, похожей на изображение ниже.

Примечание: Если вас попросят предоставить доступ к приложению, вам, возможно, придётся ввести сообщение ещё раз.

7. Поздравляем!

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

Что мы рассмотрели

Создал и опубликовал приложение Google Chat с помощью Apps Script.
Отвечал на сообщения пользователей простым ответом.
Взаимодействовал с другими сервисами Google Workspace от имени пользователя через приложение «Чат».

Отправляйтесь в отпуск с приложением Google Chat Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

1. Введение

Что вы узнаете

Что вам понадобится

2. Получите пример кода.

Скачать код

Клонируйте репозиторий GitHub.

3. Создайте обработчики событий для Google Chat.

Создайте проект Apps Script.

События в Google Чате

Code.gs

4. Опубликуйте и протестируйте приложение чата.

Обновите файл манифеста скрипта.

appsscript.json

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

Опубликуйте приложение в чате.

Протестируйте приложение для чата

5. Определите формат ответа в виде карточки.

Ответы на карточки

Code.gs

Протестируйте приложение для чата

6. Реагируйте на нажатия кнопок в карточках.

Интерактивные карты

Code.gs

Code.gs

Code.gs

Протестируйте приложение для чата

7. Поздравляем!

Что мы рассмотрели

Узнать больше

Отправляйтесь в отпуск с приложением Google Chat