Расширьте возможности своего почтового ящика Gmail с помощью функций Google Cloud

1. Введение

Миллиарды компаний и частных лиц используют Gmail и другие сервисы G Suite для передачи и обработки данных. Google предлагает API-интерфейсы G Suite, которые помогут вам получить программный доступ к информации в этих сервисах, и вы можете использовать API-интерфейсы, чтобы легко автоматизировать свой ежедневный рабочий процесс. В ходе этой лабораторной работы вы создадите мощное расширение Gmail, которое автоматически классифицирует электронные письма во входящих сообщениях и сохраняет эти категории в таблице Google. Это расширение будет использовать API RESTful G Suite, функции Google Cloud и другие сервисы Google Cloud Platform.

Что вы построите

В ходе этой лабораторной работы вы создадите и развернете несколько облачных функций, связанных с API G Suite и другими сервисами Google Cloud Platform. Эти функции будут:

  • Разрешите безопасный доступ к вашим данным Gmail и Google Sheets.
  • Извлекайте изображения, прикрепленные к любой входящей почте
  • Классифицируйте эти изображения с помощью API Cloud Vision.
  • Запишите эти категории, адрес отправителя и имя вложения в Google Sheet.

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

  • Основы RESTful API G Suite
  • Основы функций Google Cloud и других сервисов Google Cloud Platform.
  • Как получить программный доступ к Gmail с помощью Google Cloud Functions

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

  • Учетная запись Google с доступом к Gmail и Google Sheets. Если у вас его нет, создайте его здесь .
  • Базовые знания Javascript/Node.js.

2. Прежде всего

Включите API

На этом лабораторном занятии вы будете использовать следующие продукты/услуги Google:

  • Облачные функции Google
  • Google Cloud Pub/Sub
  • API Google Cloud Vision
  • Облачное хранилище данных Google
  • API Gmail
  • API Google Таблиц

Облачные функции Google

Google Cloud Functions — это бессерверная платформа Google «Функции как услуга», которая позволяет запускать отдельные фрагменты кода («функции») простым и масштабируемым способом.

Чтобы включить функции Google Cloud, щелкните гамбургер-меню в левом верхнем углу экрана, чтобы открыть левую боковую панель навигации:

f457988e33594bb6.png

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

Google Cloud Pub/Sub

Google Cloud Pub/Sub — это простая и масштабируемая основа для потоковой передачи данных и доставки событий. В этой лабораторной работе он служит связующим звеном между Gmail и Google Cloud Functions.

Чтобы включить Google Cloud Pub/Sub, откройте левую боковую панель навигации, найдите Pub/Sub и щелкните по нему. Нажмите «Включить API» , чтобы включить Google Cloud Pub/Sub в вашем проекте.

Облачное хранилище данных Google

Google Cloud Datastore — это масштабируемая и распределенная бессерверная база данных.

Чтобы включить Google Cloud Datastore, на левой боковой панели навигации найдите Datastore и щелкните его. Нажмите «Выбрать режим хранилища данных» на новой странице.

98012c91fd4080d4.png

Для этой лабораторной работы вы можете использовать любое расположение базы данных. Нажмите « Создать базу данных» , чтобы включить хранилище данных Google Cloud; это может занять несколько минут.

Облачное видение Google

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

См. инструкции ниже для получения информации о том, как включить Google Cloud Vision API.

Включение API Gmail, API Google Таблиц и API Google Cloud Vision.

Еще раз откройте левую боковую панель навигации и найдите API и службы . Нажмите «Библиотека» . В поле «Поиск API и служб» введите Gmail . В результатах поиска выберите Gmail API и нажмите «Включить» .

Вернитесь на страницу библиотеки API. Найдите Google Sheets API и включите его.

Повторите процесс. Найдите Cloud Vision API и включите его.

Откройте Google Cloud Shell.

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

Чтобы открыть Google Cloud Shell, нажмите кнопку «Активировать Cloud Shell» на верхней синей горизонтальной панели:

fd5c2925ca9cdfdd.png

Внизу экрана появится новая панель:

34f498402e910802.png

Нажмите кнопку «Запустить редактор кода» , чтобы запустить редактор кода Cloud Shell:

