Migra desde archivos de lectura de entidades

Los archivos de lectura de entidades (ERF) son representaciones JSON de los objetos de campaña de un socio que, a pedido, se generan a diario y están disponibles a través de Google Cloud Storage.

Los ERF dejaron de estar disponibles en junio de 2021. A partir del 31 de octubre de 2024, los ERF se desactivarán oficialmente y ya no se generarán. Se recomienda a todos los usuarios existentes de archivos de lectura de entidades que migren a la API de Display & Video 360 para continuar recuperando los recursos de Display & Video 360.

En esta guía, se analiza cómo migrar archivos de lectura de entidades a la API de Display & Video 360 de las siguientes maneras:

• Brindar una descripción general de las diferencias entre las dos interfaces
• Comparación de tablas de ERF con servicios de API
• Proporciona orientación sobre la recuperación de entidades a través de la API
• Reconocer las brechas de datos existentes
• Presentación de una asignación de todos los campos de ERF a campos de recursos de API comparables

Descripción general

Cuando migres de ERF a la API de Display & Video 360, debes considerar una serie de diferencias clave, incluidas las siguientes:

• Actualización de los datos. Los ERF se generan diariamente y de forma masiva, mientras que la API recupera la versión más actualizada de un recurso.
• Estructura de los recursos. La API utiliza estructuras JSON diferentes a las de ERF para representar los mismos tipos de recursos. Algunos recursos, como la configuración de la segmentación pública, pueden usar un espacio de ID diferente.
• Método de recuperación. La API de Display & Video 360 solo permite la recuperación de recursos de forma individual, en listas paginadas o a través de transferencias de datos de BigQuery, a diferencia de los archivos JSON sin procesar que proporciona ERF.
• Alcance. A diferencia de los ERF, que tienen alcance por ID de socio, la mayoría de los recursos de API están dentro de alcance por ID de anunciante. Los recursos incluidos en las respuestas se limitan a los recursos dentro de ese alcance.

Representación de datos de ERF en la API

Los archivos de lectura de entidades se separan en tablas “Public” y “Private”. Las tablas públicas proporcionan información que está disponible y aplicable a todos los usuarios, como los valores de segmentación. Las tablas privadas proporcionan datos específicos de un socio, como recursos de creatividades o líneas de pedido.

La API de Display & Video 360 no usa esta dicotomía, sino que hace que toda esta información se pueda recuperar a través de varios servicios y usa diferentes estructuras JSON. En esta sección, se compara la información proporcionada a través de las tablas de ERF públicas y privadas con la que está disponible a través de los recursos y servicios de la API de Display & Video 360.

Información pública

Las tablas públicas de ERF proporcionan materiales de referencia para que los usuarios los usen cuando interpretan la configuración de segmentación de los recursos privados recuperados y asignan la segmentación a través de un subconjunto de versiones de archivos de datos estructurados (SDF) subidas a través de la IU. Estos materiales de referencia son los mismos para todos los usuarios y consisten en un ID numérico, que se usa en la asignación, y detalles más descriptivos, como un nombre visible.

Advertencia: Dado que la API de Display & Video 360 usa un espacio de ID diferente para la configuración de la segmentación, toda la información almacenada en caché de las tablas públicas de ERF deberá recuperarse a través de la API.

Cuando usas la API de Display & Video 360, la información de referencia de segmentación se puede recuperar a través del servicio targetingTypes.targetingOptions. Al igual que las tablas públicas, este servicio proporciona los ID y los detalles de las opciones de segmentación para un tipo de segmentación específico. Consulta nuestra página existente sobre la configuración de la segmentación para ver un ejemplo de código que muestra la recuperación del ID de la opción de segmentación.

Nota: Aunque las solicitudes al servicio targetingTypes.targetingOptions requieren un ID de anunciante, la información recuperada debe ser idéntica para todos los anunciantes.

Tablas públicas y SDF

Antes de SDF v7, los archivos de lectura de entidades y los archivos de datos estructurados usan el mismo espacio de ID para la configuración de segmentación. Si eres usuario de SDF que usa tablas públicas de ERF para interpretar o asignar configuraciones de segmentación con SDF, puedes descargar este material de referencia en formato CSV a través de la IU de Display & Video 360.

A partir de la versión 7, se actualizaron los espacios de ID que usa un subconjunto de columnas de archivos de datos estructurados para separar el SDF de los ERF y alinearse aún más con la API de Display & Video 360. Consulta la guía de migración de la versión 7 y la documentación de referencia para obtener más información.

