Связаться с намиПодключиться

Передача событий Yandex Cloud Postbox в Yandex Data Streams и их анализ с помощью Yandex DataLens

Статья создана
Обновлена 18 ноября 2024 г.

Важно

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

В этом руководстве вы настроите передачу событий Yandex Cloud Postbox в Yandex Data Streams и визуализацию этих событий с помощью Yandex DataLens для последующего анализа. Источник событий — отправка электронных писем.

Вы сможете реализовать все представленные решения в консоли управления Yandex Cloud без навыков разработки. Для обработки и хранения данных будут использоваться сервисы Yandex Cloud Functions и Yandex Managed Service for YDB.

Чтобы настроить передачу событий и их визуализацию:

  1. Подготовьте облако к работе.
  2. Настройте базу данных Managed Service for YDB.
  3. Создайте поток данных Data Streams.
  4. Подготовьте ресурсы Yandex Cloud Postbox и Cloud DNS.
  5. Подготовьте ресурсы Cloud Functions.
  6. Отправьте письма.
  7. Настройте визуализацию в DataLens.

Если созданные ресурсы вам больше не нужны, удалите их.

Подготовьте облако к работе

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

  1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
  2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

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

Подробнее об облаках и каталогах.

В стоимость поддержки инфраструктуры входят:

Создайте сервисный аккаунт

  1. В консоли управления выберите нужный каталог.
  2. В списке сервисов выберите Identity and Access Management.
  3. Нажмите кнопку Создать сервисный аккаунт.
  4. Введите имя сервисного аккаунта: yds-functions.
  5. Нажмите кнопку Добавить роль и выберите роли yds.editor и functions.functionInvoker.
  6. Нажмите кнопку Создать.

Настройте базу данных Managed Service for YDB

В качестве хранилища событий может использоваться любая подходящая для задач аналитики СУБД. В данном руководстве используется бессерверная база данных Managed Service for YDB. Для других СУБД SQL-запрос создания таблицы и код функции загрузки событий в нее могут отличаться.

Создайте базу данных

  1. В консоли управления выберите нужный каталог.
  2. Выберите сервис Managed Service for YDB.
  3. Нажмите кнопку Создать базу данных.
  4. Укажите Имя БД postbox-events-ydb.
  5. В блоке Тип базы данных выберите Serverless.
  6. Нажмите кнопку Создать базу данных.

Дождитесь запуска БД. В процессе создания БД будет иметь статус Provisioning, а когда станет готова к использованию, статус изменится на Running.

Создайте таблицу

  1. На странице Базы данных выберите БД postbox-events-ydb.

  2. Чтобы открыть корневую директорию БД, перейдите на вкладку Навигация.

  3. Чтобы создать запрос к БД, в правом верхнем углу нажмите кнопку Новый SQL-запрос. Откроется страница Запрос.

  4. В поле Запрос введите:

    CREATE TABLE postbox_events
(
    saved_datetime Datetime NOT NULL,
    eventid String NOT NULL,
    eventtype String,
    mail_timestamp Timestamp,
    mail_messageid String,
    mail_ch_from String,
    mail_ch_to String, 
    mail_ch_messageid String,
    mail_ch_subject String,
    delivery_timestamp Timestamp,
    delivery_time_ms Uint64,
    delivery_recipients String,
    bounce_bounceType String,
    bounce_bounceSubType String,
    bounce_bouncedRecipients String,
    bounce_timestamp Timestamp,
    -- message Json,
    PRIMARY KEY (saved_datetime, eventid)
)

  5. Нажмите кнопку Выполнить.

    После выполнения запроса появится таблица postbox_events.

Создайте поток данных Data Streams

Создайте поток данных для регистрации событий.

  1. В консоли управления выберите сервис Data Streams.
  2. Нажмите кнопку Создать поток.
  3. Укажите базу данных postbox-events-ydb.
  4. Введите имя потока данных postbox-events-stream.
  5. Выберите режим тарификации По фактическому использованию.
  6. Нажмите кнопку Создать.

