Migrar de arquivos da leitura de entidades

Os arquivos da leitura de entidades foram desativados.

Os arquivos de leitura de entidade (ERFs, na sigla em inglês) são representações JSON dos objetos de campanha de um parceiro disponibilizados pelo Google Cloud Storage.

O uso de ERFs foi descontinuado em junho de 2021, e a desativação vai ocorrer em 31 de outubro de 2024. As ERFs não são mais geradas. Use a API Display & Video 360 para recuperar recursos do Display & Video 360.

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

• Apresentar uma visão geral das diferenças entre as duas interfaces
• Comparação das tabelas de ERF com os serviços de API
• Como receber orientações sobre a recuperação de entidades pela API
• Reconhecer as lacunas de dados
• Apresentar um mapeamento de todos os campos de ERF para campos de recursos de API comparáveis

Visão geral

Ao migrar de ERFs para a API Display & Video 360, há várias diferenças importantes a serem consideradas, 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 das do ERF para representar os mesmos tipos de recursos. Alguns recursos, como as 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 pela ERF.
• Escopo. Ao contrário dos ERFs, que são delimitados pelo ID do parceiro, a maioria dos recursos da API é delimitada pelo ID do anunciante. Os recursos incluídos nas respostas são limitados aos recursos dentro desse escopo.

Representação de dados de ERF na API

Os arquivos de leitura de entidades são separados em tabelas "Pública" e "Privada". 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 pelas 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 ERF fornecem materiais de referência para os usuários usarem ao interpretar as configurações de segmentação dos recursos privados recuperados e atribuir a segmentação por meio de um subconjunto de versões de arquivos de dados estruturados (SDFs) enviados pela interface. Esses materiais de referência são iguais 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 das tabelas públicas de ERF precisam ser recuperadas novamente 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. Assim como as tabelas públicas, esse serviço fornece os IDs e detalhes das opções de segmentação para um tipo específico. Consulte nossa página Definir segmentação para conferir 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 para todos os anunciantes.

Tabelas públicas e SDFs

Antes da SDF v7, os arquivos de leitura de entidade e os arquivos de dados estruturados usavam o mesmo espaço de ID para as configurações de segmentação. Se você for um usuário de SDF que usa tabelas públicas de ERF para interpretar ou atribuir configurações de segmentação usando SDF, faça o download desse material de referência em formato CSV pela 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 desvincular o SDF dos ERFs e se alinhar ainda mais à API Display & Video 360. Consulte o guia de migração da v7 e a documentação de referência para mais informações.

Recursos privados

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

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 método de lista de cada serviço. A estrutura JSON de cada recurso é diferente na API em comparação com a ERF, usando nomes de campo e recursos compartilhados diferentes.

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

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 um serviço de API diferente. Os recursos podem ser recuperados individualmente ou em massa usando o método de busca ou lista 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 são definidos por parceiro, a maioria dos recursos na API é definida por anunciante. A recuperação de todos os tipos de recursos, como itens de linha, em um parceiro pode exigir uma solicitação de lista individual para cada anunciante filho desse parceiro. As exceções incluem filhos diretos de um parceiro, como anunciantes e canais de propriedade do parceiro.
• Paginação. Os métodos de lista de API usam a paginação para garantir que as respostas tenham um tamanho razoável, limitando a maioria das respostas de solicitação individuais ou páginas a 100 recursos. Se o número de recursos relevantes for maior que o tamanho da página, serão necessárias chamadas de lista consecutivas para extrair as páginas subsequentes da resposta de lista completa. Um exemplo de código de paginação de uma resposta de lista é fornecido em uma seção do nosso guia de segmentação sobre a recuperação das opções de segmentação disponíveis .
• Solicitação extra necessária para a recuperação da segmentação. As configurações de segmentação de um recurso não sã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 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 extrair a mesma quantidade de informações disponíveis em um único arquivo de leitura de entidades. Otimizar a forma de extrair recursos pode ajudar a recuperar os dados necessários com mais eficiência:

• Fazer solicitações simultâneas à API. A API Display & Video 360 protege a infraestrutura usando limites de taxa de solicitações por projeto e por anunciante. Essa estrutura de cota permite implementar uma solução com vários threads 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 um 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ó tiver interesse em itens de linha que foram atualizados no último dia, use o parâmetro filter do método advertisers.lineItems.list para retornar apenas 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 armazenados em cache precisam ser verificados semanalmente para considerar mudanças ou descontinuações pouco frequentes.

