Migrar de arquivos da leitura de entidades

Os arquivos da leitura de entidades (ERFs, na sigla em inglês) são representações JSON dos objetos de campanha de um parceiro que, mediante solicitação, são geradas diariamente e disponibilizadas pelo Google Cloud Storage.

Os ERFs foram descontinuados em junho de 2021. A partir de 31 de outubro de 2024, os ERFs serão oficialmente desativados e não serão mais gerados. Recomendamos que todos os usuários atuais do arquivo de leitura de entidades migrem para a API Display & Video 360 para continuar recuperando recursos do Display & Video 360.

Este guia explica como migrar dos arquivos da leitura de entidades para a API Display & Video 360:

• Fornecer uma visão geral das diferenças entre as duas interfaces.
• Comparando tabelas ERF com serviços de API
• Fornecer orientação sobre a recuperação de entidades por meio da API
• Reconhecer as lacunas de dados existentes
• Apresentando um mapeamento de todos os campos ERF para campos de recursos de API comparáveis

Visão geral

Há várias diferenças importantes a serem consideradas ao migrar dos ERFs para a API Display & Video 360, incluindo:

• Atualização de dados. Os ERFs são gerados diariamente e em massa, enquanto a API recupera a versão mais atualizada de um recurso.
• Estrutura de recursos. A API usa estruturas JSON diferentes do ERF para representar os mesmos tipos de recursos. Alguns recursos, como configurações de segmentação pública, podem usar um espaço de ID diferente.
• Método de recuperação. A API Display & Video 360 só permite a recuperação de recursos individualmente, em listas paginadas ou por transferências de dados do BigQuery, em contraste com os arquivos JSON brutos fornecidos pelo ERF.
• Escopo. Ao contrário dos ERFs, que têm escopo por ID do parceiro, a maioria dos recursos de API tem escopo por ID do anunciante. Os recursos incluídos nas respostas são limitados a recursos dentro desse escopo.

Representação de dados ERF na API

Os arquivos da leitura de entidades são separados em tabelas "Pública" e "Particular". As tabelas públicas fornecem informações disponíveis e aplicáveis a todos os usuários, como valores de segmentação. As tabelas particulares fornecem dados específicos de um parceiro, como recursos de criativos ou itens de linha.

A API Display & Video 360 não usa essa dicotomia. Em vez disso, ela torna todas essas informações recuperáveis por vários serviços e usando diferentes estruturas JSON. Esta seção compara as informações fornecidas por tabelas de ERF públicas e privadas com as disponibilizadas pelos recursos e serviços da API Display & Video 360.

Informações públicas

As tabelas públicas de EFE fornecem materiais de referência para os usuários usarem ao interpretar as configurações de segmentação dos recursos particulares recuperados e atribuir a segmentação por meio de um subconjunto de versões dos arquivos de dados estruturados (SDFs, na sigla em inglês) enviadas pela interface. Esses materiais de referência são os mesmos para todos os usuários e consistem em um ID numérico, usado para mapeamento, e detalhes mais descritivos, como um nome de exibição.

Aviso :como a API Display & Video 360 usa um espaço de ID diferente para as configurações de segmentação, todas as informações em cache de tabelas públicas do ERF precisarão ser recuperadas pela API.

Ao usar a API Display & Video 360, as informações de referência de segmentação podem ser recuperadas pelo serviço targetingTypes.targetingOptions. Semelhante às tabelas públicas, esse serviço fornece os IDs e os detalhes das opções de segmentação para um tipo específico de segmentação. Consulte a página Definir segmentação para um exemplo de código que demonstra a recuperação do ID da opção de segmentação.

Observação :embora as solicitações para o serviço targetingTypes.targetingOptions exijam um ID do anunciante, as informações recuperadas precisam ser idênticas em todos os anunciantes.

Tabelas públicas e SDFs

Antes do SDF v7, os arquivos de leitura de entidades e os arquivos de dados estruturados usam o mesmo espaço de ID para as configurações de segmentação. Se você for um usuário do SDF usando tabelas públicas ERF para interpretar ou atribuir configurações de segmentação usando SDF, poderá fazer o download desse material de referência no formato CSV por meio da interface do Display & Video 360.