Дождитесь запуска потока данных. Когда поток станет готов к использованию, его статус изменится с Creating на Active.

Подготовьте ресурсы Yandex Cloud Postbox и Cloud DNS

Создайте адрес для отправки писем, пройдите проверку владения доменом и настройте конфигурацию для регистрации событий в Data Streams.

Создайте адрес

  1. На своем компьютере сгенерируйте ключ privatekey.pem для создания DKIM-подписи:

    openssl genrsa -out privatekey.pem 2048

  2. Создайте адрес:

    1. В консоли управления выберите сервис Cloud Postbox.
    2. Нажмите кнопку Создать адрес.
    3. В поле Домен укажите домен, с которого будете отправлять письма. Домен может быть любого уровня.
    4. В поле Селектор укажите селектор, например postbox. Указанный селектор должен использоваться только в одной ресурсной записи — той, которую необходимо создать при прохождении проверки владения доменом.
    5. В поле Приватный ключ скопируйте содержимое файла приватного ключа privatekey.pem.
    6. Нажмите кнопку Создать адрес.

Пройдите проверку владения доменом

Чтобы отправлять письма, подтвердите владение доменом. После создания адреса на его странице сформируются настройки DKIM-подписи. Их нужно указать в качестве значений ресурсной записи, которую необходимо добавить в вашу доменную зону. Вы можете добавить запись у вашего регистратора или в сервисе Yandex Cloud DNS, если вы делегировали ваш домен.

Пример создания ресурсной записи в Cloud DNS

  1. В консоли управления выберите каталог, в котором находятся адрес и ваша доменная зона.

  2. Выберите сервис Cloud DNS.

  3. Выберите вашу доменную зону.

  4. Нажмите кнопку Создать запись.

  5. В поле Имя укажите часть имени, сгенерированного при создании адреса, без домена в формате <селектор>._domainkey.. Например postbox._domainkey..

    Примечание

    Для других DNS-сервисов может потребоваться скопировать запись целиком. Итоговая запись должна иметь вид <селектор>._domainkey.<домен>., например postbox._domainkey.example.com..

  6. В списке Тип выберите TXT.

  7. В поле Значение скопируйте содержимое поля Значение из блока Подтверждение подписи. Обратите внимание, что значение записи нужно взять в кавычки, например:

    "v=DKIM1;h=sha256;k=rsa;p=M1B...aCA8"

  8. Нажмите кнопку Создать.

  9. Перейдите в сервис Cloud Postbox.

  10. Выберите созданный адрес.

  11. Нажмите кнопку Проверить адрес. Если запись верна, статус проверки на странице адреса изменится на Success.

Ответы DNS-сервера кешируются, поэтому возможны задержки при обновлении ресурсной записи.

Создайте конфигурацию

  1. В консоли управления выберите сервис Cloud Postbox.

  2. На панели слева выберите Конфигурации.

  3. Нажмите кнопку Создать конфигурацию.

  4. Введите имя конфигурации postbox-events-config.

  5. В блоке Подписки нажмите Добавить:

    1. Введите название подписки postbox-events-subscribe.
    2. Выберите поток данных postbox-events-stream.
    3. Включите опцию Включено, чтобы активировать подписку.

  6. Нажмите кнопку Создать конфигурацию.

Подготовьте ресурсы Cloud Functions

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

Получите код функции

Скачайте архив postbox-events.zip на свой компьютер. В архиве находятся файлы index.py и requirements.txt, содержащие код функции.

На своем компьютере выполните следующие операции:

  1. Склонируйте репозиторий с кодом функции:

    git clone https://github.com/yandex-cloud-examples/yc-postbox-events/blob/main/build/postbox-events.git

    Перейдите в директорию с репозиторием. В ней должны появиться файлы index.py и requirements.txt, содержащие код функции.

  2. Создайте архив с именем postbox-events.zip и добавьте в него файлы index.py и requirements.txt.

