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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Удалять неполные составные объекты. Перед добавлением составных объектов в запись убедитесь, что в них заполнены все обязательные поля. Например, если в объекте 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 для безопасной неинтерактивной аутентификации.

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