Display e L'API Video 360 v2 verrà ritirata. Utilizza Display e ma l'API Video 360 v3. Per istruzioni sulla migrazione da v2 a v3, consulta la nostra guida alla migrazione.

Questa pagina è stata tradotta dall'API Cloud Translation.

Esegui la migrazione da file di lettura entità

I file per la lettura delle entità (ERF) sono rappresentazioni JSON degli oggetti della campagna di un partner resi disponibili tramite Google Cloud Storage.

Le ERF sono state ritirate a giugno 2021 e non saranno più disponibili a partire dal 31 ottobre 2024. Gli ERF non vengono più generati. Utilizza l'API Display & Video 360 per recuperare le risorse di Display & Video 360.

Questa guida illustra come eseguire la migrazione dai file di lettura delle entità all'API Display & Video 360:

Fornire una panoramica delle differenze tra le due interfacce
Confronto tra tabelle ERF e servizi API
Fornire indicazioni sul recupero delle entità tramite l'API
Riconoscere le lacune nei dati esistenti
Presentazione di una mappatura di tutti i campi ERF ai campi delle risorse API paragonabili

Panoramica

Quando esegui la migrazione dalle ERF all'API Display & Video 360, devi prendere in considerazione una serie di differenze chiave, tra cui:

Aggiornamento dei dati. I file ERF vengono generati quotidianamente e collettivamente mentre l'API recupera la versione più aggiornata di una risorsa.
Struttura delle risorse. L'API utilizza strutture JSON diverse da ERF per rappresentare gli stessi tipi di risorse. Alcune risorse, come le impostazioni di targeting pubblico, potrebbero utilizzare uno spazio ID diverso.
Metodo di recupero. L'API Display & Video 360 consente di recuperare le risorse solo singolarmente, in elenchi paginati o tramite trasferimenti di dati BigQuery, a differenza dei file JSON non elaborati forniti da ERF.
Ambito. A differenza degli ERF, il cui ambito è definito dall'ID partner, la maggior parte delle risorse API è definita dall'ID inserzionista. Le risorse incluse nelle risposte sono limitate alle risorse all'interno di questo ambito.

Rappresentazione dei dati ERF nell'API

I file per la lettura delle entità sono suddivisi in tabelle "Pubblico" e "Privato". Le tabelle pubbliche forniscono informazioni disponibili e applicabili a tutti gli utenti, ad esempio i valori di targeting. Le tabelle private forniscono dati specifici per un partner, come le risorse di creatività o di elementi pubblicitari.

L'API Display &Video 360 non utilizza questa dicotomia, rendendo invece tutte le informazioni recuperabili tramite vari servizi e utilizzando diverse strutture JSON. Questa sezione mette a confronto le informazioni fornite tramite le tabelle ERF pubbliche e private con quelle rese disponibili tramite le risorse e i servizi dell'API Display & Video 360.

Informazioni pubbliche

Le tabelle pubbliche ERF forniscono agli utenti materiali di riferimento da utilizzare quando interpretano le impostazioni di targeting delle risorse private recuperate e assegnano il targeting tramite un sottoinsieme di versioni dei file di dati strutturati (SDF) caricati tramite l'interfaccia utente. Questi materiali di riferimento, gli stessi per tutti gli utenti, sono costituiti da un ID numerico, utilizzato per la mappatura, e da dettagli più descrittivi, come un nome visualizzato.

Quando utilizzi l'API Display & Video 360, le informazioni di riferimento per il targeting possono essere recuperate tramite il servizio targetingTypes.targetingOptions. Analogamente alle tabelle pubbliche, questo servizio fornisce gli ID e i dettagli delle opzioni di targeting per uno specifico tipo di targeting. Consulta la nostra pagina Imposta il targeting per un esempio di codice che mostra il recupero dell'ID opzione di targeting.

SDF e tabelle pubbliche

Prima della versione 7 di SDF, i file di lettura delle entità e i file di dati strutturati utilizzano lo stesso spazio ID per le impostazioni di targeting. Se sei un utente di SDF che utilizza le tabelle pubbliche ERF per interpretare o assegnare le impostazioni di targeting utilizzando SDF, puoi scaricare questo materiale di riferimento in formato CSV tramite l'interfaccia utente di Display & Video 360.