A partir da v7, os espaços de ID usados por um subconjunto de colunas de arquivos de dados estruturados foram atualizados para separar o SDF dos ERFs e se alinhar ainda mais com a API Display & Video 360. Para mais informações, consulte o guia de migração v7 e a documentação de referência.

Recursos privados

As tabelas particulares do ERF fornecem um resumo diário das configurações atuais dos recursos particulares de propriedade de um parceiro. Devido ao grande volume de recursos que podem ser criados em um único parceiro, esses arquivos podem se tornar muito grandes e difíceis de fazer o download e processar.

Na API, cada tabela particular tem um serviço correspondente que fornece endpoints para recuperação e gerenciamento desse tipo de recurso. Os recursos podem ser recuperados em massa usando o respectivo método de lista de cada serviço. A estrutura JSON de cada recurso é diferente na API em comparação com o ERF, utilizando diferentes nomes de campo e recursos compartilhados.

Certas informações disponíveis na representação ERF de um recurso, como as configurações de segmentação atribuídas do recurso ou os sites de um canal, são representadas na API como filhas do recurso original e precisam ser recuperadas por solicitações adicionais.

Recuperação de entidades na API

Os recursos do Display & Video 360 podem ser recuperados por solicitações diretas de API ou importações automáticas para o BigQuery.

Solicitações diretas de API

Cada tipo de recurso pode ser recuperado por meio de um serviço de API diferente. Os recursos podem ser recuperados individualmente ou em massa usando o método "get" ou "list" do serviço apropriado, respectivamente. As propriedades importantes dos métodos de lista da API Display & Video 360 incluem:

• Escopo obrigatório. Ao contrário dos ERFs, que têm escopo de parceiro, a maioria dos recursos na API é definida pelo anunciante. A recuperação de todo um tipo de recurso, como itens de linha, em um parceiro pode exigir uma solicitação de lista individual para cada anunciante filho desse parceiro. Exceções incluem filhos diretos de um parceiro, como anunciantes e canais de propriedade do parceiro.
• Paginação. Os métodos de lista de APIs usam paginação para garantir que as respostas tenham um tamanho razoável, limitando a maioria das respostas de solicitações individuais, ou páginas, a 100 recursos. Se o número de recursos relevantes for maior que o tamanho da página, as chamadas de lista consecutivas serão necessárias para recuperar as páginas subsequentes da resposta completa da lista. Um exemplo de código de paginação de uma resposta de lista é fornecido em uma seção da nossa página do Guia de segmentação sobre como recuperar as opções de segmentação disponíveis .
• Solicitações adicionais são necessárias para a recuperação de segmentação. As configurações de segmentação de um recurso não estão incluídas no objeto JSON da API, mas são recursos filhos conhecidos como opções de segmentação atribuídas. Esses recursos filhos precisam ser recuperados por meio de uma solicitação separada. Por exemplo, para cada item de linha recuperado com uma solicitação advertisers.lineItems.list, é necessário fazer uma solicitação advertisers.lineItems.bulkListAssignedTargetingOptions separada para recuperar todas as informações de segmentação.

Otimizar a recuperação de recursos

A API Display & Video 360 pode exigir várias solicitações para recuperar a mesma quantidade de informações disponíveis em um único arquivo de leitura de entidades. A otimização da forma como você extrai recursos pode ajudar a recuperar os dados necessários com mais eficiência:

• Faça solicitações simultâneas para a API. A API Display & Video 360 protege a infraestrutura usando limites de taxa de solicitações por anunciante e projeto. Essa estrutura de cotas permite implementar uma solução com várias linhas de execução em vários anunciantes, o que reduz o tempo total necessário para recuperar todos os recursos necessários. Embora a paginação exija que todos os recursos de um tipo em determinado escopo sejam recuperados por chamadas consecutivas, a recuperação de recursos em outro escopo ou de outro tipo pode ser feita simultaneamente.
• Use filtros e ordene por parâmetros nas chamadas de lista para recuperar apenas os recursos relevantes. Por exemplo, se você só tem interesse em itens de linha que foram atualizados no último dia, use o parâmetro filter do método advertisers.lineItems.list para retornar somente itens de linha com um updateTime maior que um determinado carimbo de data/hora. Isso pode reduzir significativamente o número de solicitações que precisam ser feitas.
• Armazene em cache os IDs usados com frequência para evitar solicitações de API desnecessárias. Algumas informações de referência, como IDs de opções de segmentação e IDs de público-alvo do Google, são relativamente estáveis e podem ser armazenadas com segurança para evitar a necessidade de recuperação a cada uso. No entanto, os valores em cache precisam ser verificados semanalmente para considerar mudanças ou descontinuações pouco frequentes.

Consulte nosso Guia de otimização de cotas para mais informações sobre como acessar a API Display & Video 360 de maneira eficiente.

Importar para o BigQuery

Com o conector do BigQuery da API Display & Video 360, é possível importar de forma automática e diária as configurações de recursos do Display & Video 360 diretamente para o BigQuery. As configurações são armazenadas no BigQuery usando o design de recursos da API Display & Video 360. Há suporte para um subconjunto de recursos da API.

Consulte a seguinte documentação da nuvem para mais informações sobre como usar o conector do BigQuery da API Display & Video 360:

• O que é o serviço de transferência de dados do BigQuery?
• Programar uma transferência do Display & Video 360
• Transformação de dados do Display & Video 360

Lacunas de dados da API conhecidas

Existem lacunas de dados importantes que você pode encontrar ao migrar do ERF para a API Display & Video 360, como:

• Pedidos de inserção de imagens históricas. Os pedidos de inserção de história não podem ser recuperados pela API e precisam ser recuperados na interface do Display & Video 360.
• Um subconjunto de campos de recursos. Um pequeno número de campos de recursos presentes em objetos ERF não está disponível nos recursos correspondentes recuperados pela API Display & Video 360.

Apêndice: como mapear campos ERF para a API

Mapeamento de tabela pública

As tabelas abaixo mapeiam os campos das tabelas públicas do EFE para os tipos e campos de opções de segmentação existentes na API Display & Video 360. Embora o valor de um campo possa ser mapeado para outro, isso não garante que eles usem o mesmo tipo de dados, valores de enumeração ou espaço de ID.

Coleção de apps

Recuperável no tipo de segmentação TARGETING_TYPE_APP_CATEGORY.

Nome do campo ERF	Disponibilidade da API DV360
id	TargetingOption.targetingOptionId .
name	TargetingOption.appCategoryDetails.displayName .

Navegador

Recuperável no tipo de segmentação TARGETING_TYPE_BROWSER.

Nome do campo ERF	Disponibilidade da API DV360
id	TargetingOption.targetingOptionId .
is_mobile	Indisponível.
name	TargetingOption.browserDetails.displayName .

DataPartner

Não há recursos ou campos equivalentes disponíveis na API Display & Video 360.

DeviceCriteria

Recuperável nos tipos de segmentação TARGETING_TYPE_OPERATING_SYSTEM, TARGETING_TYPE_DEVICE_MAKE_MODEL e TARGETING_TYPE_DEVICE_TYPE.

Nome do campo ERF	Disponibilidade da API DV360
id	Campo TargetingOption.targetingOptionId ou enumeração DeviceType .
is_mobile	Indisponível.
name	TargetingOption.operatingSystemDetails.displayName , o campo TargetingOption.deviceMakeModelDetails.displayName ou a enumeração DeviceType , dependendo do tipo de segmentação.
criteria_type	TargetingOption.targetingType .
operating_system_id	Indisponível.
mobile_brand_name	Indisponível.
mobile_model_name	Indisponível.
mobile_make_model_id	Indisponível.
device_type	DeviceType .

GeoLocation

Recuperável no tipo de segmentação TARGETING_TYPE_GEO_REGION.

Nome do campo ERF	Disponibilidade da API DV360
id	TargetingOption.targetingOptionId .
canonical_name	TargetingOption.geoRegionDetails.displayName .
geo_name	Indisponível.
country_code	Indisponível.
region_code	Indisponível.
city_name	Indisponível.
postal_name	Indisponível.
dma_code	Indisponível.