Recursos privados

Las tablas privadas de ERF proporcionan un resumen diario de la configuración actual de los recursos privados que son propiedad de un socio. Debido al gran volumen de recursos que se pueden crear con un solo socio, estos archivos pueden llegar a ser muy grandes y difíciles de descargar y procesar.

En la API, cada tabla privada tiene un servicio correspondiente que proporciona extremos para la recuperación y la administración de ese tipo de recurso. Los recursos se pueden recuperar de forma masiva con el método de lista respectivo de cada servicio. La estructura JSON para cada recurso es diferente en la API en comparación con ERF, ya que utiliza diferentes nombres de campo y recursos compartidos.

Cierta información disponible en la representación de ERF de un recurso, como la configuración de segmentación asignada de un recurso o los sitios de un canal, se representan en la API como elementos secundarios del recurso original y se deben recuperar a través de solicitudes a la API adicionales.

Recuperación de entidades en la API

Los recursos de Display & Video 360 se pueden recuperar a través de solicitudes directas a la API o importaciones automáticas a BigQuery.

Solicitudes directas a la API

Cada tipo de recurso se puede recuperar a través de un servicio de API diferente. Los recursos se pueden recuperar de forma individual o masiva con el método get o list del servicio apropiado, respectivamente. Entre las propiedades importantes de los métodos de listas de la API de Display & Video 360, se incluyen las siguientes:

• Alcance obligatorio. A diferencia de los ERF, cuyo alcance es el socio, la mayoría de los recursos de la API están dentro del alcance del anunciante. Recuperar todos los tipos de recursos (como las líneas de pedido) de un socio puede requerir una solicitud de lista individual para cada anunciante secundario de ese socio. Entre las excepciones se incluyen los elementos secundarios directos de un socio, como los anunciantes y los canales que son propiedad de los socios.
• Paginación. Los métodos de lista de APIs utilizan la paginación para garantizar que las respuestas tengan un tamaño razonable, lo que limita la mayoría de las respuestas de solicitudes individuales (o páginas) a 100 recursos. Si la cantidad de recursos relevantes es mayor que el tamaño de la página, se requieren llamadas consecutivas a listas para recuperar las páginas posteriores de la respuesta de la lista completa. Puedes encontrar un ejemplo de código de paginación de una respuesta de lista en una sección de nuestra página de la Guía de segmentación relacionada con la recuperación de opciones de segmentación disponibles .
• Se requieren solicitudes adicionales para recuperar la segmentación. La configuración de la segmentación de un recurso no se incluye en su objeto JSON de la API, sino recursos secundarios conocidos como opciones de segmentación asignadas. Estos recursos secundarios se deben recuperar a través de una solicitud independiente. Por ejemplo, para cada línea de pedido recuperada mediante una solicitud advertisers.lineItems.list, se debe realizar una solicitud advertisers.lineItems.bulkListAssignedTargetingOptions independiente para recuperar toda la información de segmentación.

Optimiza la recuperación de recursos

Es posible que la API de Display & Video 360 requiera varias solicitudes para recuperar la misma cantidad de información que está disponible en un solo archivo de lectura de entidades. Optimizar la forma en la que recuperas los recursos puede ayudarte a recuperar los datos que necesitas de manera más eficiente:

• Realizar solicitudes simultáneas a la API La API de Display & Video 360 protege la infraestructura mediante solicitudes por anunciante y límites de frecuencia de proyecto. Esta estructura de cuotas te permite implementar una solución de varios subprocesos en varios anunciantes, lo que reducirá el tiempo total que lleva recuperar todos los recursos necesarios. Si bien la paginación requiere que todos los recursos de un tipo dentro de un alcance determinado se recuperen mediante llamadas consecutivas, la recuperación de recursos dentro de otro alcance o de otro tipo se puede realizar de forma simultánea.
• Usa filtros y ordena por parámetros en tus llamadas a lista para recuperar solo los recursos relevantes. Por ejemplo, si solo te interesan las líneas de pedido que se actualizaron en el último día, puedes usar el parámetro filter del método advertisers.lineItems.list para mostrar solo líneas de pedido con un updateTime mayor que una marca de tiempo determinada. Esto puede reducir de manera significativa la cantidad de solicitudes que se deben realizar.
• Almacena en caché los IDs de uso frecuente para evitar solicitudes innecesarias a la API. Cierta información de referencia, como los IDs de opciones de segmentación y los IDs de público de Google, son relativamente estables y se pueden almacenar de forma segura para evitar la necesidad de recuperarla cada vez que la uses. Sin embargo, los valores almacenados en caché se deben verificar semanalmente para tener en cuenta los cambios o las bajas poco frecuentes.

