Интеграция с Google BigQuery

Требуется помощь разработчика

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

Интеграция с Google BigQuery передает выбранные события сообщений Pushwoosh в ваш набор данных BigQuery. Используйте ее для анализа событий жизненного цикла push-уведомлений, email- и SMS-сообщений в BigQuery, создания пользовательских отчетов или подключения данных к вашим последующим аналитическим процессам.

Обзор интеграции

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

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

1. Используйте проект Google Cloud с включенным биллингом. Поддерживаются кредиты Free Trial. BigQuery Sandbox недостаточно, так как Storage Write API требует включенного биллинга.

2. Убедитесь, что у вас есть платный аккаунт Pushwoosh.

Цены

Вы платите Google напрямую за использование BigQuery. Pushwoosh не взимает плату за саму интеграцию.

Актуальные тарифы, бесплатные уровни и региональные особенности см. в разделе Цены на BigQuery.

Затраты могут включать:

• Прием данных: Pushwoosh передает события с помощью BigQuery Storage Write API.
• Хранение: BigQuery хранит строки, записанные в вашу целевую таблицу.
• Запросы: BigQuery взимает плату за запросы в соответствии с выбранной вами моделью ценообразования.

Тип интеграции

Источник: Данные отправляются из Pushwoosh в ваш набор данных BigQuery.

Поддерживаемые платформы

Pushwoosh передает события с платформ iOS, Android, Huawei, Chrome, Safari, Firefox и Web.

Синхронизируемые сущности

Выбранные события жизненного цикла push-уведомлений, email- и SMS-сообщений передаются в BigQuery. Pushwoosh записывает одну строку для каждого выбранного события в целевую таблицу.

Сценарии использования

• Аналитика сообщений в режиме, близком к реальному времени: анализируйте события жизненного цикла push-уведомлений, email- и SMS-сообщений в BigQuery вскоре после их обработки в Pushwoosh.
• Пользовательская отчетность: создавайте отчеты BigQuery для выбранных типов событий, приложений, кампаний и идентификаторов сообщений.
• Последующие рабочие процессы с данными: подключайте данные о событиях Pushwoosh к вашим процессам аналитики, отчетности или обработки данных.

Как работает интеграция

После сохранения конфигурации Pushwoosh начинает передавать выбранные события сообщений в вашу таблицу BigQuery в режиме, близком к реальному времени. Для каждого события сообщения, проходящего через Pushwoosh, система проверяет, выбран ли тип события в вашей конфигурации.

Если да, Pushwoosh добавляет новую строку в вашу целевую таблицу. Если таблица еще не существует, Pushwoosh создает ее автоматически, используя схему, описанную ниже. События обычно появляются в BigQuery в течение 30 секунд после обработки в Pushwoosh.

Настройка интеграции в Google Cloud

Выберите проект Google Cloud

Войдите в Google Cloud Console, затем выберите или создайте проект, которому будет принадлежать набор данных BigQuery.

Совет

Запишите ID проекта. Используйте короткий идентификатор, например my-company-12345, а не читаемое название проекта.

Включите необходимые API

В Google Cloud Console перейдите в APIs & Services → Library и включите следующие API:

• BigQuery API
• BigQuery Storage API

Pushwoosh использует эти API для создания целевой таблицы и потоковой передачи событий в BigQuery.

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

Pushwoosh использует сервисный аккаунт для записи событий в ваш набор данных BigQuery.

1. Перейдите в IAM & Admin → Service Accounts.

2. Нажмите Create service account.

3. В поле Service account name введите имя, например, pushwoosh-bigquery.

   Google Cloud автоматически сгенерирует Service account ID из имени.

   

4. Нажмите Create and continue.

Предоставьте роли IAM

1. Предоставьте сервисному аккаунту следующие роли IAM:

   • BigQuery Data Editor: позволяет Pushwoosh создавать таблицу и добавлять строки.
   • BigQuery User: позволяет Pushwoosh использовать Storage Write API.
   

Примечание

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

2. Нажмите Continue.

3. Нажмите Done.

Создайте JSON-ключ

Pushwoosh использует JSON-ключ для аутентификации в качестве сервисного аккаунта.

1. Откройте созданный вами сервисный аккаунт.

2. Перейдите в Keys → Add key → Create new key.

3. Выберите JSON.

Google Cloud загрузит файл JSON-ключа на ваш компьютер.

Осторожно

Храните файл JSON-ключа в безопасности. Любой, у кого есть этот файл, сможет записывать данные в ваш проект BigQuery. Не добавляйте его в git и не делитесь им в чатах. Pushwoosh хранит ключ в зашифрованном виде и не отображает его в интерфейсе после загрузки.

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

Набор данных — это место, где Pushwoosh будет хранить таблицу с потоковыми событиями.

