BigQuery: вставка строки

Используйте элемент BigQuery: вставка строки, чтобы передать одну строку в таблицу BigQuery из шага Journey через API потоковой вставки. Подобно элементу Google Sheets: добавить строку, этот элемент аутентифицируется через аккаунт Google, подключенный один раз для всей учетной записи. В самом элементе нет поля для токена.

Типичные случаи использования:

• Заполнение таблицы отчетов: вставка строки для каждого достигнутого шага Journey для последующего использования в дашборде или запланированном запросе.
• Запись событий в реальном времени: потоковая передача необработанных данных Journey в BigQuery вместо ожидания пакетного экспорта.
• Объединение с существующими данными: вставка значения устройства или Tag, которое таблицы BigQuery могут использовать для объединения с вашими собственными наборами данных.

Перед началом работы

Подключите аккаунт Google в разделе Настройки > Сторонние интеграции > Google. Это то же подключение, которое использует элемент Google Sheets: добавить строку. После подключения Google установите интеграцию, чтобы элемент появился в конструкторе Journey.

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

Осторожно

Если вы подключили аккаунт Google до добавления поддержки BigQuery, переподключите его. Подключение сохраняет те разрешения, которые были ему предоставлены, поэтому старое подключение может записывать данные в Sheets, но не в BigQuery, и элемент будет завершаться с ошибкой 403.

Также на стороне Google Cloud должны быть выполнены два условия, иначе запрос завершится ошибкой:

• Набор данных и таблица уже должны существовать. Этот элемент только записывает строки. Он никогда не создает таблицы.
• Подключенный аккаунт Google должен иметь роль BigQuery Data Editor (или любую роль, предоставляющую право bigquery.tables.updateData) для этого набора данных.

Настройка элемента

1. Перетащите элемент BigQuery: вставка строки из раздела Интеграции на левой панели на холст.
2. Дважды щелкните по элементу и введите Имя шага.
3. В поле ID проекта введите ID проекта Google Cloud. Используйте именно ID, а не отображаемое имя, например my-analytics-prod.

4. В поле Набор данных введите имя набора данных.

5. В поле Таблица введите имя таблицы.

6. В разделе Столбцы добавьте по одной строке для каждого столбца BigQuery, в который нужно записать данные. Введите имя столбца и значение. Имена не должны быть пустыми и должны быть уникальными. Каждый указанный вами столбец должен существовать в схеме таблицы. Значением может быть фиксированный текст или макрос traveler, например {{tag:Name}} — те же макросы, что и в теле Webhook. Или нажмите Вставить динамическое значение, чтобы выбрать атрибут, созданный на предыдущем шаге этого Journey, например, ответ LLM или сопоставленное значение Webhook.

Пример

Если для Набора данных установлено значение marketing, а для Таблицы — journey_events, то установка в Столбцах значения device_id с ID устройства traveler ({{device:hwid}}) запишет строку в столбец device_id этой таблицы.

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

Ответ

Traveler переходит к следующему шагу, который вы подключите на холсте.

Атрибуты после выполнения шага

Этот элемент не возвращает атрибут в случае успеха. Если BigQuery отклоняет строку, ошибка записывается в bigquery_insert_error. См. раздел Сбои и непредвиденные ответы.

Сбои и непредвиденные ответы

Откройте Журнал вызовов в окне настроек элемента и проверьте ответ:

• 401 — подключение Google отсутствует или истек срок его действия. Переподключите его в разделе Настройки > Сторонние интеграции.
• 403 с accessDenied: Streaming insert is not allowed in the free tier — к проекту не привязан платежный аккаунт. Потоковые вставки, которые использует этот элемент, не входят в бесплатный уровень (песочницу) BigQuery. Включите биллинг для проекта, и тот же запрос будет выполнен успешно.
• 403 с accessDenied или insufficientPermissions — подключение было предоставлено до добавления поддержки BigQuery (переподключите его), или у аккаунта Google нет доступа на запись в набор данных.
• 403 с quotaExceeded или rateLimitExceeded — исчерпана квота проекта на потоковые вставки. Переподключение не поможет. Journey должен отправлять меньше данных, или необходимо увеличить квоту в Google Cloud.
• 404 — имя проекта, набора данных или таблицы ни с чем не совпадает.

Осторожно

Строка, отклоненная BigQuery (из-за неизвестного столбца или значения, не соответствующего типу столбца), возвращается с кодом 200 и телом ответа insertErrors, а не со статусом ошибки. Traveler продолжает движение, как будто запись прошла успешно. Первое такое сообщение записывается в атрибут traveler bigquery_insert_error. Элемент Разделение по условию не может напрямую ветвиться по этому атрибуту, поэтому сначала сохраните его в Tag с помощью элемента Обновить профиль пользователя, а затем настройте ветвление по этому Tag. Полное тело ответа находится в Журнале вызовов.

Неудачный запрос удаляет traveler из Journey. См. раздел Ошибки и неудачные запросы.

Пример сценария: заполнение таблицы отчетов BigQuery

Команда хочет, чтобы активность Journey попадала в тот же набор данных BigQuery, который уже запрашивают их запланированные отчеты.

1. Добавьте элемент BigQuery: вставка строки сразу после шага, который вы хотите записать. Установите для Набора данных значение marketing, а для Таблицы — journey_events. В Столбцах установите device_id в {{device:hwid}}.
2. Нажмите Сохранить.

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