Consulta nuestra guía de optimización de cuotas para obtener más información sobre cómo acceder a la API de Display & Video 360 de manera eficiente.

Importar a BigQuery

El conector de BigQuery de la API de Display & Video 360 te permite importar de forma automática la configuración de recursos de Display & Video 360 directamente a BigQuery todos los días. Las configuraciones se almacenan en BigQuery mediante el diseño de recursos de la API de Display & Video 360. Se admite un subconjunto de recursos de API.

Consulta la siguiente documentación sobre la nube para obtener más información sobre el uso del conector de BigQuery de la API de Display & Video 360:

• ¿Qué es un Servicio de transferencia de datos de BigQuery?
• Cómo programar una transferencia de Display & Video 360
• Transformación de datos de Display & Video 360

Brechas de datos conocidas de la API

Existen lagunas de datos notables que puedes encontrar cuando migras de ERF a la API de Display & Video 360, como las siguientes:

• Pedidos de inserción de historias. Los pedidos de inserción de historias no se pueden recuperar a través de la API y deben recuperarse mediante la IU de Display & Video 360.
• Un subconjunto de campos de recursos. Una pequeña cantidad de campos de recursos presentes en los objetos ERF no está disponible en los recursos correspondientes recuperados a través de la API de Display & Video 360.

Apéndice: Asignación de campos de ERF a la API

Asignación de tablas públicas

En las siguientes tablas, se asignan los campos de las tablas públicas de ERF a los tipos de segmentación y los campos de opciones de segmentación existentes en la API de Display & Video 360. Aunque el valor de un campo se puede asignar a otro, eso no garantiza que usen el mismo tipo de datos, valores de enumeración o espacio de ID.

Colección de apps

Se puede recuperar en el tipo de segmentación TARGETING_TYPE_APP_CATEGORY.

Nombre del campo ERF	Disponibilidad de la API de DV360
id	TargetingOption.targetingOptionId .
name	TargetingOption.appCategoryDetails.displayName .

Navegador

Se puede recuperar en el tipo de segmentación TARGETING_TYPE_BROWSER.

Nombre del campo ERF	Disponibilidad de la API de DV360
id	TargetingOption.targetingOptionId .
is_mobile	No disponible.
name	TargetingOption.browserDetails.displayName .

DataPartner

No hay recursos ni campos equivalentes disponibles en la API de Display & Video 360.

DeviceCriteria

Se puede recuperar en los tipos de segmentación TARGETING_TYPE_OPERATING_SYSTEM, TARGETING_TYPE_DEVICE_MAKE_MODEL y TARGETING_TYPE_DEVICE_TYPE.

Nombre del campo ERF	Disponibilidad de la API de DV360
id	Campo TargetingOption.targetingOptionId o enum DeviceType
is_mobile	No disponible.
name	Campo TargetingOption.operatingSystemDetails.displayName , campo TargetingOption.deviceMakeModelDetails.displayName o enum DeviceType , según el tipo de segmentación.
criteria_type	TargetingOption.targetingType .
operating_system_id	No disponible.
mobile_brand_name	No disponible.
mobile_model_name	No disponible.
mobile_make_model_id	No disponible.
device_type	Enumeración DeviceType .

GeoLocation

Se puede recuperar en el tipo de segmentación TARGETING_TYPE_GEO_REGION.

Nombre del campo ERF	Disponibilidad de la API de DV360
id	TargetingOption.targetingOptionId .
canonical_name	TargetingOption.geoRegionDetails.displayName .
geo_name	No disponible.
country_code	No disponible.
region_code	No disponible.
city_name	No disponible.
postal_name	No disponible.
dma_code	No disponible.

Isp

Se puede recuperar en el tipo de segmentación TARGETING_TYPE_CARRIER_AND_ISP.

Nombre del campo ERF	Disponibilidad de la API de DV360
id	TargetingOption.targetingOptionId .
is_mobile	No disponible.
name	TargetingOption.carrierAndIspDetails.displayName .
secondary_criteria_id	TargetingOption.targetingOptionId .

Idioma