10f8631ef48bed22.png

Редактор кода Cloud Shell откроется в новом окне.

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

Запустите команду ниже в Cloud Shell, чтобы клонировать проект:

git clone https://github.com/googlecodelabs/gcf-gmail-codelab.git

cd gcf-gmail-codelab

Вы должны увидеть новую папку gcf-gmail-codelab в редакторе кода Cloud Shell.

3. Архитектурный обзор

Ниже приведен рабочий процесс этой лабораторной работы:

79c5d3e43f674b33.png

  1. Пользователь настраивает push-уведомления Gmail: каждый раз, когда в папку «Входящие» поступает новое сообщение, Gmail отправляет уведомление в Cloud Pub/Sub.
  2. Cloud Pub/Sub доставляет уведомление о новом сообщении в Google Cloud Functions.
  3. При получении уведомления о новом сообщении экземпляр Cloud Functions подключается к Gmail и получает новое сообщение.
  4. Если к сообщению есть изображение в качестве вложения, экземпляр Cloud Functions вызывает API Cloud Vision для анализа вложения.
  5. Экземпляр Cloud Functions обновляет выбранную вами таблицу Google, указывая, кто отправляет сообщение и где загрузить вложение.

4. Разрешите доступ к Gmail.

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

Зарегистрируйте клиент OAuth

В левом навигационном меню Google Cloud Console найдите API и службы . Нажмите «Экран согласия OAuth» .

91b2a3bac30bb2c5.png

Введите имя в поле Имя приложения , например GCF + Gmail Codelab . Остальные настройки оставьте нетронутыми, прокрутите страницу вниз и нажмите «Сохранить» .

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

Перейдите на вкладку «Учетные данные» . Нажмите «Создать учетные данные» и выберите идентификатор клиента OAuth . Выберите тип веб-приложения , дайте ему имя (здесь вы можете снова использовать GCF + Gmail Codelab ) и нажмите «Создать». Поля «Ограничения» пока оставьте пустыми.

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

1160d8027ea52d90.png

Выполните процедуру авторизации

В примере кода auth/index.js указывает две облачные функции, auth_init и auth_callback , которые работают вместе для выполнения процесса авторизации, используя идентификатор клиента и только что созданный секрет клиента.

Чтобы проверить код, откройте auth/index.js в редакторе кода Cloud Shell.

Процесс авторизации возвращает два типа токенов: токены доступа и токены обновления .

  • Токены доступа — это кратковременные доказательства личности, которые предоставляют любому, кто ими владеет, ограниченный доступ к вашим данным; auth_callback сохраняет их в Cloud Datastore.
  • Токены обновления используются для получения новых токенов доступа и имеют значительно более длительный срок действия.

Обычно они либо зашифрованы, либо хранятся отдельно от токенов доступа.

Отредактируйте auth/env_vars.yaml в редакторе кода Cloud Shell. Замените YOUR-GOOGLE-CLIENT-ID и YOUR-GOOGLE-CLIENT-SECRET своими собственными значениями. Для получения дополнительной информации см. предыдущий шаг. Оставьте пока значения YOUR-GOOGLE-CLIENT-CALLBACK-URL и YOUR-PUBSUB-TOPIC без изменений.

a2b4853c39a78bc6.png

После редактирования auth/env_vars.yaml выполните следующую команду в Cloud Shell, чтобы развернуть облачные функции:

cd ~
cd gcf-gmail-codelab/auth

# Deploy Cloud Function auth_init
gcloud functions deploy auth_init --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml

# Deploy Cloud Function auth_callback
gcloud functions deploy auth_callback --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml

Развертывание облачных функций может занять несколько минут. При появлении запроса дайте Cloud SDK разрешение на установку бета-команд.

Затем перейдите в Google Cloud Console и нажмите «Облачные функции» в левом навигационном меню. Нажмите auth_callback в списке облачных функций и переключитесь на вкладку «Триггер» .

cb094bd341f9b299.png

45678a327c80e0f1.png

Скопируйте URL-адрес на странице. Вернитесь на страницу облачных функций, нажмите auth_init в списке облачных функций. На вкладке «Общие» нажмите « Изменить» . Нажмите «Переменные среды, сеть, тайм-ауты и т. д.» и замените значение GOOGLE_CALLBACK_URL на только что скопированный URL-адрес.