Consulte nosso guia de otimização de cota 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, você pode importar automaticamente as configurações de recursos do Display & Video 360 diretamente para o BigQuery diariamente. 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 de API.

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

• O que é um 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 conhecidas da API

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

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

Apêndice: como mapear campos de ERF para a API

Mapeamento de tabelas públicas

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

Coleção de apps

Pode ser recuperado no tipo de segmentação TARGETING_TYPE_APP_CATEGORY.

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

Navegador

Pode ser recuperada no tipo de segmentação TARGETING_TYPE_BROWSER.

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

DataPartner

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

DeviceCriteria

Pode ser recuperado 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 tipo enumerado DeviceType .
is_mobile	Indisponível.
nome	TargetingOption.operatingSystemDetails.displayName , TargetingOption.deviceMakeModelDetails.displayName ou DeviceType , dependendo do tipo de segmentação.
criteria_type	Campo 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 tipo enumerado.

GeoLocation

Pode ser recuperada no tipo de segmentação TARGETING_TYPE_GEO_REGION.

Nome do campo ERF	Disponibilidade da API DV360
id	Campo TargetingOption.targetingOptionId .
canonical_name	Campo 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

Pode ser recuperada no tipo de segmentação TARGETING_TYPE_CARRIER_AND_ISP.

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

Idioma

Pode ser recuperada no tipo de segmentação TARGETING_TYPE_LANGUAGE.

Nome do campo ERF	Disponibilidade da API DV360
id	Campo TargetingOption.targetingOptionId .
nome	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

Pode ser recuperada no tipo de segmentação TARGETING_TYPE_EXCHANGE.

Nome do campo ERF	Disponibilidade da API DV360
id	Exchange tipo enumerado.
nome	Exchange tipo enumerado.

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 podem ser incluídos em relatórios. Se você quiser remover apps e URLs não denunciáveis dos gastos, siga as instruções na Central de Ajuda do DV360.

Mapeamento de campo de tabela particular

As tabelas abaixo mapeiam os campos das tabelas privadas de 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	Campo Advertiser.advertiserId .
common_data.name	Campo Advertiser.displayName .
common_data.active	Campo Advertiser.entityStatus .
common_data.integration_code	Campo Advertiser.integrationDetails.integrationCode .
partner_id	Campo Advertiser.partnerId .
currency_code	Campo Advertiser.generalConfig.currencyCode .
timezone_code	Campo Advertiser.generalConfig.timeZone .
landing_page_url	Campo Advertiser.generalConfig.domainUrl .
available_channel_ids	Recuperável pelo método advertisers.channels.list .
blacklist_channel_id	Pode ser recuperado pelo método advertisers.targetingTypes.assignedtargetingOptions.list no tipo de segmentação TARGETING_TYPE_CHANNEL . Se AssignedTargetingOption.channelDetails.negative for verdadeiro, o canal está sendo alvo de segmentação negativa.
dcm_configuration	Indisponível.
dcm_network_id	Campo 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	Campo Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId .
dcm_syncable_site_ids	Campo Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds .
enable_oba_tags	Indisponível.

Campanha

Nome do campo ERF	Disponibilidade da API DV360
common_data.id	Campo Campaign.campaignId .
common_data.name	Campo Campaign.displayName .
common_data.active	Campo Campaign.entityStatus .
common_data.integration_code	Indisponível.
advertiser_id	Campo Campaign.advertiserId .
orçamento	Campos Campaign.campaignFlight e Campaign.campaignBudgets .
frequency_cap	Campo Campaign.frequencyCap .
default_target_list	Indisponível
uses_video_creatives	Indisponível.
uses_display_creatives	Indisponível.
uses_audio_creatives	Indisponível.
objetivo	Campo Campaign.campaignGoal.campaignGoalType .
métrica	Campo Campaign.campaignGoal.performanceGoal.performanceGoalType .
objective_description	Campo Campaign.campaignGoal.performanceGoal.performanceGoalString .
metric_amount_micros	Campo Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros .

Criativo