Isp (link em inglês)

Recuperável no tipo de segmentação TARGETING_TYPE_CARRIER_AND_ISP.

Nome do campo ERF	Disponibilidade da API DV360
id	TargetingOption.targetingOptionId .
is_mobile	Indisponível.
name	TargetingOption.carrierAndIspDetails.displayName .
secondary_criteria_id	TargetingOption.targetingOptionId .

Idioma

Recuperável no tipo de segmentação TARGETING_TYPE_LANGUAGE.

Nome do campo ERF	Disponibilidade da API DV360
id	TargetingOption.targetingOptionId .
name	Indisponível. O nome de exibição completo de um idioma está disponível no campo TargetingOption.languageDetails.displayName .

SiteToPlacementId

Não há recursos ou campos equivalentes disponíveis na API Display & Video 360.

SupportedExchange

Recuperável no tipo de segmentação TARGETING_TYPE_EXCHANGE.

Nome do campo ERF	Disponibilidade da API DV360
id	Exchange .
name	Exchange .

UniversalSite

Não há recursos ou campos equivalentes disponíveis na API Display & Video 360. Sites e apps individuais podem ser segmentados diretamente nos tipos de segmentação TARGETING_TYPE_URL e TARGETING_TYPE_APP, respectivamente. No Display & Video 360, qualquer app ou URL pode ser segmentado, mas nem todos eles podem ser incluídos em relatórios. Se você quiser remover apps e URLs que não podem ser incluídos em relatórios de gastos, siga as instruções na Central de Ajuda do DV360.

Mapeamento de campo da tabela particular

As tabelas abaixo mapeiam os campos das tabelas particulares do ERF para campos ou serviços existentes na API Display & Video 360. Embora o valor de um campo possa ser mapeado para outro, isso não garante que eles usem o mesmo tipo de dados, valores de enumeração ou espaço de ID.

Anunciante

Nome do campo ERF	Disponibilidade da 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 .
currency_code	Advertiser.generalConfig.currencyCode .
timezone_code	Advertiser.generalConfig.timeZone .
landing_page_url	Advertiser.generalConfig.domainUrl .
available_channel_ids	Recuperável pelo método advertisers.channels.list .
blacklist_channel_id	Recuperável pelo método advertisers.targetingTypes.assignedtargetingOptions.list no tipo de segmentação TARGETING_TYPE_CHANNEL . Se AssignedTargetingOption.channelDetails.negative for verdadeiro, o canal terá uma segmentação negativa.
dcm_configuration	Indisponível.
dcm_network_id	Advertiser.adServerConfig.cmHybridConfig.cmAccountId .
dcm_advertiser_id	O campo Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds lista os IDs dos anunciantes do CM360 que compartilham a configuração do Floodlight do CM360.
dcm_floodlight_group_id	Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId .
dcm_syncable_site_ids	Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds .
enable_oba_tags	Indisponível.

Campaign

Nome do campo ERF	Disponibilidade da API DV360
common_data.id	Campaign.campaignId .
common_data.name	Campaign.displayName .
common_data.active	Campaign.entityStatus .
common_data.integration_code	Indisponível.
advertiser_id	Campaign.advertiserId .
budget	Campos Campaign.campaignFlight e Campaign.campaignBudgets .
frequency_cap	Campaign.frequencyCap .
default_target_list	Recuperável pelo método advertisers.campaigns.bulkListCampaignAssignedTargetingOptions .
uses_video_creatives	Indisponível.
uses_display_creatives	Indisponível.
uses_audio_creatives	Indisponível.
objetivo	Campaign.campaignGoal.campaignGoalType .
metric	Campaign.campaignGoal.performanceGoal.performanceGoalType .
objective_description	Campaign.campaignGoal.performanceGoal.performanceGoalString .
metric_amount_micros	Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros .

Criativo

Nome do campo ERF	Disponibilidade da API 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

Nome do campo ERF	Disponibilidade da API DV360
id	CustomList.customListId .
name	CustomList.displayName .
descrição	Indisponível.
advertiser_id	Indisponível.