Se puede recuperar en el tipo de segmentación TARGETING_TYPE_LANGUAGE.

Nombre del campo ERF	Disponibilidad de la API de DV360
id	TargetingOption.targetingOptionId .
name	No disponible. El nombre visible completo de un idioma está disponible en el campo TargetingOption.languageDetails.displayName .

SiteToPlacementId

No hay recursos ni campos equivalentes disponibles en la API de Display & Video 360.

SupportedExchange

Se puede recuperar en el tipo de segmentación TARGETING_TYPE_EXCHANGE.

Nombre del campo ERF	Disponibilidad de la API de DV360
id	Enumeración Exchange .
name	Enumeración Exchange .

UniversalSite

No hay recursos ni campos equivalentes disponibles en la API de Display & Video 360. Las apps y los sitios individuales se pueden orientar directamente en los tipos de segmentación TARGETING_TYPE_URL y TARGETING_TYPE_APP, respectivamente. En Display & Video 360, se puede orientar a cualquier app o URL, pero no se pueden generar informes sobre todas las apps o URLs. Si quieres quitar de los gastos las apps y URLs que no se pueden informar, sigue las instrucciones del Centro de ayuda de DV360.

Asignación de campos de tabla privada

En las siguientes tablas, se asignan los campos de las tablas privadas de ERF a los campos o servicios existentes en la API de Display & Video 360. Aunque el valor de un campo puede asignarse a otro, eso no garantiza que utilicen el mismo tipo de datos, valores enum o espacio de ID.

Anunciante

Nombre del campo ERF	Disponibilidad de la API de 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 .
currency_code	Advertiser.generalConfig.currencyCode .
timezone_code	Advertiser.generalConfig.timeZone .
landing_page_url	Advertiser.generalConfig.domainUrl .
available_channel_ids	Se puede recuperar a través del método advertisers.channels.list .
blacklist_channel_id	Se puede recuperar a través del método advertisers.targetingTypes.assignedtargetingOptions.list en el tipo de segmentación TARGETING_TYPE_CHANNEL . Si el valor de AssignedTargetingOption.channelDetails.negative es verdadero, el canal se orienta de manera negativa.
dcm_configuration	No disponible.
dcm_network_id	Advertiser.adServerConfig.cmHybridConfig.cmAccountId .
dcm_advertiser_id	En el campo Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds , se enumeran los IDs de anunciante de CM360 que comparten la configuración de Floodlight de CM360.
dcm_floodlight_group_id	Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId .
dcm_syncable_site_ids	Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds .
enable_oba_tags	No disponible.

Campaign

Nombre del campo ERF	Disponibilidad de la API de DV360
common_data.id	Campaign.campaignId .
common_data.name	Campaign.displayName .
common_data.active	Campaign.entityStatus .
common_data.integration_code	No disponible.
advertiser_id	Campaign.advertiserId .
presupuesto	Campos Campaign.campaignFlight y Campaign.campaignBudgets .
frequency_cap	Campaign.frequencyCap .
default_target_list	Se puede recuperar a través del método advertisers.campaigns.bulkListCampaignAssignedTargetingOptions .
uses_video_creatives	No disponible.
uses_display_creatives	No disponible.
uses_audio_creatives	No disponible.
objetivo	Campaign.campaignGoal.campaignGoalType .
métrica	Campaign.campaignGoal.performanceGoal.performanceGoalType .
objective_description	Campaign.campaignGoal.performanceGoal.performanceGoalString .
metric_amount_micros	Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros .

Creatividad

Nombre del campo ERF	Disponibilidad de la API de DV360
common_data.id	Creative.creativeId .
common_data.name	Creative.displayName .
common_data.active	Creative.entityStatus .
common_data.integration_code	Creative.integrationCode .
advertiser_id	Creative.advertiserId .
dcm_placement_id	Creative.cmPlacementId .
width_pixels	Creative.dimensions.widthPixels .
height_pixels	Creative.dimensions.heightPixels .
approval_status	Creative.reviewStatus .
expanding_direction	Creative.expandingDirection .
creative_type	Creative.creativeType .

CustomAffinity

Nombre del campo ERF	Disponibilidad de la API de DV360
id	CustomList.customListId .
name	CustomList.displayName .
descripción	No disponible.
advertiser_id	No disponible.

FloodlightActivity