939ca3bd38047282.png

Нажмите «Развернуть» , чтобы применить изменения. Повторите процесс и также обновите auth_callback .

Наконец, откройте левое меню навигации и выберите API и услуги > Проверка домена . Чтобы добавить авторизованный домен, нажмите «Добавить домен» . Например, если URL-адрес, который вы скопировали ранее, выглядит так

https://us-central1-my-project.cloudfunctions.net/auth_callback

Вам следует добавить следующее в качестве авторизованного домена:

us-central1-my-project.cloudfunctions.net

Нажмите Добавить домен для подтверждения.

4348748f232ceb87.png

Вернитесь на страницу учетных данных . Щелкните имя вашего клиента OAuth и добавьте скопированный URL-адрес в качестве URI авторизованного перенаправления . Нажмите Enter для подтверждения.

Удалите часть /auth_callback из URL-адреса и добавьте остальную часть в качестве авторизованного источника Javascript . Например, если ваш URL-адрес выглядит так

https://us-central1-my-project.cloudfunctions.net/auth_callback

В качестве источника необходимо добавить следующее:

https://us-central1-my-project.cloudfunctions.net/

159bad719432582c.png

Нажмите Enter для подтверждения и нажмите Сохранить , чтобы применить изменения.

5. Настройте push-уведомления Gmail.

Если процесс авторизации завершится успешно, auth_callback автоматически вызовет API Gmail для настройки push-уведомлений.

Чтобы получать push-уведомления Gmail, вам необходимо создать тему Pub/Sub. Любой подписчик темы будет автоматически получать уведомления о входящих сообщениях по мере их поступления из Gmail.

Чтобы создать тему Pub/Sub, перейдите в Google Cloud Console и нажмите Pub/Sub > Темы в левом навигационном меню. Нажмите Создать тему . Введите название темы, например gmail-watch , и нажмите «Создать» . Кроме того, вы должны предоставить Gmail разрешение на отправку сообщений в вашу тему Pub/Sub: щелкните контекстное меню только что созданной темы (три вертикальные точки) и выберите «Разрешения» ; нажмите «Добавить участников» , укажите gmail-api-push@system.gserviceaccount.com в качестве нового участника и присвойте ему роль Pub/Sub > Pub/Sub Publisher ; наконец, нажмите «Сохранить» , чтобы применить изменения.

Обновите облачную функцию auth_callback чтобы указать, какую тему Pub/Sub использовать. Нажмите «Облачные функции» в левом меню навигации и выберите auth_callback в списке «Облачные функции». На вкладке «Общие» нажмите « Изменить» . Нажмите «Дополнительно» и замените значение PUBSUB_TOPIC на имя только что созданной темы Pub/Sub. Нажмите «Сохранить» , чтобы применить изменения.

Теперь вы готовы авторизоваться и настроить push-уведомления Gmail. Подождите, пока новые изменения будут завершены, затем вернитесь на страницу «Облачные функции» , выберите auth_init в списке «Облачные функции» и переключитесь на вкладку «Триггер» . Нажмите на URL-адрес, и вы будете перенаправлены на страницу «Войти через Google» :

348ab0a7e0c9cd03.png

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

cfdad62fd02de004.png

Нажмите Разрешить , чтобы разрешить доступ. auth_callback завершит процесс авторизации, сохранит токены доступа и настроит для вас push-уведомления Gmail. После завершения этого процесса вы должны увидеть сообщение Successfully set up Gmail push notifications в вашем браузере.

В этой лаборатории кода используется пакет @google-cloud/express-oauth2-handlers для автоматизации рабочего процесса авторизации. Дополнительную информацию смотрите в его репозитории на GitHub .

6. Обработка входящих сообщений

Как мы упоминали ранее, любой подписчик на созданную вами тему Pub/Sub будет получать уведомления, когда в ваш почтовый ящик поступают новые сообщения. pubsub/index.js определяет облачную функцию watchGmailMessages , которая после развертывания в качестве подписчика на тему будет читать новые сообщения, классифицировать прикрепленные изображения и экспортировать эти категории в Google Sheet.

