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

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

1. Введение

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

В этой лабораторной работе вы узнаете, как создать приложение чата — «Приложение чата для учета посещаемости», которое назначает автоответчики в Gmail и планирует встречи в Google Календаре. Создав приложение чата для учета посещаемости в Google Apps Script , вы сможете легко получить доступ к другим сервисам Google, таким как Диск, Gmail, Календарь, Документы, Таблицы и многим другим.

Чему вы научитесь

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

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

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

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

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

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

Загрузить код

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

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

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

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

git clone https://github.com/googleworkspace/apps-script-samples

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

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

Чтобы создать проект Apps Script, выполните следующие шаги:

Перейти к script.new .
Нажмите Проект без названия .
Переименуйте скрипт приложения Attendance Chat и нажмите Rename .

События в Google Chat

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

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

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

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

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

Код.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

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

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

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

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

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

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

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

API «chat.googleapis.com» не существует или у вас нет разрешения на доступ к нему.

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

После сохранения изменений убедитесь, что на странице API Google Chat отображается статус приложения « ДОСТУПНО — доступно пользователям» .

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

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

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

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

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

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

Ответы карт

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

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

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

Код.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() , добавленная на этом этапе, считывает исходное сообщение пользователя и формирует ответ в виде простого виджета TextParagragh . Затем функция onMessage() вызывает метод createCardResponse() , который помещает виджет TextParagraph в раздел одной карточки. Приложение Chat возвращает в Google Chat объект JavaScript, созданный на основе ответа карточки.

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

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

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

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

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

На предыдущем этапе ваше приложение Chat ответило на сообщение пользователя (событие MESSAGE ) простой карточкой, содержащей виджет TextParagragh . На этом этапе вы создаёте ответ, включающий кнопки, для каждой из которых определено настраиваемое действие.

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

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

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

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

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

Код.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 .

Код.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 };
}

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

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

Код.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, выполните следующие действия:

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

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

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

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

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

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

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

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

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

1. Введение

Чему вы научитесь

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

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

Загрузить код

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

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

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

События в Google Chat

Код.gs

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

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

appsscript.json

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

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

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

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

Ответы карт

Код.gs

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

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

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

Код.gs

Код.gs

Код.gs

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

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

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

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

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