Рекомендации

При использовании Data Manager API следуйте приведенным ниже рекомендациям.

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

Независимо от того, отправляете ли вы участников аудитории или события с помощью UserData, включите как можно больше user_identifiers, в том числе несколько идентификаторов одного типа.

Например, если у пользователя несколько адресов электронной почты, добавьте отдельный элемент UserIdentifier для каждого из них. Аналогично, если у вас есть идентификаторы разных типов для одного пользователя, например адреса электронной почты, номера телефонов и адреса, добавьте отдельный элемент UserIdentifier для каждого идентификатора, не превышая максимальное количество идентификаторов.

Оптимизация запросов

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

Например, если вы хотите добавить в аудиторию 10 000 участников, добавьте их все в список audience_members в одном запросе IngestAudienceMembersRequest. Добавить всех 10 000 участников одним запросом эффективнее,чем отправлять отдельный запрос для каждого участника.

Отправка параллельных запросов

Чтобы сократить общее время, необходимое для передачи данных, отправляйте параллельные запросы к IngestionService. Рекомендуем отправлять не более 10 запросов одновременно, чтобы снизить вероятность превышения лимита запросов в минуту.

Вы можете отправлять параллельные запросы, даже если у них одинаковый параметр destinations.

Как подтвердить данные на стороне клиента

В Data Manager API используется модель быстрого отказа. Если хотя бы одна запись в запросе не проходит синхронную проверку, весь запрос отклоняется и ни одна из записей не обрабатывается. Кроме того, API проверяет запросы на нескольких уровнях, поэтому после исправления одной ошибки может появиться другая.

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

  • Удаляйте пустые значения перед хешированием. Перед вычислением хешей SHA-256 проверяйте, нет ли в полях email_address и phone_number пустых строк или строк, содержащих только пробелы. Хеширование пустой строки приводит к созданию действительного хеша, который проходит синтаксические проверки, но снижает коэффициент соответствия.

  • Удалять неполные составные объекты. Перед добавлением составных объектов в запись убедитесь, что в них заполнены все обязательные поля. Например, если в объекте AddressInfo отсутствует любое из четырех обязательных полей (given_name, family_name, region_code или postal_code), удалите весь идентификатор address, чтобы избежать ошибок REQUIRED_FIELD_MISSING.

  • Проверьте кодировку и поля с простым текстом. Убедитесь, что хешированные поля соответствуют объявленному значению encoding, а не отправляют необработанный простой текст. Также проверьте, что поля, которые должны оставаться простым текстом (например, mobile_ids), не хешируются.

  • Отфильтруйте временные метки, выходящие за допустимые пределы. Убедитесь, что временные метки не относятся к будущему и не выходят за пределы периода ретроспективного анализа конверсий.

    Если вы отправляете запросы в формате JSON, убедитесь, что строки временных меток соответствуют формату RFC 3339 со смещением часового пояса.

  • Очистка номеров телефонов. Перед хешированием убедитесь, что номера телефонов включают код страны и соответствуют формату E.164.

  • Удалите пустые или слишком большие записи. Ограничьте user_identifiers лимитом на запись (10 идентификаторов), удалите пустые специальные параметры и пропустите все записи, не содержащие действительных идентификаторов.

  • Проверьте требования к вариантам использования. Убедитесь, что каждое событие содержит все обязательные поля для целевого сервиса и варианта использования (например, transaction_id для онлайн-конверсий Google Рекламы). Полный список обязательных полей для каждого случая использования приведен в руководстве по отправке событий для вашего целевого сервиса в обзоре событий.

  • Используйте validateOnly для тестирования запросов. Отправляйте запросы с параметром validateOnly, для которого задано значение true, чтобы выявлять ошибки быстрого сбоя без добавления или удаления данных. Успешное выполнение запроса на проверку не гарантирует, что при асинхронной обработке не возникнет ошибок. Поэтому после отправки обычного запроса продолжайте проверять его статус и диагностические данные.

Подробные правила нормализации и хеширования приведены в статье Как форматировать пользовательские данные.

Как проверить статус запроса и данные диагностики

Запишите и соберите request_id из каждого объекта IngestAudienceMembersResponse или IngestEventsResponse и используйте идентификаторы запросов, чтобы проверить статус запроса и выполнить диагностику.

Как отслеживать квоты и получать оповещения о них

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

Развертывание рабочей версии

При переходе от локального тестирования к рабочим нагрузкам используйте Application Default Credentials с прикрепленным сервисным аккаунтом или Workload Identity Federation, чтобы безопасно выполнять аутентификацию без взаимодействия с пользователем.

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

Назад
Как анализировать ошибки API