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.
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.
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 richiestaadvertisers.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 metodoadvertisers.lineItems.list
per restituire solo gli elementi pubblicitari con un valoreupdateTime
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
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. |