1. В Google Cloud Console откройте BigQuery.

2. В Explorer выберите проект, который вы подготовили для интеграции.

3. Нажмите Create dataset.

4. В поле Dataset ID введите ID набора данных, например pushwoosh_data.

5. В поле Data location выберите регион набора данных.

6. Нажмите Create dataset.

Настройка интеграции в Pushwoosh

1. В вашем аккаунте Pushwoosh перейдите в Settings → 3rd Party Integrations для приложения, которое вы хотите подключить.

2. Найдите Google BigQuery в списке доступных сервисов и нажмите Configure.

3. Заполните поля конфигурации.

• GCP Project ID: введите ID проекта из Google Cloud, например my-company-12345.
• Service Account JSON: вставьте полное содержимое файла JSON-ключа, который вы скачали из Google Cloud.
• Dataset ID: как только поля GCP Project ID и Service Account JSON будут заполнены, Pushwoosh получит список наборов данных, к которым имеет доступ ваш сервисный аккаунт. Выберите целевой набор данных. Если выпадающий список пуст, проверьте, имеет ли сервисный аккаунт доступ и существует ли набор данных в указанном вами проекте.
• Dataset region: выберите регион вашего набора данных BigQuery.
• Table name: оставьте пустым, чтобы использовать таблицу по умолчанию pushwoosh_events. Pushwoosh создаст таблицу со схемой, описанной ниже.
• Events: выберите события, которые вы хотите передавать. Вы можете изменить этот список позже.
• Stream events to BigQuery: включите этот переключатель. Выключите его, чтобы приостановить передачу данных, не удаляя конфигурацию.

4. Нажмите Test connection.

Pushwoosh проверит учетные данные в BigQuery, не записывая данные.

Вы можете увидеть один из следующих статусов подключения:

• Connection successful: учетные данные работают, и сервисный аккаунт имеет доступ к набору данных.
• auth_failed: JSON-ключ недействителен или отозван.
• dataset_not_found: ID набора данных указан неверно или сервисный аккаунт не имеет к нему доступа.
• missing_permission: у сервисного аккаунта отсутствует одна из требуемых ролей.

5. Нажмите Apply.

Pushwoosh сохранит конфигурацию и начнет использовать ее примерно через 30 секунд. После этого выбранные события начнут передаваться в BigQuery.

Проверка интеграции

1. Отправьте тестовое push-уведомление или вызовите другое сообщение, которое генерирует один из выбранных вами типов событий.

2. Подождите около 30 секунд.

3. Откройте BigQuery Studio.

4. Перейдите в свой проект, затем откройте настроенный вами набор данных и целевую таблицу. Если вы оставили поле Table name пустым, откройте pushwoosh_events.

5. Нажмите Preview.

Вы должны увидеть строку события в таблице.

Схема таблицы

Pushwoosh записывает каждое выбранное событие как отдельную строку в целевой таблице. Чтобы ускорить и упростить фильтрацию запросов, таблица партиционирована по дням с использованием timestamp и кластеризована по app_id и event_kind.

Название поля	Тип	Описание
event_kind	STRING	Тип события Pushwoosh, например Push Sent или Email Opened.
message_id	STRING	Код сообщения Pushwoosh, такой как идентификатор кампании или сообщения.
device_id	STRING	Аппаратный ID (HWID) устройства в Pushwoosh, с которого произошло событие.
user_id	STRING	Ваш внешний User ID, если он известен. Пусто для анонимных устройств.
timestamp	TIMESTAMP	Время события в UTC.
app_id	STRING	Код приложения Pushwoosh.
platform	STRING	Исходная платформа, например ios, android или web.
properties	JSON	Дополнительные поля события. Используйте JSON_VALUE для запроса полей, как показано ниже.

Запрос свойств

Столбец properties хранит дополнительные поля событий в формате JSON. Используйте JSON_VALUE для извлечения отдельных полей в ваших запросах.

Например, чтобы увидеть, какие кампании привели к наибольшему количеству открытий за последние 7 дней, нажмите +, чтобы создать новый запрос, вставьте SQL-код ниже и нажмите Run.

SELECT
  event_kind,
  JSON_VALUE(properties, '$.campaign_id') AS campaign_id,
  COUNT(*) AS events
FROM `your-project.your_dataset.pushwoosh_events`
WHERE event_kind = 'Push Opened'
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
GROUP BY 1, 2
ORDER BY events DESC

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

SELECT
  event_kind,
  COUNT(*) AS events
FROM `your-project.your_dataset.pushwoosh_events`
WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
GROUP BY event_kind
ORDER BY events DESC

Обновление интеграции

Ротация ключа сервисного аккаунта

1. В Google Cloud Console перейдите в IAM & Admin → Service Accounts.

