API Display & Video 360 v2 больше не используется. Вместо этого используйте Display & Video 360 API v3 . Инструкции по переходу с версии 2 на версию 3 см. в нашем руководстве по миграции .

Эта страница переведена с помощью Cloud Translation API.

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

Файлы чтения объектов (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` .
Partner_id	Поле `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` . 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 под данным партнером.
Partner_id	Предоставляется пользователем при запросе к сервису `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` . 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` PerformanceGoalAutoBid.maxAverageCpmBidAmountMicros в зависимости от используемой схемы стратегии.
Performance_goal	Поля `LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType` . PerformanceGoalType или `LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType` PerformanceGoalAutoBid. 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	Нет в наличии.
рекламодатель_цены	Нет в наличии.