Миграция из файлов чтения сущностей

Файлы чтения объектов (ERF) — это JSON-представления объектов кампании партнера, которые по запросу генерируются ежедневно и становятся доступными через Google Cloud Storage .

Поддержка ERF прекращена в июне 2021 года . С 31 октября 2024 года поддержка ERF официально прекратится и больше не будет создаваться. Всем существующим пользователям файла чтения объекта рекомендуется перейти на API Display & Video 360 , чтобы продолжить получение ресурсов Display & Video 360.

В этом руководстве описывается, как перейти с файлов Entity Read Files на API Display & Video 360, выполнив следующие действия:

  • Обзор различий между двумя интерфейсами
  • Сравнение таблиц ERF со службами API
  • Предоставление рекомендаций по извлечению объектов через API
  • Признание существующих пробелов в данных
  • Представление сопоставления всех полей ERF с сопоставимыми полями ресурсов API.

Обзор

При переходе с ERF на API Display & Video 360 необходимо учитывать ряд ключевых отличий, в том числе:

  • Свежесть данных. ERF генерируются ежедневно и массово, пока API получает самую последнюю версию ресурса.
  • Структура ресурса. API использует структуры JSON, отличные от ERF, для представления тех же типов ресурсов. Некоторые ресурсы, например настройки общедоступного таргетинга, могут использовать другое пространство идентификаторов.
  • Метод поиска. API Display & Video 360 позволяет извлекать ресурсы только по отдельности, в виде списков с разбивкой на страницы или посредством передачи данных BigQuery, в отличие от необработанных файлов JSON, предоставляемых ERF.
  • Объем. В отличие от ERF, область действия которых определяется идентификатором партнера, большинство ресурсов API ограничены идентификатором рекламодателя. Ресурсы, включенные в ответы, ограничены ресурсами в пределах этой области.

Представление данных ERF в API

Файлы чтения сущностей разделены на «Общедоступные» и «Частные» таблицы. Общедоступные таблицы предоставляют информацию, доступную и применимую для всех пользователей, например значения таргетинга. Частные таблицы предоставляют данные, специфичные для партнера, например ресурсы креативов или позиций.

API Display & Video 360 не использует эту дихотомию, вместо этого предоставляя возможность получения всей этой информации через различные сервисы и используя разные структуры JSON. В этом разделе сравнивается информация, предоставляемая через общедоступные и частные таблицы ERF, с информацией, доступной через ресурсы и сервисы API Display & Video 360.

Публичная информация

Публичные таблицы ERF предоставляют справочные материалы, которые пользователи могут использовать при интерпретации настроек таргетинга полученных ими частных ресурсов и назначении таргетинга с помощью подмножества версий файлов структурированных данных (SDF) , загруженных через пользовательский интерфейс . Эти справочные материалы одинаковы для всех пользователей и состоят из числового идентификатора, используемого для сопоставления, и более описательных сведений, таких как отображаемое имя.

При использовании API Display & Video 360 справочную информацию о таргетинге можно получить через сервис targetingTypes.targetingOptions . Подобно общедоступным таблицам, этот сервис предоставляет идентификаторы и подробную информацию о параметрах таргетинга для определенного типа таргетинга. На нашей существующей странице «Настройка таргетинга» приведен пример кода, демонстрирующий получение идентификатора параметра таргетинга.

Публичные таблицы и SDF-файлы

До версии SDF v7 файлы чтения сущностей и файлы структурированных данных использовали одно и то же пространство идентификаторов для настроек таргетинга. Если вы являетесь пользователем SDF и используете общедоступные таблицы ERF для интерпретации или назначения настроек таргетинга с помощью SDF, вы можете вместо этого скачать этот справочный материал в формате CSV через интерфейс Display & Video 360.

Начиная с версии 7 , пространства идентификаторов, используемые подмножеством столбцов файлов структурированных данных, были обновлены, чтобы отделить SDF от ERF и обеспечить дальнейшее согласование с API Display & Video 360. Дополнительную информацию см. в руководстве по миграции на версию 7 и справочной документации .

Частные ресурсы

Частные таблицы ERF предоставляют ежедневный снимок текущих настроек частных ресурсов, принадлежащих партнеру. Из-за огромного объема ресурсов, которые могут быть созданы одним партнером, эти файлы могут стать очень большими, и их будет сложно загружать и обрабатывать.

В API каждой частной таблице соответствует соответствующий сервис, предоставляющий конечные точки для получения и управления этим типом ресурса. Ресурсы можно получить массово, используя соответствующий метод списка каждой службы. Структура JSON для каждого ресурса в API отличается от ERF, поскольку используются разные имена полей и общие ресурсы.