Чтобы проверить код, откройте pubsub/index.js в редакторе кода Cloud Shell.

Получение сообщений

Push-уведомление Gmail включает адрес электронной почты, с которым связано уведомление, и идентификатор истории. Для простоты в этой кодовой лаборатории вы просто запрашиваете у Gmail API последнее сообщение при поступлении push-уведомления; для лучшего результата вместо этого используйте идентификатор истории для поиска сообщений .

// Look up the most recent message.
const listMessagesRes = await gmail.users.messages.list({
  userId: email,
  maxResults: 1
});
const messageId = listMessagesRes.messages[0].id;

// Get the message using the message ID.
const message = await gmail.users.messages.get({
  userId: email,
  id: messageId
});

return message;

Анализ вложенных изображений

Если к сообщению прикреплено изображение, watchGmailMessages вызовет API Cloud Vision для аннотации к изображению. В этой лаборатории кода вы попросите Cloud Vision API классифицировать изображение и вернуть несколько тегов изображения; например, если предоставлено изображение голубого неба, API Cloud Vision может вернуть теги blue , sky и natural .

watchGmailMessages использует библиотеку API Cloud Vision для Node.js для вызова API Cloud Vision:

// Tag the attachment using Cloud Vision API
const analyzeAttachment = async (data, filename) => {
  var topLabels = ['', '', ''];
  if (filename.endsWith('.png') || filename.endsWith('.jpg')) {
    const [analysis] = await visionClient.labelDetection({
      image: {
        content: Buffer.from(data, 'base64')
      }
    });
    const labels = analysis.labelAnnotations;
    topLabels = labels.map(x => x.description).slice(0, 3);
  }

  return topLabels;
};

Обновить Google Таблицу

watchGmailMessages экспортирует результаты этого анализа в Google Sheet. Он включает имя отправителя, имя вложения и теги вложений изображений (если есть).

Сначала создайте Google Sheet. Откройте Google Sheets и нажмите « Пустой шаблон» в разделе «Начать новую таблицу» . Скопируйте идентификатор вашего листа. Например, если адрес в вашем браузере выглядит так:

https://docs.google.com/spreadsheets/d/abcdefghij01234567890/edit#gid=0

Идентификатор вашей таблицы — abcdefghij01234567890 . В редакторе кода Cloud Shell обновите gcf-gmail-codelab/pubsub/env_vars.yaml и замените YOUR-GOOGLE-SHEET-ID своим собственным значением.

watchGmailMessages подключается к Google Sheets API для добавления информации: 

const updateReferenceSheet = async (from, filename, topLabels) => {
  await googleSheets.spreadsheets.values.append({
    spreadsheetId: SHEET,
    range: SHEET_RANGE,
    valueInputOption: 'USER_ENTERED',
    requestBody: {
      range: SHEET_RANGE,
      majorDimension: 'ROWS',
      values: [
        [from, filename].concat(topLabels)
      ]
    }
  });
};

Последний шаг

В редакторе кода Cloud Shell откройте gcf-gmail-codelab/pubsub/env_vars.yaml и замените YOUR-GOOGLE-CLIENT-ID , YOUR-GOOGLE-CLIENT-SECRET и YOUR-GOOGLE-CALLBACK-URL своими собственными значениями. Вы можете найти эти значения в Google Cloud Console: откройте «Облачные функции» в левом навигационном меню, выберите auth_init в списке облачных функций и найдите раздел «Переменные среды» .

Развертывание кода

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

cd ~

cd gcf-gmail-codelab/pubsub

gcloud functions deploy watchGmailMessages --runtime=nodejs8 --trigger-topic=gmail-watch --env-vars-file=env_vars.yaml

Если вы назвали свою тему Cloud Pub/Sub иначе, чем gmail-watch , замените gmail-watch в приведенной выше команде названием вашей темы. Развертывание облачной функции может занять несколько секунд.

7. Попробуйте

Поздравляем, все готово! Отправьте себе электронное письмо с вложением изображения. Через несколько секунд вы увидите созданный вами Google Sheet автоматически обновится с предоставленной вами информацией.