2. Откройте ваш сервисный аккаунт.

3. Перейдите в Keys и создайте новый JSON-ключ.

4. Оставьте старый ключ активным, пока не убедитесь, что новый ключ работает.

5. В Pushwoosh откройте модальное окно конфигурации Google BigQuery.

6. Вставьте новый JSON в поле Service Account JSON.

7. Нажмите Apply.

Pushwoosh проверит новый ключ, заменит сохраненные учетные данные и начнет использовать его после следующей перезагрузки конфигурации, что займет около 30 секунд.

После того как вы убедитесь, что события по-прежнему передаются, удалите старый ключ в Google Cloud Console.

Изменение целевого набора данных или таблицы

1. В Pushwoosh перейдите в Settings → 3rd Party Integrations.

2. Откройте настройки Google BigQuery.

3. Выберите другой набор данных или введите новое имя таблицы.

4. Нажмите Apply.

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

Чтобы сохранить существующий ключ сервисного аккаунта при обновлении других настроек, оставьте поле Service Account JSON пустым перед нажатием Apply.

Устранение неполадок

Проблема	Что проверить
Тестовое подключение не удалось с ошибкой auth_failed	JSON-файл сервисного аккаунта имеет неверный формат или ключ был отозван в Google Cloud. Создайте новый ключ и снова вставьте полный JSON-файл. Файл начинается с {, заканчивается } и содержит блок private_key.
Тестовое подключение не удалось с ошибкой dataset_not_found	ID набора данных указан с ошибкой или не существует в указанном вами проекте. ID наборов данных чувствительны к регистру. Выберите набор данных из выпадающего списка, чтобы избежать опечаток.
Тестовое подключение не удалось с ошибкой missing_permission	У сервисного аккаунта отсутствуют роли BigQuery Data Editor или BigQuery User. Предоставьте обе роли на уровне проекта или на уровне набора данных для более ограниченного доступа.
Тестовое подключение проходит успешно, но в BigQuery не появляются строки	Подождите не менее 30 секунд. Убедитесь, что тип события, которое вы отправляете, выбран в разделе События. Например, если выбрано только Push Opened и никто не открывает push-уведомление, строки не появятся.
Конфигурация выглядит правильно, но в модальном окне поля пустые	Перезагрузите страницу. Конфигурация запрашивается при каждом открытии модального окна и кэшируется базовой службой на 30 секунд. Если вы только что сохранили настройки, подождите немного и откройте модальное окно снова.

Примечание

Pushwoosh записывает события Push Sent, Email Sent и SMS Sent независимо от статуса доставки, чтобы агрегированные данные в BigQuery соответствовали канонической статистике Pushwoosh. Для событий Delivered, Opened, Bounced и Unsubscribed Pushwoosh записывает только успешные события.

FAQ

Могу ли я использовать бесплатный аккаунт Google Cloud?

Да, если в проекте включен биллинг. Кредитов Free Trial достаточно для работы этой интеграции при типичных объемах в течение всего пробного периода. BigQuery Sandbox без биллинга не будет работать, так как Storage Write API требует включенного биллинга.

Видит ли Pushwoosh мои данные в BigQuery?

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

Могу ли я экспортировать данные в несколько наборов данных BigQuery?

Для каждого приложения поддерживается одно назначение. Если вам нужны те же события в двух наборах данных, настройте в своем проекте запланированный запрос BigQuery для копирования данных из pushwoosh_events в другую таблицу.

Могу ли я изменить схему таблицы?

Схема фиксирована для всех клиентов. Если вам нужны дополнительные столбцы, извлекайте их из JSON-поля properties в своих собственных представлениях или запланированных запросах.

Что произойдет, если я временно отключу интеграцию?

Выключите переключатель Stream events to BigQuery и нажмите Apply. Pushwoosh прекратит добавление событий для этого приложения примерно через 30 секунд.

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

Как полностью удалить интеграцию?

Свяжитесь с support@pushwoosh.com, чтобы удалить конфигурацию интеграции. Набор данных и уже записанные в BigQuery строки останутся в вашем аккаунте Google Cloud.

Есть ли гарантии доставки?

Интеграция использует доставку “at-least-once” (как минимум один раз). В нормальных условиях дубликаты редки. Перезапуск процесса между добавлением и фиксацией может привести к небольшому количеству дублирующихся строк. Выполняйте дедупликацию в SQL, если ваш последующий конвейер требует результатов “exactly-once” (ровно один раз).

Почему нет события Push Clicked?

В настоящее время Pushwoosh предоставляет в этой интеграции события Push Sent, Push Delivered и Push Opened для push-уведомлений. Отдельного шага для клика по push-уведомлению нет. Для email и SMS есть свои события жизненного цикла.