Esegui la migrazione da file di lettura entità

I file di lettura delle entità (ERF) sono rappresentazioni JSON degli oggetti delle campagne di un partner che, su richiesta, vengono generati ogni giorno e resi disponibili tramite Google Cloud Storage.

I programmi ERF sono stati ritirati a giugno 2021. A partire dal 31 ottobre 2024, i ERF verranno ufficialmente ritirati e non verranno più generati. Tutti gli utenti esistenti del file per la lettura delle entità sono invitati a eseguire la migrazione all'API Display & Video 360 per continuare a recuperare le risorse Display & Video 360.

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

• Panoramica delle differenze tra le due interfacce
• Confronto tra tabelle ERF e servizi API
• Guida al recupero delle entità tramite l'API
• Come riconoscere le lacune nei dati esistenti
• presentazione di una mappatura di tutti i campi ERF a campi di risorse API paragonabili

Panoramica

Quando esegui la migrazione dai ERF all'API Display & Video 360, devi considerare una serie di differenze chiave, tra cui:

• Aggiornamento dei dati. I ERF vengono generati ogni giorno e in blocco, mentre l'API recupera la versione più aggiornata di una risorsa.
• Struttura delle risorse. L'API utilizza strutture JSON diverse rispetto a 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 il recupero delle risorse solo singolarmente, in elenchi impaginati o tramite trasferimenti di dati BigQuery, a differenza dei file JSON non elaborati forniti da ERF.
• Ambito. A differenza dei ERF, che sono associati all'ID partner, la maggior parte delle risorse API è limitata all'ID inserzionista. Le risorse incluse nelle risposte sono limitate alle risorse in quell'ambito.

Rappresentazione dei dati ERF nell'API

I file per la lettura delle entità sono separati in tabelle "Pubblica" 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 risorse di creatività o elementi pubblicitari.

L'API Display & Video 360 non utilizza questa dicotomia, ma rende tutte queste informazioni recuperabili tramite vari servizi e utilizzando strutture JSON diverse. Questa sezione confronta le informazioni fornite tramite 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 materiali di riferimento che gli utenti possono utilizzare per interpretare le impostazioni di targeting delle risorse private recuperate e assegnare il targeting tramite un sottoinsieme di versioni di file di dati strutturati (SDF) caricate tramite l'interfaccia utente. Questi materiali di riferimento sono gli stessi per tutti gli utenti e sono costituiti da un ID numerico, utilizzato per la mappatura e da dettagli più descrittivi, ad esempio un nome visualizzato.

Avviso: poiché l'API Display & Video 360 utilizza uno spazio ID diverso per le impostazioni di targeting, tutte le informazioni memorizzate nella cache delle tabelle pubbliche ERF dovranno essere recuperate nuovamente tramite l'API.

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 un tipo di targeting specifico. Consulta la pagina Imposta targeting esistente per un esempio di codice che illustra il recupero dell'ID opzione di targeting.

Nota: sebbene le richieste al servizio targetingTypes.targetingOptions richiedano un ID inserzionista, le informazioni recuperate devono essere identiche per tutti gli inserzionisti.

Tabelle pubbliche e SDF

Prima di SDF v7, i file per la lettura delle entità e i file di dati strutturati utilizzano lo stesso spazio ID per le impostazioni di targeting. Se sei un utente del file SDF che utilizza le tabelle pubbliche di ERF per interpretare o assegnare le impostazioni di targeting tramite 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 disaccoppiare SDF dagli ERF e allinearsi ulteriormente all'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. Grazie all'enorme volume di risorse che è possibile creare sotto un singolo 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 di quel tipo di risorsa. Le risorse possono essere recuperate in blocco utilizzando il rispettivo metodo dell'elenco di ciascun servizio. La struttura JSON di ogni risorsa è diversa nell'API rispetto a ERF, utilizzando nomi di campo e risorse condivise diversi.

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

Recupero delle entità nell'API

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

Richieste API dirette

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

• Ambito obbligatorio. A differenza dei ERF, con ambito partner, l'ambito della maggior parte delle risorse nell'API è inserzionista. Il recupero di un intero tipo di risorsa, ad esempio gli elementi pubblicitari, da un partner può richiedere una singola richiesta di elenco per ogni inserzionista secondario di quel partner. Fanno eccezione i canali secondari diretti di un partner, come gli inserzionisti e i canali di proprietà del partner.
• Impaginazione. I metodi degli elenchi delle API utilizzano l'impaginazione per garantire che le risposte siano di dimensioni ragionevoli, limitando la maggior parte delle risposte alle richieste, o delle singole pagine, a 100 risorse. Se il numero di risorse pertinenti è maggiore della dimensione della pagina, sono necessarie chiamate di elenco consecutive per recuperare le pagine successive della risposta completa dell'elenco. Un esempio di codice del paging di una risposta a un elenco è disponibile in una sezione della nostra pagina della Guida al targeting relativa al recupero delle opzioni di targeting disponibili .
• Richieste aggiuntive necessarie 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 figlio 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 può richiedere più richieste per recuperare la stessa quantità di informazioni disponibili in un singolo file di lettura delle entità. L'ottimizzazione della modalità di recupero delle risorse può aiutarti a recuperare i dati di cui hai bisogno in modo più efficiente:

• Inviare richieste in parallelo all'API. L'API Display & Video 360 protegge l'infrastruttura utilizzando le richieste per inserzionista per limiti di frequenza di progetto. Questa struttura di quota consente di implementare una soluzione multi-thread per più inserzionisti in modo da ridurre il tempo totale necessario per recuperare tutte le risorse necessarie. Sebbene l'impaginazione richieda il recupero di tutte le risorse di un tipo all'interno di un determinato ambito tramite chiamate consecutive, il recupero delle risorse in un altro ambito o in un altro tipo può essere eseguito contemporaneamente.
• Utilizza i filtri e l'ordine in base ai parametri nelle chiamate all'elenco per recuperare solo le risorse pertinenti. Ad esempio, se ti interessano solo gli elementi pubblicitari che sono stati 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. Questo può ridurre notevolmente il numero di richieste da effettuare.
• Memorizza nella cache gli ID utilizzati regolarmente per evitare richieste API non necessarie. Alcune informazioni di riferimento, come gli ID opzioni di targeting e gli ID pubblico di Google, sono relativamente stabili e possono essere archiviate in modo sicuro per evitare di recuperarle a ogni utilizzo. Tuttavia, i valori memorizzati nella cache dovrebbero essere controllati settimanalmente per tenere conto di eventuali modifiche o deprecazioni non frequenti.

Consulta la nostra guida all'ottimizzazione delle quote per ulteriori informazioni su come accedere in modo efficiente all'API Display & Video 360.

Importa in BigQuery

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

Consulta la seguente documentazione cloud per ulteriori informazioni sull'utilizzo del connettore BigQuery dell'API Display & Video 360:

• Che cos'è BigQuery Data Transfer Service?
• Pianificare un trasferimento a Display & Video 360
• Trasformazione dei dati di Display & Video 360

Carenze note nei dati dell'API

Durante la migrazione da ERF all'API Display & Video 360 potresti riscontrare notevoli lacune nei dati, ad esempio:

• Ordini di inserzione di tipo Storia. Gli ordini di inserzione di tipo Storia non possono essere recuperati tramite l'API e devono essere recuperati tramite l'interfaccia utente di Display & Video 360.
• Un sottoinsieme di campi delle risorse. Un numero ridotto di campi delle risorse presenti negli oggetti ERF non è disponibile nelle risorse corrispondenti recuperate tramite l'API Display & Video 360.

Appendice: mappatura dei campi ERF all'API

Mappatura delle 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 campo, ciò non garantisce che venga utilizzato lo stesso tipo di dati, valori di enumerazione o lo stesso spazio ID.

Raccolta di app

Recuperabile nel tipo di targeting TARGETING_TYPE_APP_CATEGORY.

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

Browser

Recuperabile nel 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 risorse o campi 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 nel 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 nel tipo di targeting TARGETING_TYPE_LANGUAGE.

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

SiteToPlacementId

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

SupportedExchange

Recuperabile nel 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. Singoli siti e singole app possono essere scelti come target direttamente nei tipi di targeting TARGETING_TYPE_URL e TARGETING_TYPE_APP, rispettivamente. In Display & Video 360, qualsiasi app o URL può essere scelto come target, ma non tutte le app o gli URL possono essere inclusi nei report. Se vuoi rimuovere dalla spesa le app e gli URL non soggetti a report, segui le istruzioni nel Centro assistenza DV360.

Mappatura dei campi della tabella privata

Le tabelle riportate di seguito 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 venga utilizzato lo stesso tipo di dati, valori di enumerazione 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 il metodo advertisers.targetingTypes.assignedtargetingOptions.list nel tipo di targeting TARGETING_TYPE_CHANNEL . Se AssignedTargetingOption.channelDetails.negative è true, il canale viene 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 nel partner specificato.
partner_id	Fornito dall'utente quando si effettua una richiesta al servizio floodlightGroups.floodlightActivities.
remarketing_enabled	Il campo FloodlightActivity.remarketingConfigs elenca questa configurazione per ogni inserzionista con accesso all'attività Floodlight nel partner in questione.
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 della strategia utilizzato.
performance_goal	LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType o LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType , a seconda dello schema della 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 risorse o campi equivalenti nell'API Display & Video 360.

UniversalChannel

Nome campo ERF	Disponibilità dell'API DV360
id	Channel.channelId .
nome	Channel.displayName .
site_ids	Recuperabile tramite i 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.