A partire dalla versione 7, gli spazi ID utilizzati da un sottoinsieme di colonne dei file di dati strutturati sono stati aggiornati per separare l'SDF dai file ERF ed essere ulteriormente allineati con l'API Display &Video 360. Per ulteriori informazioni, consulta la guida alla migrazione alla versione 7 e la documentazione di riferimento.

Risorse private

Le tabelle private ERF forniscono uno snapshot giornaliero delle impostazioni attuali delle risorse private di proprietà di un partner. A causa dell'enorme volume di risorse che è possibile creare in un unico partner, questi file possono diventare molto grandi e difficili da scaricare ed elaborare.

Nell'API, ogni tabella privata ha un servizio corrispondente che fornisce endpoint per il recupero e la gestione del tipo di risorsa. Le risorse possono essere recuperate in blocco utilizzando il rispettivo metodo di elenco di ciascun servizio. La struttura JSON per ogni risorsa è diversa nell'API rispetto all'ERF, in quanto utilizza nomi di campi e risorse condivise diversi.

Alcune informazioni disponibili nella rappresentazione ERF di una risorsa, ad esempio le impostazioni di targeting assegnate di una risorsa o i siti di un canale, sono rappresentate nell'API come elementi secondari della risorsa originale e devono essere recuperate tramite richieste API aggiuntive.

Recupero di entità nell'API

Le risorse Display & Video 360 possono essere recuperate tramite richieste dirette all'API o tramite importazioni automatiche in BigQuery.

Richieste API dirette

Ogni tipo di risorsa è recuperabile tramite un servizio API diverso. Le risorse possono essere recuperate singolarmente o collettivamente utilizzando rispettivamente il metodo get o list del servizio appropriato. Alcune proprietà importanti dei metodi di elenco dell'API Display &Video 360 includono:

Ambito obbligatorio. A differenza degli ERF, il cui ambito è definito in base al partner, la maggior parte delle risorse nell'API è definita in base all'inserzionista. Il recupero di tutto un tipo di risorsa, ad esempio gli elementi pubblicitari, per un partner potrebbe richiedere una singola richiesta di elenco per ogni inserzionista secondario di quel partner. Le eccezioni includono i canali secondari diretti di un partner, come gli inserzionisti e i canali di proprietà del partner.
Impaginazione. I metodi di elenco dell'API utilizzano la paginazione per garantire che le risposte abbiano dimensioni ragionevoli, limitando la maggior parte delle risposte o delle pagine delle singole richieste a 100 risorse. Se il numero di risorse pertinenti supera la dimensione della pagina, le chiamate all'elenco consecutive sono necessarie per recuperare le pagine successive della risposta completa dell'elenco. Un esempio di codice che esegue il paging di una risposta elenco è disponibile in una sezione della pagina della guida sul targeting relativa al recupero delle opzioni di targeting disponibili .
Sono necessarie ulteriori richieste per il recupero del targeting. Le impostazioni di targeting di una risorsa non sono incluse nell'oggetto JSON dell'API, ma sono risorse figlio note come opzioni di targeting assegnate. Queste risorse secondarie devono essere recuperate tramite una richiesta separata. Ad esempio, per ogni elemento pubblicitario recuperato tramite una richiesta advertisers.lineItems.list, è necessario effettuare una richiesta advertisers.lineItems.bulkListAssignedTargetingOptions separata per recuperare tutte le informazioni di targeting.

Ottimizza il recupero delle risorse

L'API Display & Video 360 potrebbe richiedere più richieste per recuperare la stessa quantità di informazioni disponibili in un singolo file di lettura delle entità. L'ottimizzazione del modo in cui recupero le risorse può aiutarti a recuperare i dati di cui hai bisogno in modo più efficiente:

Invia richieste in parallelo all'API. L'API Display & Video 360 protegge l'infrastruttura utilizzando limiti di frequenza delle richieste per inserzionista e per progetto. Questa struttura di quote ti consente di implementare una soluzione multithread per più inserzionisti che riduce il tempo totale necessario per recuperare tutte le risorse necessarie. Sebbene la paginazione requira che tutte le risorse di un tipo all'interno di un determinato ambito vengano recuperate tramite chiamate consecutive, il recupero delle risorse all'interno di un altro ambito o di un altro tipo può essere eseguito contemporaneamente.
Utilizza i filtri e i parametri di ordinamento nelle chiamate di elenco per recuperare solo le risorse pertinenti. Ad esempio, se ti interessano solo gli elementi pubblicitari aggiornati nell'ultimo giorno, puoi utilizzare il parametro filter del metodo advertisers.lineItems.list per restituire solo gli elementi pubblicitari con un valore updateTime maggiore di un determinato timestamp. In questo modo, puoi ridurre notevolmente il numero di richieste da effettuare.
Memorizza nella cache gli ID usati regolarmente per evitare richieste API non necessarie. Alcune informazioni di riferimento, come gli ID opzioni di targeting e gli ID segmento di pubblico di Google, sono relativamente stabili e possono essere archiviate in modo sicuro per evitare di doverle recuperare a ogni utilizzo. Tuttavia, i valori memorizzati nella cache devono essere controllati su base settimanale per tenere conto di modifiche o ritiri non frequenti.

Per saperne di più su come accedere in modo efficiente all'API Display & Video 360, consulta la nostra guida all'ottimizzazione delle quote.

Importazione in BigQuery

Il connettore BigQuery dell'API Display &Video 360 consente di importare automaticamente le configurazioni di risorse di Display &Video 360 direttamente in BigQuery su base giornaliera. Le configurazioni vengono archiviate in BigQuery utilizzando il design delle risorse dell'API Display & Video 360. È supportato un sottoinsieme di risorse API.

Per ulteriori informazioni sull'utilizzo del connettore BigQuery dell'API Display & Video 360, consulta la seguente documentazione sul cloud:

Lacune nei dati delle API note

Esistono notevoli lacune nei dati che potresti riscontrare durante la migrazione dall'ERF all'API Display & Video 360, ad esempio:

Ordini di inserzione di tipo Storia. Gli ordini di inserzione di tipo Storia non sono recuperabili tramite l'API e devono essere recuperati tramite l'interfaccia utente di Display & Video 360.
Un sottoinsieme di campi delle risorse. Un numero limitato di campi delle risorse presenti gli oggetti ERF non sono disponibili nelle risorse corrispondenti recuperate tramite l'API Display & Video 360.

Appendice: mappatura dei campi ERF all'API

Mapping di tabelle pubbliche

Le tabelle riportate di seguito mappano i campi delle tabelle pubbliche ERF ai tipi di targeting esistenti e ai campi delle opzioni di targeting nell'API Display & Video 360. Sebbene il valore di un campo possa essere mappato a un altro, non è garantito che utilizzino lo stesso tipo di dati, gli stessi valori enumerati o lo stesso spazio ID.

Raccolta di app

Recuperabile in base al tipo di targeting TARGETING_TYPE_APP_CATEGORY.

Nome campo ERF	Disponibilità dell'API DV360
id	`TargetingOption.targetingOptionId` .
nome	`TargetingOption.appCategoryDetails.displayName` .

Browser

Recuperabile in base al tipo di targeting TARGETING_TYPE_BROWSER.

Nome campo ERF	Disponibilità dell'API DV360
id	`TargetingOption.targetingOptionId` .
is_mobile	Non disponibile.
nome	`TargetingOption.browserDetails.displayName` .

DataPartner

Non sono disponibili campi o risorse equivalenti nell'API Display &Video 360.

DeviceCriteria

Recuperabile nei tipi di targeting TARGETING_TYPE_OPERATING_SYSTEM, TARGETING_TYPE_DEVICE_MAKE_MODEL e TARGETING_TYPE_DEVICE_TYPE.

Nome campo ERF	Disponibilità dell'API DV360
id	`TargetingOption.targetingOptionId` o `DeviceType` enum.
is_mobile	Non disponibile.
nome	Campo `TargetingOption.operatingSystemDetails.displayName` , `TargetingOption.deviceMakeModelDetails.displayName` o `DeviceType` enum, a seconda del tipo di targeting.
criteria_type	`TargetingOption.targetingType` .
operating_system_id	Non disponibile.
mobile_brand_name	Non disponibile.
mobile_model_name	Non disponibile.
mobile_make_model_id	Non disponibile.
device_type	`DeviceType` enum.

GeoLocation

Recuperabile in base al tipo di targeting TARGETING_TYPE_GEO_REGION.