Получите реквизиты для подключения к БД

  1. Перейдите в консоль управления.

  2. Выберите каталог с вашей БД и перейдите в сервис Managed Service for YDB.

  3. Выберите базу данных, для которой нужно получить эндпоинт и путь.

    • Эндпоинт БД указан в блоке Соединение в первой части значения поля Эндпоинт (часть до вхождения /?database=):

      Например, эндпоинт для БД в режиме Serverless — grpcs://ydb.serverless.yandexcloud.net:2135.

    • Путь БД указан в блоке Соединение во второй части значения поля Эндпоинт (часть после вхождения /?database=).

      Пример пути БД: /ru-central1/b1gia87mbaom********/etnudu2n9ri3********.

Создайте функцию

Для создания функции вам потребуется код функции и реквизиты для подключения к БД.

  1. В консоли управления выберите сервис Cloud Functions.

  2. Создайте функцию:

    1. Нажмите кнопку Создать функцию.
    2. В поле Имя введите имя функции. Например, postbox-events-function.
    3. Нажмите кнопку Создать.

  3. Создайте версию функции:

    1. В открывшемся окне Редактор выберите Python 3.12.

    2. Отключите опцию Добавить файлы с примерами кода.

    3. Нажмите кнопку Продолжить.

    4. В поле Способ выберите ZIP-архив.

    5. Нажмите кнопку Прикрепить файл и выберите архив postbox-events.zip.

    6. В поле Точка входа укажите index.handler.

    7. В блоке Параметры укажите:

      • Таймаут, c — 10.

      • Память — 128 МБ.

      • Сервисный аккаунт — yds-functions.

      • Переменные окружения:

        Ключ Описание Пример значения
        YDB_DATABASE Путь БД /ru-central1/b1go123e9vjq********/etnu15kr22********
        YDB_ENDPOINT Эндпоинт БД grpcs://ydb.serverless.yandexcloud.net:2135
        YDB_TABLE Имя таблицы postbox_events

    8. Нажмите кнопку Сохранить изменения.

Создайте триггер

  1. В консоли управления выберите сервис Cloud Functions.
  2. На панели слева выберите Триггеры.
  3. Нажмите кнопку Создать триггер.
  4. В поле Имя введите имя триггера. Например, postbox-events-trigger.
  5. В поле Тип выберите Data Streams.
  6. В поле Запускаемый ресурс выберите Функция.
  7. В блоке Настройки Data Streams выберите поток данных postbox-events-stream и сервисный аккаунт yds-functions.
  8. В блоке Настройки функции выберите функцию postbox-events-function и сервисный аккаунт yds-functions.
  9. Нажмите кнопку Создать триггер.

Отправьте письма

  1. Создайте сервисный аккаунт postbox-user c ролью postbox.sender и статические ключи доступа.

  2. Отправьте несколько тестовых писем с использованием адреса, созданного ранее.

  3. Убедитесь, что письма отправлены — проверьте почту, на которую отправлены письма.

  4. Убедитесь, что данные поступают в сервисы:

    1. Проверьте поток данных:

      1. В консоли управления выберите сервис Data Streams.

      2. Выберите поток данных postbox-events-stream.

      3. Перейдите на вкладку Просмотр данных.

        На графиках должна отобразиться отправка писем.

    2. Проверьте БД:

      1. В консоли управления выберите сервис Managed Service for YDB.

      2. Выберите БД postbox-events-ydb.

      3. Перейдите на вкладку Навигация

      4. Выберите таблицу postbox_events.

        В таблице должны появиться записи. В некоторых столбцах может быть значение NULL — это зависит от типа уведомления, которое было получено от сервиса Yandex Cloud Postbox.

Настройте визуализацию в DataLens

Чтобы наблюдать за отправкой писем, настройте подключение, создайте датасет, чарты и дашборд.