Определенная информация, доступная в представлении ресурса в формате ERF, например назначенные для ресурса настройки таргетинга или сайты канала, представлена ​​в API как дочерние элементы исходного ресурса и должна быть получена с помощью дополнительных запросов API.

Получение сущности в API

Ресурсы Display & Video 360 можно получить либо с помощью прямых запросов API, либо с помощью автоматического импорта в BigQuery .

Прямые запросы API

Каждый тип ресурса можно получить через отдельный сервис API. Ресурсы можно получить индивидуально или массово, используя метод get или list соответствующего сервиса соответственно. Важные свойства методов списка API Display & Video 360 включают в себя:

  • Требуемый объем. В отличие от ERF, область действия которых определяется партнером , большинство ресурсов в API регулируются рекламодателем . Для получения всех типов ресурсов, например позиций, в рамках партнера может потребоваться отдельный запрос списка для каждого дочернего рекламодателя этого партнера. Исключение составляют прямые дочерние элементы партнера, например рекламодатели и каналы, принадлежащие партнеру.
  • Пагинация. Методы списков API используют нумерацию страниц, чтобы гарантировать разумный размер ответов, ограничивая большинство отдельных ответов на запросы или страниц до 100 ресурсов. Если количество соответствующих ресурсов превышает размер страницы, требуются последовательные вызовы списка для получения последующих страниц ответа полного списка. Пример кода, отображающий ответ списка, приведен в разделе нашей страницы руководства по таргетингу, посвященном получению доступных параметров таргетинга .
  • Для целевого извлечения необходимы дополнительные запросы. Настройки таргетинга ресурса не включены в его объект API JSON, а являются дочерними ресурсами, известными как назначенные параметры таргетинга . Эти дочерние ресурсы необходимо получить с помощью отдельного запроса. Например, для каждой позиции , полученной с помощью запроса advertisers.lineItems.list , необходимо выполнить отдельный запрос advertisers.lineItems.bulkListAssignedTargetingOptions для получения всей информации о таргетинге.

Оптимизация извлечения ресурсов

API Display & Video 360 может потребовать несколько запросов для получения того же объема информации, который доступен в одном файле чтения объекта. Оптимизация способа извлечения ресурсов может помочь более эффективно извлекать нужные данные:

  • Выполняйте одновременные запросы к API. API Display & Video 360 защищает инфраструктуру, используя ограничения по ставкам для каждого рекламодателя и проекта . Эта структура квот позволяет реализовать многопоточное решение для нескольких рекламодателей, что сократит общее время, необходимое для получения всех необходимых ресурсов. Хотя разбиение на страницы требует, чтобы все ресурсы типа в определенной области извлекались посредством последовательных вызовов, извлечение ресурсов в другой области или другого типа может выполняться одновременно.
  • Используйте фильтры и упорядочивайте вызовы по параметрам в списке вызовов, чтобы получать только релевантные ресурсы. Например, если вас интересуют только те позиции, которые были обновлены за последний день, вы можете использовать параметр filter метода advertisers.lineItems.list , чтобы возвращать только те позиции, у которых значение updateTime превышает заданную временную метку. Это может значительно сократить количество запросов, которые необходимо сделать.
  • Кэшируйте регулярно используемые идентификаторы , чтобы избежать ненужных запросов к API. Определенная справочная информация, такая как идентификаторы параметров таргетинга и идентификаторы аудитории Google, относительно стабильна и может безопасно храниться, чтобы избежать необходимости ее извлечения при каждом использовании. Однако кэшированные значения следует проверять еженедельно, чтобы учесть нечастые изменения или устаревание.

Дополнительную информацию о том, как эффективно получить доступ к Display & Video 360 API, можно найти в нашем руководстве по оптимизации квот .

Импортировать в BigQuery

Коннектор BigQuery API Display & Video 360 позволяет ежедневно автоматически импортировать конфигурации ресурсов Display & Video 360 непосредственно в BigQuery . Конфигурации хранятся в BigQuery с использованием дизайна ресурсов API Display & Video 360. Поддерживается подмножество ресурсов API.

Дополнительную информацию об использовании коннектора BigQuery API Display & Video 360 см. в следующей облачной документации:

Известные пробелы в данных API

При переходе с ERF на API Display & Video 360 вы можете столкнуться с заметными пробелами в данных, например:

  • Заказы на размещение историй. Заказы на размещение историй невозможно получить через API, их необходимо получать через интерфейс Display & Video 360.
  • Подмножество полей ресурсов. Небольшое количество полей ресурсов, присутствующих в объектах ERF, недоступно в соответствующих ресурсах, полученных через API Display & Video 360.