Nome campo ERF	Disponibilità dell'API DV360
id	`TargetingOption.targetingOptionId` .
canonical_name	`TargetingOption.geoRegionDetails.displayName` .
geo_name	Non disponibile.
country_code	Non disponibile.
region_code	Non disponibile.
city_name	Non disponibile.
postal_name	Non disponibile.
dma_code	Non disponibile.

Isp

Recuperabile nel tipo di targeting TARGETING_TYPE_CARRIER_AND_ISP.

Nome campo ERF	Disponibilità dell'API DV360
id	`TargetingOption.targetingOptionId` .
is_mobile	Non disponibile.
nome	`TargetingOption.carrierAndIspDetails.displayName` .
secondary_criteria_id	`TargetingOption.targetingOptionId` .

Lingua

Recuperabile in base al tipo di targeting TARGETING_TYPE_LANGUAGE.

Nome campo ERF	Disponibilità dell'API DV360
id	`TargetingOption.targetingOptionId` .
nome	Non disponibile. Il nome visualizzato completo di una lingua è disponibile nel campo `TargetingOption.languageDetails.displayName` .

SiteToPlacementId

Non sono disponibili risorse o campi equivalenti nell'API Display & Video 360.

SupportedExchange

Recuperabile in base al tipo di targeting TARGETING_TYPE_EXCHANGE.

Nome campo ERF	Disponibilità dell'API DV360
id	`Exchange` enum.
nome	`Exchange` enum.

UniversalSite

Non sono disponibili risorse o campi equivalenti nell'API Display & Video 360. I singoli siti e le singole app possono essere scelti come target direttamente nei tipi di targeting TARGETING_TYPE_URL e TARGETING_TYPE_APP. In Display & Video 360, qualsiasi app o URL può essere scelto come target, ma non tutti possono essere oggetto di report. Se vuoi impedire che app e URL non segnalabili spendano, segui le istruzioni nel Centro assistenza DV360.

Mappatura dei campi delle tabelle private

Le seguenti tabelle mappano i campi delle tabelle private ERF a campi o servizi esistenti nell'API Display &Video 360. Sebbene il valore di un campo possa essere mappato a un altro, ciò non garantisce che utilizzino lo stesso tipo di dati, gli stessi valori enumerati o lo stesso spazio ID.

Inserzionista

Nome campo ERF	Disponibilità dell'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	Recuperabile tramite il metodo `advertisers.channels.list` .
blacklist_channel_id	Recuperabile tramite `advertisers.targetingTypes.assignedtargetingOptions.list` metodo nel tipo di targeting `TARGETING_TYPE_CHANNEL` . Se `AssignedTargetingOption.channelDetails.negative` è true, il canale è scelto come target negativo.
dcm_configuration	Non disponibile.
dcm_network_id	`Advertiser.adServerConfig.cmHybridConfig.cmAccountId` .
dcm_advertiser_id	Il campo `Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds` elenca gli ID inserzionista CM360 che condividono la configurazione Floodlight CM360.
dcm_floodlight_group_id	`Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId` .
dcm_syncable_site_ids	`Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds` .
enable_oba_tags	Non disponibile.

Campagna

Nome campo ERF	Disponibilità dell'API DV360
common_data.id	`Campaign.campaignId` .
common_data.name	`Campaign.displayName` .
common_data.active	`Campaign.entityStatus` .
common_data.integration_code	Non disponibile.
advertiser_id	`Campaign.advertiserId` .
budget	`Campaign.campaignFlight` e `Campaign.campaignBudgets` .
frequency_cap	`Campaign.frequencyCap` .
default_target_list	Recuperabile tramite il metodo `advertisers.campaigns.bulkListCampaignAssignedTargetingOptions` .
uses_video_creatives	Non disponibile.
uses_display_creatives	Non disponibile.
uses_audio_creatives	Non disponibile.
scopo	`Campaign.campaignGoal.campaignGoalType` .
metrica	`Campaign.campaignGoal.performanceGoal.performanceGoalType` .
objective_description	`Campaign.campaignGoal.performanceGoal.performanceGoalString` .
metric_amount_micros	`Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros` .

Creatività