Nombre del campo ERF	Disponibilidad de la API de DV360
common_data.id	FloodlightActivity.floodlightActivityId .
common_data.name	FloodlightActivity.displayName .
common_data.active	FloodlightActivity.servingStatus .
common_data.integration_code	No disponible.
advertiser_id	El campo FloodlightActivity.advertiserIds muestra una lista de todos los anunciantes con acceso a la actividad de Floodlight del socio determinado.
partner_id	Lo proporciona el usuario cuando realiza una solicitud al servicio de floodlightGroups.floodlightActivities.
remarketing_enabled	El campo FloodlightActivity.remarketingConfigs enumera esta configuración para cada anunciante con acceso a la actividad de Floodlight del socio determinado.
ssl_required	FloodlightActivity.sslRequired .

InsertionOrder

Nombre del campo ERF	Disponibilidad de la API de DV360
common_data.id	InsertionOrder.insertionOrderId .
common_data.name	InsertionOrder.displayName .
common_data.active	InsertionOrder.entityStatus .
common_data.integration_code	InsertionOrder.integrationDetails.integrationCode .
advertiser_id	InsertionOrder.advertiserId .
campaign_id	InsertionOrder.campaignId .
overall_budget	No disponible. Se puede calcular con el contenido del campo InsertionOrder.budget.budgetSegments .
scheduled_segments	InsertionOrder.budget.budgetSegments .
frequency_cap	InsertionOrder.frequencyCap .
default_partner_costs	InsertionOrder.partnerCosts .
default_target_list	Se puede recuperar a través del método advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions .

InventorySource

Nombre del campo ERF	Disponibilidad de la API de DV360
id	InventorySource.inventorySourceId .
sin clasificar	No disponible.
inventory_name	InventorySource.displayName .
exchange_id	InventorySource.exchange .
accessing_advertisers	Campos InventorySource.readWriteAccessors y InventorySource.readAdvertiserIds .
external_id	InventorySource.dealId .
min_cpm_micros	InventorySource.rateDetails.rate.nanos , según el valor del campo InventorySource.rateDetails.inventorySourceRateType .
min_cpm_currency_code	InventorySource.rateDetails.rate.currencyCode .

LineItem

Nombre del campo ERF	Disponibilidad de la API de 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 .
insertion_order_id	LineItem.insertionOrderId .
creative_ids	LineItem.creativeIds .
max_cpm_advertiser_micros	Campos LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros o LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros , según el esquema de estrategia que se use.
performance_goal	Campos LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType o LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType , según el esquema de estrategia que se use.
goal_advertiser_micros	LineItem.bidStrategy.performanceGoalAutoBid.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	Campo LineItem.budget.maxAmount si LineItem.budget.budgetUnit es BUDGET_UNIT_IMPRESSIONS .
budget.max_spend_advertiser_micros	Campo LineItem.budget.maxAmount si LineItem.budget.budgetUnit es 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 .
target_list	Se puede recuperar a través del método advertisers.lineItems.bulkListLineItemAssignedTargetingOptions .

NegativeKeywordList

Nombre del campo ERF	Disponibilidad de la API de DV360
id	NegativeKeywordList.negativeKeywordListId .
name	NegativeKeywordList.displayName .
advertiser_id	NegativeKeywordList.advertiserId .

Socio

Nombre del campo ERF	Disponibilidad de la API de DV360
common_data.id	Partner.partnerId .
common_data.name	Partner.displayName .
common_data.active	Partner.entityStatus .
common_data.integration_code	No disponible.
currency_code	Partner.generalConfig.currencyCode .
exchange_settings	Partner.exchangeConfig.enabledExchanges .
default_partner_costs	No disponible.
default_partner_revenue	No disponible.
default_target_list	No disponible.

Pixel

No hay recursos ni campos equivalentes disponibles en la API de Display & Video 360.

UniversalChannel

Nombre del campo ERF	Disponibilidad de la API de DV360
id	Channel.channelId .
name	Channel.displayName .
site_ids	Recuperable con los métodos advertisers.channels.sites.list y partners.channels.sites.list según el tipo de owner .
accessing_advertisers	No disponible.
is_deleted	No disponible.
is_brand_safe_channel	No disponible.

UserList

Nombre del campo ERF	Disponibilidad de la API de DV360
id	FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId .
name	FirstAndThirdPartyAudience.displayName .
data_partner_id	No disponible.
accessing_advertisers	No disponible.
partner_pricing	No disponible.
advertiser_pricings	No disponible.