Приложение. Сопоставление полей ERF с API

Сопоставление общедоступных таблиц

В таблицах ниже поля общедоступных таблиц ERF сопоставлены с существующими типами таргетинга и полями параметров таргетинга в Display & Video 360 API. Хотя значение одного поля может сопоставляться с другим, это не гарантирует, что они используют один и тот же тип данных, значения перечисления или пространство идентификаторов.

Коллекция приложений

Можно получить с типом таргетинга TARGETING_TYPE_APP_CATEGORY .

Имя поля ERF Доступность API DV360
идентификатор Поле TargetingOption.targetingOptionId .
имя Поле TargetingOption.appCategoryDetails.displayName .

Браузер

Можно получить с типом таргетинга TARGETING_TYPE_BROWSER .

Имя поля ERF Доступность API DV360
идентификатор Поле TargetingOption.targetingOptionId .
is_mobile Нет в наличии.
имя Поле TargetingOption.browserDetails.displayName .

DataPartner

В API Display & Video 360 нет эквивалентного ресурса или полей.

Критерии устройства

Доступно для типов таргетинга TARGETING_TYPE_OPERATING_SYSTEM , TARGETING_TYPE_DEVICE_MAKE_MODEL и TARGETING_TYPE_DEVICE_TYPE .

Имя поля ERF Доступность API DV360
идентификатор Поле TargetingOption.targetingOptionId или перечисление DeviceType .
is_mobile Нет в наличии.
имя Поле TargetingOption.operatingSystemDetails.displayName , поле TargetingOption.deviceMakeModelDetails.displayName или перечисление DeviceType , в зависимости от типа таргетинга.
критерий_тип Поле TargetingOption.targetingType .
операционная_система_id Нет в наличии.
mobile_brand_name Нет в наличии.
mobile_model_name Нет в наличии.
mobile_make_model_id Нет в наличии.
тип устройства Перечисление типа DeviceType .

Геолокация

Можно получить с типом таргетинга TARGETING_TYPE_GEO_REGION .

Имя поля ERF Доступность API DV360
идентификатор Поле TargetingOption.targetingOptionId .
каноническое_имя Поле TargetingOption.geoRegionDetails.displayName .
географическое_имя Нет в наличии.
код страны Нет в наличии.
код_региона Нет в наличии.
название города Нет в наличии.
почтовое_имя Нет в наличии.
dma_code Нет в наличии.

Интернет-провайдер

Можно получить с типом таргетинга TARGETING_TYPE_CARRIER_AND_ISP .

Имя поля ERF Доступность API DV360
идентификатор Поле TargetingOption.targetingOptionId .
is_mobile Нет в наличии.
имя Поле TargetingOption.carrierAndIspDetails.displayName .
Secondary_criteria_id Поле TargetingOption.targetingOptionId .

Язык

Можно получить с типом таргетинга TARGETING_TYPE_LANGUAGE .

Имя поля ERF Доступность API DV360
идентификатор Поле TargetingOption.targetingOptionId .
имя Нет в наличии. Полное отображаемое имя языка доступно в поле TargetingOption.languageDetails.displayName .

SiteToPlacementId

В API Display & Video 360 нет эквивалентного ресурса или полей.

ПоддерживаетсяExchange

Можно получить с типом таргетинга TARGETING_TYPE_EXCHANGE .

Имя поля ERF Доступность API DV360
идентификатор Exchange перечислением.
имя Exchange перечислением.

Универсальный сайт

В API Display & Video 360 нет эквивалентного ресурса или полей. На отдельные сайты и приложения можно настроить таргетинг непосредственно с помощью типов таргетинга TARGETING_TYPE_URL и TARGETING_TYPE_APP соответственно. В Display & Video 360 таргетингом можно настроить любое приложение или URL-адрес, но не о каждом приложении или URL-адресе можно сообщить. Если вы хотите исключить приложения и URL-адреса, не подлежащие отчетности, из расходов, следуйте инструкциям в Справочном центре DV360 .

Сопоставление полей частной таблицы

В таблицах ниже поля частных таблиц ERF сопоставлены с существующими полями или сервисами в API Display & Video 360. Хотя значение одного поля может сопоставляться с другим, это не гарантирует, что они используют один и тот же тип данных, значения перечисления или пространство идентификаторов.

Рекламодатель