Nome campo ERF	Disponibilità dell'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 campo ERF	Disponibilità dell'API DV360
id	`CustomList.customListId` .
nome	`CustomList.displayName` .
descrizione	Non disponibile.
advertiser_id	Non disponibile.

FloodlightActivity

Nome campo ERF	Disponibilità dell'API DV360
common_data.id	`FloodlightActivity.floodlightActivityId` .
common_data.name	`FloodlightActivity.displayName` .
common_data.active	`FloodlightActivity.servingStatus` .
common_data.integration_code	Non disponibile.
advertiser_id	Il campo `FloodlightActivity.advertiserIds` elenca tutti gli inserzionisti con accesso all'attività Floodlight del partner specificato.
partner_id	Fornito dall'utente quando effettua una richiesta al servizio `floodlightGroups.floodlightActivities`.
remarketing_enabled	Il campo `FloodlightActivity.remarketingConfigs` elenca questa configurazione per ogni inserzionista con accesso all'attività Floodlight per il partner specificato.
ssl_required	`FloodlightActivity.sslRequired` .

InsertionOrder

Nome campo ERF	Disponibilità dell'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	Non disponibile. Può essere calcolato utilizzando i contenuti del campo `InsertionOrder.budget.budgetSegments` .
scheduled_segments	`InsertionOrder.budget.budgetSegments` .
frequency_cap	`InsertionOrder.frequencyCap` .
default_partner_costs	`InsertionOrder.partnerCosts` .
default_target_list	Recuperabile tramite il metodo `advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions` .

InventorySource

Nome campo ERF	Disponibilità dell'API DV360
id	`InventorySource.inventorySourceId` .
non classificato	Non disponibile.
inventory_name	`InventorySource.displayName` .
exchange_id	`InventorySource.exchange` .
accessing_advertisers	`InventorySource.readWriteAccessors` e `InventorySource.readAdvertiserIds` .
external_id	`InventorySource.dealId` .
min_cpm_micros	`InventorySource.rateDetails.rate.nanos` , a seconda del valore del campo `InventorySource.rateDetails.inventorySourceRateType` .
min_cpm_currency_code	`InventorySource.rateDetails.rate.currencyCode` .

LineItem

Nome campo ERF	Disponibilità dell'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	`LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros` o `LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros` , a seconda dello schema di strategia utilizzato.
performance_goal	`LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType` o `LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType` , a seconda dello schema di strategia utilizzato.
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` se `LineItem.budget.budgetUnit` è `BUDGET_UNIT_IMPRESSIONS` .
budget.max_spend_advertiser_micros	`LineItem.budget.maxAmount` se `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` .
target_list	Recuperabile tramite il metodo `advertisers.lineItems.bulkListLineItemAssignedTargetingOptions` .

NegativeKeywordList

Nome campo ERF	Disponibilità dell'API DV360
id	`NegativeKeywordList.negativeKeywordListId` .
nome	`NegativeKeywordList.displayName` .
advertiser_id	`NegativeKeywordList.advertiserId` .

Partner

Nome campo ERF	Disponibilità dell'API DV360
common_data.id	`Partner.partnerId` .
common_data.name	`Partner.displayName` .
common_data.active	`Partner.entityStatus` .
common_data.integration_code	Non disponibile.
currency_code	`Partner.generalConfig.currencyCode` .
exchange_settings	`Partner.exchangeConfig.enabledExchanges` .
default_partner_costs	Non disponibile.
default_partner_revenue	Non disponibile.
default_target_list	Non disponibile.

Pixel

Non sono disponibili campi o risorse equivalenti nell'API Display &Video 360.

UniversalChannel

Nome campo ERF	Disponibilità dell'API DV360
id	`Channel.channelId` .
nome	`Channel.displayName` .
site_ids	Recuperabile tramite metodi `advertisers.channels.sites.list` e `partners.channels.sites.list` , a seconda del tipo di `owner` .
accessing_advertisers	Non disponibile.
is_deleted	Non disponibile.
is_brand_safe_channel	Non disponibile.

UserList

Nome campo ERF	Disponibilità dell'API DV360
id	`FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId` .
nome	`FirstAndThirdPartyAudience.displayName` .
data_partner_id	Non disponibile.
accessing_advertisers	Non disponibile.
partner_pricing	Non disponibile.
advertiser_pricings	Non disponibile.