Nome do campo ERF	Disponibilidade da API DV360
common_data.id	Campo Creative.creativeId .
common_data.name	Campo Creative.displayName .
common_data.active	Campo Creative.entityStatus .
common_data.integration_code	Campo Creative.integrationCode .
advertiser_id	Campo Creative.advertiserId .
dcm_placement_id	Campo Creative.cmPlacementId .
width_pixels	Campo Creative.dimensions.widthPixels .
height_pixels	Campo Creative.dimensions.heightPixels .
approval_status	Campo Creative.reviewStatus .
expanding_direction	Campo Creative.expandingDirection .
creative_type	Campo Creative.creativeType .

CustomAffinity

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

FloodlightActivity

Nome do campo ERF	Disponibilidade da API DV360
common_data.id	Campo FloodlightActivity.floodlightActivityId .
common_data.name	Campo FloodlightActivity.displayName .
common_data.active	Campo 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.
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.
ssl_required	Campo FloodlightActivity.sslRequired .

InsertionOrder

Nome do campo ERF	Disponibilidade da API DV360
common_data.id	Campo InsertionOrder.insertionOrderId .
common_data.name	Campo InsertionOrder.displayName .
common_data.active	Campo InsertionOrder.entityStatus .
common_data.integration_code	Campo InsertionOrder.integrationDetails.integrationCode .
advertiser_id	Campo InsertionOrder.advertiserId .
campaign_id	Campo InsertionOrder.campaignId .
overall_budget	Indisponível. Pode ser calculado usando o conteúdo do campo InsertionOrder.budget.budgetSegments .
scheduled_segments	Campo InsertionOrder.budget.budgetSegments .
frequency_cap	Campo InsertionOrder.frequencyCap .
default_partner_costs	Campo InsertionOrder.partnerCosts .
default_target_list	Indisponível.

InventorySource

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

LineItem

Nome do campo ERF	Disponibilidade da API DV360
common_data.id	Campo LineItem.lineItemId .
common_data.name	Campo LineItem.displayName .
common_data.active	Campo LineItem.entityStatus .
common_data.integration_code	Campo LineItem.integrationDetails.integrationCode .
line_item_type	Campo LineItem.lineItemType .
insertion_order_id	Campo LineItem.insertionOrderId .
creative_ids	Campo LineItem.creativeIds .
max_cpm_advertiser_micros	LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros ou LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros campos, dependendo do esquema de estratégia usado.
performance_goal	LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType ou LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType campos, dependendo do esquema de estratégia usado.
goal_advertiser_micros	Campo LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalAmountMicros .
partner_revenue_model	Campo LineItem.partnerRevenueModel .
cost_tracking_pixels	Campo LineItem.conversionCounting.floodlightActivityConfigs .
budget.start_time_usec	Campo LineItem.flight.dateRange.startDate .
budget.end_time_usec	Campo LineItem.flight.dateRange.endDate .
budget.max_impressions	Campo LineItem.budget.maxAmount se LineItem.budget.budgetUnit for BUDGET_UNIT_IMPRESSIONS .
budget.max_spend_advertiser_micros	Campo LineItem.budget.maxAmount se LineItem.budget.budgetUnit for BUDGET_UNIT_CURRENCY .
budget.pacing_type	Campo LineItem.pacing.pacingPeriod .
budget.pacing_max_impressions	Campo LineItem.pacing.dailyMaxImpressions .
budget.pacing_max_spend_advertiser_micros	Campo LineItem.pacing.dailyMaxMicros .
budget.pacing_distribution	Campo LineItem.pacing.pacingType .
frequency_cap	Campo LineItem.frequencyCap .
partner_costs	Campo LineItem.partnerCosts .
target_list	Recuperável pelo método advertisers.lineItems.bulkListAssignedTargetingOptions .

NegativeKeywordList

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

Parceiro

Nome do campo ERF	Disponibilidade da API DV360
common_data.id	Campo Partner.partnerId .
common_data.name	Campo Partner.displayName .
common_data.active	Campo Partner.entityStatus .
common_data.integration_code	Indisponível.
currency_code	Campo Partner.generalConfig.currencyCode .
exchange_settings	Campo 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	Campo Channel.channelId .
nome	Campo Channel.displayName .
site_ids	Podem ser recuperados pelos 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	Campo FirstPartyAndPartnerAudience.firstPartyAndPartnerAudienceId .
nome	Campo FirstPartyAndPartnerAudience.displayName .
data_partner_id	Indisponível.
accessing_advertisers	Indisponível.
partner_pricing	Indisponível.
advertiser_pricings	Indisponível.