Rede de Display e A API Video 360 v2 foi descontinuada. Use o Display & Video 360 API v3. Para ver as instruções de migração da v2 para a v3, consulte nosso guia de migração.

Esta página foi traduzida pela API Cloud Translation.

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.

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.

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:

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.