FloodlightActivity

Nome do campo ERF	Disponibilidade da API DV360
common_data.id	FloodlightActivity.floodlightActivityId .
common_data.name	FloodlightActivity.displayName .
common_data.active	FloodlightActivity.servingStatus .
common_data.integration_code	Indisponível.
advertiser_id	O campo FloodlightActivity.advertiserIds lista todos os anunciantes com acesso à atividade do Floodlight no parceiro especificado.
partner_id	Fornecido pelo usuário ao fazer uma solicitação para o serviço floodlightGroups.floodlightActivities.
remarketing_enabled	O campo FloodlightActivity.remarketingConfigs lista essa configuração para cada anunciante com acesso à atividade do Floodlight no parceiro especificado.
ssl_required	FloodlightActivity.sslRequired .

InsertionOrder

Nome do campo ERF	Disponibilidade da API 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	Indisponível. Pode ser calculado usando o conteúdo do campo InsertionOrder.budget.budgetSegments .
scheduled_segments	InsertionOrder.budget.budgetSegments .
frequency_cap	InsertionOrder.frequencyCap .
default_partner_costs	InsertionOrder.partnerCosts .
default_target_list	Recuperável pelo método advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions .

InventorySource

Nome do campo ERF	Disponibilidade da API DV360
id	InventorySource.inventorySourceId .
sem classificação	Indisponível.
inventory_name	InventorySource.displayName .
exchange_id	InventorySource.exchange .
accessing_advertisers	Campos InventorySource.readWriteAccessors e InventorySource.readAdvertiserIds .
external_id	InventorySource.dealId .
min_cpm_micros	InventorySource.rateDetails.rate.nanos , dependendo do valor do campo InventorySource.rateDetails.inventorySourceRateType .
min_cpm_currency_code	InventorySource.rateDetails.rate.currencyCode .

LineItem

Nome do campo ERF	Disponibilidade da 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 .
insertion_order_id	LineItem.insertionOrderId .
creative_ids	LineItem.creativeIds .
max_cpm_advertiser_micros	Campos LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros ou LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros , dependendo do esquema de estratégia usado.
performance_goal	Campos LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType ou LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType , dependendo do esquema de estratégia usado.
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	LineItem.budget.maxAmount campo se LineItem.budget.budgetUnit for BUDGET_UNIT_IMPRESSIONS .
budget.max_spend_advertiser_micros	LineItem.budget.maxAmount campo se LineItem.budget.budgetUnit for 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	Recuperável pelo método advertisers.lineItems.bulkListLineItemAssignedTargetingOptions .

NegativeKeywordList

Nome do campo ERF	Disponibilidade da API DV360
id	NegativeKeywordList.negativeKeywordListId .
name	NegativeKeywordList.displayName .
advertiser_id	NegativeKeywordList.advertiserId .

Parceiro

Nome do campo ERF	Disponibilidade da API DV360
common_data.id	Partner.partnerId .
common_data.name	Partner.displayName .
common_data.active	Partner.entityStatus .
common_data.integration_code	Indisponível.
currency_code	Partner.generalConfig.currencyCode .
exchange_settings	Partner.exchangeConfig.enabledExchanges .
default_partner_costs	Indisponível.
default_partner_revenue	Indisponível.
default_target_list	Indisponível.

Pixel

Não há recursos ou campos equivalentes disponíveis na API Display & Video 360.

UniversalChannel

Nome do campo ERF	Disponibilidade da API DV360
id	Channel.channelId .
name	Channel.displayName .
site_ids	Recuperável com os métodos advertisers.channels.sites.list e partners.channels.sites.list , dependendo do tipo de owner .
accessing_advertisers	Indisponível.
is_deleted	Indisponível.
is_brand_safe_channel	Indisponível.

UserList

Nome do campo ERF	Disponibilidade da API DV360
id	FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId .
name	FirstAndThirdPartyAudience.displayName .
data_partner_id	Indisponível.
accessing_advertisers	Indisponível.
partner_pricing	Indisponível.
advertiser_pricings	Indisponível.