Создайте подключение

  1. Перейдите на главную страницу DataLens.

  2. Нажмите кнопку Создать подключение.

  3. Выберите коннектор YDB.

  4. Укажите параметры подключения:

    • Облако и каталог — выберите каталог, в котором выполняете руководство.
    • Сервисный аккаунт — yds-functions.
    • База данных — postbox-events-ydb.
    • Время жизни кеша в секундах — По умолчанию.
    • Уровень доступа SQL запросов — Разрешить подзапросы из датасетов и запросы из чартов.

  5. Нажмите кнопку Создать подключение.

  6. Введите имя подключения postbox-events-connection и нажмите Создать.

Создайте датасет

  1. Перейдите на главную страницу DataLens.
  2. Нажмите кнопку Создать датасет.
  3. На панели слева нажмите Добавить.
  4. Выберите подключение postbox-events-connection.
  5. В меню слева выберите таблицу postbox-events и перетащите ее вправо.
  6. Нажмите кнопку Сохранить.
  7. В открывшемся окне укажите имя датасета postbox-events-dataset и нажмите Создать.

Создайте чарты

В качестве примера приведено создание чартов Количество событий по дням и Список событий. Аналогичным способом вы можете создать и другие чарты.

Количество событий по дням

  1. Перейдите на главную страницу DataLens.

  2. Нажмите кнопку Создать чарт.

  3. На панели слева нажмите Выберите датасет и выберите postbox-events-dataset.

  4. Выберите тип чарта Столбчатая диаграмма.

  5. Перетащите измерения:

    • delivery_timestamp в секцию X — по оси X будут расположены даты;
    • eventid в секцию Y — значение по оси Y будет соответствовать количеству событий;
    • eventtype в секцию Цвета — типы событий будут выделены на диаграмме разными цветами.

  6. Нажмите кнопку Сохранить.

  7. В открывшемся окне укажите имя чарта Количество событий по дням и нажмите Сохранить.

Список событий

  1. Перейдите на главную страницу DataLens.

  2. Нажмите кнопку Создать чарт.

  3. На панели слева нажмите Выберите датасет и выберите postbox-events-dataset.

  4. Выберите тип чарта Таблица.

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

    • saved_datetime — дата и время сохранения события;
    • eventid — тип события;
    • mail_ch_to — адрес получателя;
    • delivery_timestamp — дата и время доставки письма;
    • delivery_time_ms — время доставки в миллисекундах;
    • mail_ch_subject — тема письма;
    • bounce_bounceType — тип ошибки доставки;
    • bounce_bounceSubType — сообщение недоставки.

  6. Перетащите измерение delivery_timestamp в секцию Сортировка, чтобы отсортировать таблицу по времени доставки.

  7. Нажмите кнопку Сохранить.

  8. В открывшемся окне укажите имя чарта Список событий и нажмите Сохранить.

Создайте дашборд

  1. Перейдите на главную страницу DataLens.

  2. Нажмите кнопку Создать дашборд.

  3. Добавьте на дашборд чарты Количество событий по дням, Список событий и другие, которые вы создали ранее:

    1. На нижней панели нажмите Чарт.
    2. В открывшемся окне в поле Чарт нажмите кнопку Выбрать и выберите Количество событий по дням.
    3. Нажмите кнопку Добавить.
    4. Повторите действия — добавьте другие чарты.

  4. Измените размер и положение чартов.

  5. Нажмите кнопку Сохранить.

  6. В открывшемся окне введите название дашборда postbox-events-dashboard.

  7. Нажмите кнопку Создать.

В результате выполнения руководства вы сможете анализировать события на графиках и в таблицах.

Как удалить созданные ресурсы

Чтобы перестать платить за созданные ресурсы:

  1. Удалите триггер для вызова функции Cloud Functions.
  2. Удалите функцию Cloud Functions.
  3. Удалите базу данных Managed Service for YDB.
  4. Удалите поток данных Data Streams.
  5. Удалите адрес и конфигурацию Yandex Cloud Postbox.
Предыдущая
Хранение статического ключа доступа в секрете Yandex Lockbox
Следующая
Создание интерактивного serverless-приложения с использованием WebSocket