Questa guida illustra le risorse per la risoluzione dei problemi relativi alle offerte in tempo reale, che consentono di accedere in modo programmatico alle metriche delle campagne con offerte in tempo reale esposte anche tramite lo strumento Segmentazione delle offerte in tempo reale nell'interfaccia utente di Authorized Buyers. Questi includono bidders.filterSets
, bidders.accounts.filterSets
e tutte le risorse sottostanti in modo gerarchico.
Utilizzando le metriche delle risorse per la risoluzione dei problemi delle offerte in tempo reale, puoi ottenere informazioni sulle opportunità mancate di ottenere impressioni, utili per ottimizzare la tua campagna con offerte in tempo reale.
Modifiche alla struttura e allo stile dell'API
Le risorse per la risoluzione dei problemi RTB introducono alcune modifiche per indicare esplicitamente la proprietà e l'accesso, fornire un controllo più granulare sui dati restituiti dall'API e allinearsi meglio con le pratiche di progettazione dell'API di Google.
Risorse a livello di offerente e di account
Le risorse sono strutturate sia in bidders
che in bidders.accounts
. Consentono di specificare se una chiamata API ha come target un offerente (noto anche come account principale) e tutti gli account secondari associati o singoli account Authorized Buyers. Nel contesto della risoluzione dei problemi
RTB, le risorse strutturate in bidders.filterSets
restituiranno metriche aggregate
per lo strumento di offerta specificato e per tutti gli account secondari associati. Al contrario, quelli con bidders.accounts.filterSets
restituiranno solo le metriche per l'account specificato, che si tratti di un offerente o di un account secondario.
Nota: gli account che delegano le offerte a un altro acquirente non sono account offerente e,
di conseguenza, non possono accedere alle risorse a livello di offerente. Inoltre, gli account non offerente non possono accedere alle risorse impressionMetrics
, filteredBidResponses
, bidResponseErrors
e bidResponsesWithoutBids
a livello di account.
Introduzione dei nomi delle risorse come identificatori univoci
I nomi delle risorse vengono utilizzati come identificatori univoci anziché come ID di numeri interi o stringhe. Quando crei una nuova istanza di un determinato tipo di risorsa, ora devi specificare un nome della risorsa relativa utilizzando il percorso URI della risorsa seguito dall'ID risorsa preferito. Di seguito sono riportati esempi di nomi pertinenti per le risorse per la risoluzione dei problemi RTB:
Risorsa | Esempio di nome |
---|---|
bidders.filterSets | bidders/12345678/filterSets/fset_1 |
bidders.accounts.filterSets | bidders/12345678/accounts/87654321/filterSets/fset_2 |
Nota: l'ID risorsa specificato per bidders
nel nome deve essere l'ID account Authorized Buyers di un offerente. Per accounts
, l'ID risorsa deve essere un ID account
dell'offerente o di un account secondario da questo gestito. Se non sai quali account Authorized Buyers sono associati al tuo Account Google, puoi utilizzare il metodo accounts.list per trovarli.
Set di filtri
Un set di filtri è una rappresentazione delle opzioni di filtro disponibili e può essere creato a livello di offerente o account. Viene utilizzato per filtrare l'elenco dei risultati delle risorse per la risoluzione dei problemi delle offerte in tempo reale che recuperano le metriche per le campagne con offerte in tempo reale.
Il filtro applicato durante il recupero delle metriche è l'intersezione di ciascun filtro nel set di filtri specificato. I filtri dell'elenco, come platforms
, vengono interpretati come l'unione di ogni elemento nell'elenco.
I set di filtri a livello di strumento di offerta e di account sono distinti e accessibili solo dal livello in cui sono stati creati, indipendentemente dall'account utilizzato per crearli. Un offerente e un insieme di filtri di condivisione degli account secondari creati a livello di account, mentre solo un offerente può accedere alle risorse a livello di offerente. La tabella seguente riassume il modo in cui gli offerenti e gli account secondari possono accedere alle risorse a entrambi i livelli:
bidders.filterSets | bidders.accounts.filterSets | |
---|---|---|
Account offerente | Una chiamata API che interessa solo i set di filtri a livello di offerente. | Una chiamata API che interessa solo i set di filtri a livello di account. |
Account bambino/a | Questa chiamata API restituirà una risposta di errore. | Una chiamata API che interessa solo i set di filtri a livello di account. |
Creare un insieme di filtri
Quando crei un set di filtri, devi specificare un intervallo di tempo come relativeDateRange
,
absoluteDateRange
o realtimeTimeRange
. Quando recuperi le metriche, il comportamento predefinito prevede che tutti i dati vengano forniti per l'intero intervallo di tempo. Se vuoi ricevere
un'analisi delle serie temporali nell'intervallo di tempo, puoi specificare timeSeriesGranularity
per indicare intervalli HOURLY
o DAILY
.
Se hai bisogno di un insieme di filtri solo per un breve periodo di tempo, puoi impostare il parametro di query isTransient
su true
. Questo indica che l'insieme di filtri è temporaneo, ovvero non verrà mantenuto a tempo indeterminato. I set di filtri temporanei saranno disponibili per almeno un'ora dopo la creazione, ma alla fine verranno eliminati. Per impostazione predefinita, i set di filtri non sono temporanei.
Esempio a livello di offerente
Per creare un nuovo insieme di filtri a livello di offerente, invia una richiesta POST
all'URI della risorsa bidders.filterSets
, che ha il seguente formato:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
Avviso: i set di filtri a livello di offerente non sono in grado di filtrare per ID creatività o deal. Se specifichi questi filtri durante la creazione di un insieme di filtri a livello di offerente, riceverai una risposta di errore.
RichiediEcco un esempio di richiesta POST
che crea un nuovo insieme di filtri non temporanei a livello di offerente:
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets Authorization: Bearer access token here Content-Type: application/json { "name": "bidders/12345678/filterSets/bidder-fs", "format": "DISPLAY", "environment": "APP", "platforms": ["TABLET", "MOBILE"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }Risposta
Se la richiesta ha esito positivo, il server risponde con un codice di stato 200 OK. Il corpo della risposta includerà la risorsa dell'insieme di filtri creato, che sarà identica al set di filtri inviato nella richiesta.
Esempio a livello di account
Per creare un nuovo insieme di filtri a livello di account, invia una richiesta POST
all'URI della risorsa bidders.accounts.filterSets
, che ha il seguente formato:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
Nota: l'ID risorsa specificato per accounts
può
essere l'ID account di qualsiasi account Authorized Buyers accessibile all'account dell'offerente specificato nell'URI, incluso l'account dell'offerente stesso.
Ecco un esempio di richiesta POST
che crea un nuovo set di filtri non temporanei a livello di account:
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets Authorization: Bearer access token here Content-Type: application/json { "name": "bidders/12345678/accounts/87654321/filterSets/account-fs", "format": "VIDEO", "environment": "WEB", "platforms": ["DESKTOP"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }Risposta
Se la richiesta ha esito positivo, il server risponde con un codice di stato 200 OK. Il corpo della risposta includerà la risorsa del set di filtri creato, che sarà identica al set di filtri inviato nella richiesta.
Ottieni un insieme di filtri
Il metodo get può ricevere un insieme di filtri solo allo stesso livello in cui è stato creato. Ad esempio, un account offerente
deve utilizzare bidders.accounts.filterSets.get
per recuperare un set di filtri creato a livello di
account anziché il metodo bidders.filterSets.get
.
A livello di offerente
Puoi recuperare un set di filtri a livello di offerente inviando una richiesta HTTP GET all'URI della risorsa bidders.filterSets
, che ha il seguente formato:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}Richiesta
Esempio:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fsRisposta
Se la richiesta ha esito positivo, il server risponde con un codice di stato HTTP 200 OK
e il filtro recuperato è impostato:
{ "name": "bidders/12345678/filterSets/bidder-fs", "format": "DISPLAY", "environment": "APP", "platforms": ["TABLET", "MOBILE"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }
A livello di account
Puoi recuperare un set di filtri a livello di account inviando una richiesta HTTP GET
all'URI della risorsa bidders.accounts.filterSets
, che ha il seguente formato:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}Richiesta
Esempio:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fsRisposta
Se la richiesta ha esito positivo, il server risponde con un codice di stato HTTP 200 OK
e il filtro recuperato è impostato:
{ "name": "bidders/12345678/accounts/87654321/filterSets/account-fs", "format": "VIDEO", "environment": "WEB", "platforms": ["DESKTOP"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }
Elenca set di filtri
Il metodo list restituirà solo set di filtri accessibili dal livello che viene chiamato.
Ad esempio, un account offerente non vedrà i set di filtri creati per se stesso tramite
bidders.accounts.filterSets.create
quando chiama bidders.filterSets.list
.
A livello di offerente
Puoi recuperare tutti i set di filtri a livello di offerente per un determinato offerente inviando una richiesta GET
HTTP all'URI della risorsa bidders.filtersets
, che ha il seguente formato:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSetsRichiesta
Ecco un esempio che elenca tutti i set di filtri a livello di offerente per un offerente con ID account 12345678:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSetsRisposta
{ "filterSets": [{ "filterSetId": "99994", "name": "bidders/12345678/filterSets/test-b-1", "relativeDateRange": { "durationDays": 30 } }, { "realtimeTimeRange": { "startTimeStamp": "2017-11-15T12:30:30.072831583Z" }, "filterSetId": "99995", "name": "bidders/12345678/filterSets/test-b-2", "timeSeriesGranularity": "HOURLY" }, { "absoluteDateRange": { "endDate": { "day": 12, "month": 3, "year": 2017 }, "startDate": { "day": 26, "month": 11, "year": 2017 } }, "filterSetId": "99996", "name": "bidders/12345678/filterSets/bidder-fs", "timeSeriesGranularity": "DAILY", "platforms": ["TABLET", "MOBILE"], "environment": "APP", "format": "DISPLAY" } ] }
A livello di account
Puoi recuperare tutti i set di filtri a livello di account per un determinato account inviando una richiesta HTTP GET
all'URI della risorsa bidders.accounts.filtersets
, che ha il seguente formato:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSetsRichiesta
Ecco un esempio di elenco di tutti i set di filtri a livello di account per un account secondario con ID account 87654321:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSetsRisposta
{ "filterSets": [{ "realtimeTimeRange": { "startTimeStamp": "2017-11-19T04:24:43.252893487Z" }, "filterSetId": "99997", "name": "bidders/12345678/accounts/87654321/filterSets/test-a-1", "timeSeriesGranularity": "DAILY" }, { "absoluteDateRange": { "endDate": { "day": 3, "month": 12, "year": 2017 }, "startDate": { "day": 26, "month": 11, "year": 2017 } }, "filterSetId": "99998", "name": "bidders/12345678/accounts/87654321/filterSets/account-fs", "timeSeriesGranularity": "DAILY", "platforms": ["DESKTOP"], "environment": "WEB", "format": "VIDEO" } ] }
Eliminare un insieme di filtri
Puoi utilizzare il metodo delete
per rimuovere tutti i set di filtri non temporanei che non sono più necessari. Può solo rimuovere i set di filtri accessibili dal livello in cui viene chiamato;
ad esempio, un account offerente non può eliminare un set di filtri creato con bidders.accounts.filterSets.create
con bidders.filterSets.delete
.
A livello di offerente
Puoi eliminare un insieme di filtri a livello di offerente per un determinato account inviando una richiesta HTTP DELETE
all'URI della risorsa bidders.filtersets
, che ha il seguente formato:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}Richiesta
Ecco un esempio di eliminazione di un insieme di filtri a livello di offerente:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2Risposta
Se l'operazione ha esito positivo, il corpo della richiesta sarà vuoto. Il set di filtri specificato non sarà più accessibile.
A livello di account
Puoi eliminare un insieme di filtri a livello di account per un determinato account inviando una richiesta HTTP DELETE
all'URI della risorsa bidders.accounts.filtersets
, che ha il seguente formato:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}Richiesta
Ecco un esempio di eliminazione di un insieme di filtri a livello di account:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1Risposta
Se l'operazione ha esito positivo, il corpo della richiesta sarà vuoto. Il set di filtri specificato non sarà più accessibile.
Recupero delle metriche per la risoluzione dei problemi RTB
Tutte le risorse per la risoluzione dei problemi RTB utilizzate per ricevere le metriche funzionano in modo simile: hanno un singolo metodo per elencare le metriche per il set di filtri specificato tramite un parametro percorso filterSetName
. Il set di filtri specificato determinerà i filtri e le impostazioni che verranno applicati durante l'esecuzione di query sulle metriche. La chiamata di queste risorse dal livello dell'offerente restituirà metriche aggregate
dall'account dell'offerente e da tutti gli account secondari associati, mentre una chiamata dal livello di account
restituirà solo le metriche per un account individuale.
Metriche offerta
La risorsa bidMetrics
viene utilizzata per recuperare le metriche misurate in termini di
numero di offerte. Ad esempio, puoi utilizzarlo per determinare il numero totale di offerte in un determinato intervallo di tempo e quante di queste non sono state filtrate dall'asta, hanno vinto un'impressione e così via. Come tutte le altre risorse per la risoluzione dei problemi RTB utilizzate per raccogliere le metriche, esiste solo un metodo list
.
Elenca metriche di offerta a livello di offerente
Puoi elencare le metriche di offerta a livello di offerente per un determinato set di filtri inviando una richiesta GET
HTTP all'URI della risorsa bidders.filtersets.bidMetrics
, che ha il seguente formato:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetricsRichiesta
Ecco un esempio delle metriche di offerta a livello di offerente:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetricsRisposta
Se la richiesta ha esito positivo, il server risponde con un codice di stato 200 OK
e un corpo contenente righe di metriche per le dimensioni e la granularità specificate.
{ "bidMetricsRows": [{ "bids": { "value": "6160" }, "bidsInAuction": { "value": "5698" }, "billedImpressions": { "value": "1196" }, "impressionsWon": { "value": "2920" }, "measurableImpressions": { "value": "1160" }, "rowDimensions": { "timeInterval": { "endTime": "2017-11-29T08:00:00Z", "startTime": "2017-11-28T08:00:00Z" } }, "viewableImpressions": { "value": "683" } }, { "bids": { "value": "104288" }, "bidsInAuction": { "value": "94016" }, "billedImpressions": { "value": "99" }, "impressionsWon": { "value": "125" }, "measurableImpressions": { "value": "94" }, "rowDimensions": { "timeInterval": { "endTime": "2017-11-30T08:00:00Z", "startTime": "2017-11-29T08:00:00Z" } }, "viewableImpressions": { "value": "87" } }, { "bids": { "value": "3999" }, "bidsInAuction": { "value": "3631" }, "billedImpressions": { "value": "618" }, "impressionsWon": { "value": "1819" }, "measurableImpressions": { "value": "604" }, "rowDimensions": { "timeInterval": { "endTime": "2017-12-01T08:00:00Z", "startTime": "2017-11-30T08:00:00Z" } }, "viewableImpressions": { "value": "369" } }, { "bids": { "value": "15" }, "bidsInAuction": { "value": "3" }, "billedImpressions": {}, "impressionsWon": { "value": "3" }, "measurableImpressions": {}, "rowDimensions": { "timeInterval": { "endTime": "2017-12-02T08:00:00Z", "startTime": "2017-12-01T08:00:00Z" } }, "viewableImpressions": {} } ] }
Nota: i campi impostati su 0 per una determinata metrica non verranno visualizzati nella risposta.
Le metriche billedImpressions
e measurableImpressions
vuote riportate sopra
indicano che sia il valore sia la varianza sono impostati su 0.
Avviso: per qualsiasi suddivisione dei dati nella risposta, la risposta non includerà righe se non contengono almeno una metrica diversa da zero. Ad esempio, quando
è specificato un timeSeriesGranularity
, la risposta non includerà righe per
timeInterval
nell'intervallo di tempo specificato del set di filtri, in cui tutte le metriche sono zero.
Elenca metriche di offerta a livello di account
Puoi elencare le metriche di offerta a livello di account per un determinato set di filtri inviando una richiesta GET
HTTP all'URI della risorsa bidders.accounts.filtersets.bidMetrics
, che ha il seguente formato:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetricsRichiesta
Ecco un esempio delle metriche di offerta a livello di account:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetricsRisposta
Se la richiesta ha esito positivo, il server risponde con un codice di stato 200 OK
e un corpo contenente righe di metriche per le dimensioni e la granularità specificate.
{ "bidMetricsRows": [{ "bids": { "value": "1748" }, "bidsInAuction": { "value": "1421" }, "billedImpressions": { "value": "301" }, "impressionsWon": { "value": "915" }, "measurableImpressions": { "value": "298" }, "rowDimensions": { "timeInterval": { "endTime": "2017-12-01T08:00:00Z", "startTime": "2017-11-30T08:00:00Z" } }, "viewableImpressions": { "value": "172" } }, { "bids": { "value": "6" }, "bidsInAuction": { "value": "2" }, "billedImpressions": {}, "impressionsWon": { "value": "1" }, "measurableImpressions": {}, "rowDimensions": { "timeInterval": { "endTime": "2017-12-02T08:00:00Z", "startTime": "2017-12-01T08:00:00Z" } }, "viewableImpressions": {} } ] }
Nota: i campi impostati su 0 per una determinata metrica non verranno visualizzati nella risposta. Le
metriche vuote billedImpressions
e measurableImpressions
riportate sopra indicano
che sia il valore sia la varianza sono impostati su 0.
Avviso: per qualsiasi suddivisione dei dati nella risposta, la risposta non includerà righe se non contengono almeno una metrica diversa da zero. Ad esempio, quando
è specificato un timeSeriesGranularity
, la risposta non includerà righe per
timeInterval
nell'intervallo di tempo specificato del set di filtri, in cui tutte le metriche sono zero.