Questa pagina è stata tradotta dall'API Cloud Translation.

Risoluzione dei problemi relativi alle offerte in tempo reale

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.

Richiedi

Ecco 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.

Richiedi

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-fs

Risposta

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-fs

Risposta

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}/filterSets

Richiesta

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/filterSets

Risposta

{
  "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}/filterSets

Richiesta

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/filterSets

Risposta

{
  "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-2

Risposta

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-1

Risposta

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}/bidMetrics

Richiesta

Ecco un esempio delle metriche di offerta a livello di offerente:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetrics

Risposta

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}/bidMetrics

Richiesta

Ecco un esempio delle metriche di offerta a livello di account:

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetrics

Risposta

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.