Имя поля ERF Доступность API DV360
common_data.id Поле Advertiser.advertiserId .
common_data.name Поле Advertiser.displayName .
common_data.active Поле Advertiser.entityStatus .
common_data.integration_code Поле Advertiser.integrationDetails.integrationCode .
идентификационный номер партнера Поле Advertiser.partnerId .
код валюты Поле Advertiser.generalConfig.currencyCode .
код_часового пояса Поле Advertiser.generalConfig.timeZone .
Landing_page_url Поле Advertiser.generalConfig.domainUrl .
доступные_channel_ids Доступно с помощью метода advertisers.channels.list .
blacklist_channel_id Можно получить с помощью метода advertisers.targetingTypes.assignedtargetingOptions.list с типом таргетинга TARGETING_TYPE_CHANNEL . Если AssignedTargetingOption.channelDetails.negative имеет значение true, канал имеет отрицательную таргетинг.
dcm_configuration Нет в наличии.
dcm_network_id Поле Advertiser.adServerConfig.cmHybridConfig.cmAccountId .
dcm_advertiser_id В поле Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds перечислены идентификаторы рекламодателей CM360, которые используют общую конфигурацию Floodlight CM360.
dcm_floodlight_group_id Поле Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId .
dcm_syncable_site_ids Поле Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds .
Enable_oba_tags Нет в наличии.

Кампания

Имя поля ERF Доступность API DV360
common_data.id Поле Campaign.campaignId .
common_data.name Поле Campaign.displayName .
common_data.active Поле Campaign.entityStatus .
common_data.integration_code Нет в наличии.
идентификатор_рекламодателя Поле Campaign.advertiserId .
бюджет Поля Campaign.campaignFlight и Campaign.campaignBudgets .
Frequency_cap Поле Campaign.frequencyCap .
default_target_list Можно получить с помощью метода advertisers.campaigns.bulkListCampaignAssignedTargetingOptions .
use_video_creatives Нет в наличии.
Uses_display_creatives Нет в наличии.
use_audio_creatives Нет в наличии.
цель Поле Campaign.campaignGoal.campaignGoalType .
метрика Поле Campaign.campaignGoal.performanceGoal.performanceGoalType . PerformanceGoalType.
Object_description Поле Campaign.campaignGoal.performanceGoal.performanceGoalString . PerformanceGoalString.
metric_amount_micros Поле Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros . PerformanceGoalAmountMicros.

творческий

Имя поля ERF Доступность API DV360
common_data.id Поле Creative.creativeId .
common_data.name Поле Creative.displayName .
common_data.active Поле Creative.entityStatus .
common_data.integration_code Поле Creative.integrationCode .
идентификатор_рекламодателя Поле Creative.advertiserId .
dcm_placement_id Поле Creative.cmPlacementId .
ширина_пикселей Поле Creative.dimensions.widthPixels .
высота_пикселей Поле Creative.dimensions.heightPixels .
статус утверждения Поле Creative.reviewStatus .
расширяющееся_направление Поле Creative.expandingDirection .
творческий_тип Поле Creative.creativeType .

CustomAffinity

Имя поля ERF Доступность API DV360
идентификатор Поле CustomList.customListId .
имя Поле CustomList.displayName .
описание Нет в наличии.
идентификатор_рекламодателя Нет в наличии.

ПрожекторДеятельность

Имя поля ERF Доступность API DV360
common_data.id Поле FloodlightActivity.floodlightActivityId .
common_data.name Поле FloodlightActivity.displayName .
common_data.active Поле FloodlightActivity.servingStatus .
common_data.integration_code Нет в наличии.
идентификатор_рекламодателя В поле FloodlightActivity.advertiserIds перечислены все рекламодатели, имеющие доступ к действиям Floodlight под данным партнером.
идентификационный номер партнера Предоставляется пользователем при запросе к сервису floodlightGroups.floodlightActivities .
ремаркетинг_включен В поле FloodlightActivity.remarketingConfigs указана эта конфигурация для каждого рекламодателя, имеющего доступ к действиям Floodlight под данным партнером.
ssl_required FloodlightActivity.sslRequired поле.

Порядок вставки

Имя поля ERF Доступность API DV360
common_data.id Поле InsertionOrder.insertionOrderId .
common_data.name Поле InsertionOrder.displayName .
common_data.active Поле InsertionOrder.entityStatus .
common_data.integration_code Поле InsertionOrder.integrationDetails.integrationCode .
идентификатор_рекламодателя Поле InsertionOrder.advertiserId .
идентификатор кампании Поле InsertionOrder.campaignId .
общий_бюджет Нет в наличии. Можно рассчитать, используя содержимое поля InsertionOrder.budget.budgetSegments .
запланированные_сегменты Поле InsertionOrder.budget.budgetSegments .
Frequency_cap Поле InsertionOrder.frequencyCap .
default_partner_costs Поле InsertionOrder.partnerCosts .
default_target_list Можно получить с помощью метода advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions .

Источник инвентаря

Имя поля ERF Доступность API DV360
идентификатор Поле InventorySource.inventorySourceId .
несекретный Нет в наличии.
имя_инвентаря Поле InventorySource.displayName .
обменный_ид Поле InventorySource.exchange .
accessing_advertisers Поля InventorySource.readWriteAccessors и InventorySource.readAdvertiserIds .
внешний_ид Поле InventorySource.dealId .
min_cpm_micros Поле InventorySource.rateDetails.rate.nanos в зависимости от значения поля InventorySource.rateDetails.inventorySourceRateType .
min_cpm_currency_code Поле InventorySource.rateDetails.rate.currencyCode .

Линейный элемент

Имя поля ERF Доступность API DV360
common_data.id Поле LineItem.lineItemId .
common_data.name Поле LineItem.displayName .
common_data.active Поле LineItem.entityStatus .
common_data.integration_code Поле LineItem.integrationDetails.integrationCode .
line_item_type Поле LineItem.lineItemType .
вставка_order_id Поле LineItem.insertionOrderId .
Creative_ids Поле LineItem.creativeIds .
max_cpm_advertiser_micros Поля LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros или LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros в зависимости от используемой схемы стратегии.
Performance_goal Поля LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType . PerformanceGoalType или LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType PerformanceGoalType в зависимости от используемой схемы стратегии.
target_advertiser_micros Поле LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalAmountMicros . PerformanceGoalAmountMicros.
Partner_revenue_model Поле LineItem.partnerRevenueModel .
Cost_tracking_pixels Поле LineItem.conversionCounting.floodlightActivityConfigs .
Budget.start_time_usec Поле LineItem.flight.dateRange.startDate .
Budget.end_time_usec Поле LineItem.flight.dateRange.endDate .
Budget.max_impressions Поле LineItem.budget.maxAmount , если LineItem.budget.budgetUnit имеет BUDGET_UNIT_IMPRESSIONS .
Budget.max_spend_advertiser_micros Поле LineItem.budget.maxAmount , если LineItem.budget.budgetUnit имеет BUDGET_UNIT_CURRENCY .
Budget.pacing_type Поле LineItem.pacing.pacingPeriod .
Budget.pacing_max_impressions Поле LineItem.pacing.dailyMaxImpressions .
Budget.pacing_max_spend_advertiser_micros Поле LineItem.pacing.dailyMaxMicros .
Budget.pacing_distribution Поле LineItem.pacing.pacingType .
Frequency_cap Поле LineItem.frequencyCap .
Partner_costs Поле LineItem.partnerCosts .
целевой_список Можно получить с помощью метода advertisers.lineItems.bulkListLineItemAssignedTargetingOptions .

Список отрицательных ключевых слов

Имя поля ERF Доступность API DV360
идентификатор Поле NegativeKeywordList.negativeKeywordListId .
имя Поле NegativeKeywordList.displayName .
идентификатор_рекламодателя Поле NegativeKeywordList.advertiserId .

Партнер

Имя поля ERF Доступность API DV360
common_data.id Поле Partner.partnerId .
common_data.name Поле Partner.displayName .
common_data.active Поле Partner.entityStatus .
common_data.integration_code Нет в наличии.
код валюты Поле Partner.generalConfig.currencyCode .
обмен_настройки Поле Partner.exchangeConfig.enabledExchanges .
default_partner_costs Нет в наличии.
default_partner_revenue Нет в наличии.
default_target_list Нет в наличии.

Пиксель

В API Display & Video 360 нет эквивалентного ресурса или полей.

Универсальный канал

Имя поля ERF Доступность API DV360
идентификатор Поле Channel.channelId .
имя Поле Channel.displayName .
site_ids Доступно для получения с помощью методов advertisers.channels.sites.list и partners.channels.sites.list , в зависимости от типа owner .
accessing_advertisers Нет в наличии.
is_deleted Нет в наличии.
is_brand_safe_channel Нет в наличии.

Список пользователей

Имя поля ERF Доступность API DV360
идентификатор Поле FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId .
имя Поле FirstAndThirdPartyAudience.displayName .
data_partner_id Нет в наличии.
accessing_advertisers Нет в наличии.
Partner_pricing Нет в наличии.
рекламодатель_цены Нет в наличии.