Ce guide présente les ressources de dépannage RTB, qui vous permettent d'accéder de manière programmatique aux métriques des campagnes d'enchères en temps réel qui sont également exposées via l'outil Répartition RTB disponible dans l'interface utilisateur Authorized Buyers. Ceux-ci incluent bidders.filterSets, bidders.accounts.filterSets et toutes les ressources qu'ils contiennent de manière hiérarchique.
Grâce aux métriques issues des ressources de dépannage RTB, vous pouvez obtenir des insights sur les opportunités manquées de gagner des impressions, ce qui peut vous aider à optimiser votre campagne avec enchères en temps réel.
Ajustements de la structure et du style de l'API
Les ressources de dépannage RTB apportent quelques modifications pour indiquer explicitement la propriété et les accès, fournir un contrôle plus précis sur les données renvoyées par l'API et mieux s'aligner sur les pratiques de conception des API Google.
Ressources au niveau de l'enchérisseur et du compte
Les ressources sont structurées sous bidders et bidders.accounts. Ils vous permettent de spécifier si un appel d'API cible un enchérisseur (également appelé compte parent) et tous les comptes enfants associés, ou des comptes Authorized Buyers individuels. Dans le contexte du dépannage RTB, les ressources structurées sous bidders.filterSets renverront des métriques agrégées pour l'enchérisseur donné et tous les comptes enfants associés. En revanche, les utilisateurs situés sous bidders.accounts.filterSets ne renvoient des métriques que pour le compte spécifié, qu'il s'agisse d'un compte d'enchérisseur ou d'un compte enfant.
Remarque: Les comptes qui délèguent leurs enchères à un autre acheteur ne sont pas des comptes d'enchérisseurs et ne peuvent donc pas accéder aux ressources au niveau de l'enchérisseur. De plus, les comptes qui ne sont pas des enchérisseurs ne peuvent pas accéder aux ressources impressionMetrics, filteredBidResponses, bidResponseErrors et bidResponsesWithoutBids au niveau du compte.
Présentation des noms de ressources en tant qu'identifiants uniques
Les noms de ressources sont utilisés comme identifiants uniques plutôt que comme des ID d'entiers ou de chaînes. Lors de la création d'une instance d'un type de ressource donné, vous devez maintenant spécifier un nom de ressource relatif en utilisant le chemin d'URI de la ressource suivi de l'ID de ressource souhaité. Voici des exemples de noms pertinents pour les ressources de dépannage RTB:
| Ressource | Exemple de nom |
|---|---|
| bidders.filterSets | bidders/12345678/filterSets/fset_1 |
| bidders.accounts.filterSets | bidders/12345678/accounts/87654321/filterSets/fset_2 |
Remarque: L'ID de ressource spécifié pour bidders dans le nom doit être l'ID de compte Authorized Buyers d'un enchérisseur. Pour accounts, l'ID de ressource doit être un ID de compte de l'enchérisseur ou d'un compte enfant qu'il gère. Si vous ne savez pas quels comptes Authorized Buyers sont associés à votre compte Google, vous pouvez les rechercher à l'aide de la méthode accounts.list.
Ensembles de filtres
Un ensemble de filtres représente les options de filtrage disponibles et peut être créé au niveau de l'enchérisseur ou du compte. Il permet de filtrer la liste des ressources de dépannage RTB qui récupèrent des métriques pour vos campagnes d'enchères en temps réel.
Le filtre appliqué lors de la récupération des métriques est l'intersection de chaque filtre de l'ensemble de filtres spécifié. Les filtres de liste, tels que platforms, sont interprétés comme l'union de chaque élément de la liste.
Les ensembles de filtres au niveau de l'enchérisseur et du compte sont distincts et accessibles uniquement au niveau où ils ont été créés, quel que soit le compte utilisé pour les créer. Un enchérisseur et un compte enfant partagent des ensembles de filtres créés au niveau du compte, alors qu'un seul enchérisseur peut accéder aux ressources au niveau de l'enchérisseur. Le tableau suivant récapitule comment les comptes d'enchérisseurs et les comptes enfants peuvent accéder aux ressources à chaque niveau:
| bidders.filterSets | bidders.accounts.filterSets | |
|---|---|---|
| Compte d'enchérisseur | Un appel d'API n'affecte que les ensembles de filtres au niveau de l'enchérisseur. | Appel d'API n'affectant que les ensembles de filtres au niveau du compte. |
| Compte enfant | Cet appel d'API renverra une erreur. | Appel d'API n'affectant que les ensembles de filtres au niveau du compte. |
Créer un ensemble de filtres
Lorsque vous créez un ensemble de filtres, vous devez spécifier une période en tant que relativeDateRange, absoluteDateRange ou realtimeTimeRange. Par défaut, lors de la récupération des métriques, toutes les données doivent être fournies pour l'ensemble de la période. Si vous souhaitez recevoir une répartition des séries temporelles sur la période, vous pouvez spécifier timeSeriesGranularity pour indiquer les intervalles HOURLY ou DAILY.
Si vous n'avez besoin d'un ensemble de filtres que pendant une courte période, vous pouvez définir le paramètre de requête isTransient sur true. Cela indique que l'ensemble de filtres est temporaire, c'est-à-dire qu'il ne sera pas conservé indéfiniment. Les ensembles de filtres temporaires seront disponibles pendant au moins une heure après leur création, mais finiront par être supprimés. Par défaut, les ensembles de filtres ne sont pas temporaires.
Exemple au niveau de l'enchérisseur
Pour créer un ensemble de filtres au niveau de l'enchérisseur, envoyez une demande POST à l'URI de ressource bidders.filterSets, au format suivant:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
Avertissement: Les ensembles de filtres au niveau de l'enchérisseur ne peuvent pas filtrer par ID de création ou d'accord. Si vous spécifiez ces filtres lors de la création d'un ensemble de filtres au niveau de l'enchérisseur, vous recevrez une erreur.
RequêteVoici un exemple de demande POST qui crée un ensemble de filtres au niveau de l'enchérisseur non temporaire:
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"
}
Réponse
Si la requête aboutit, le serveur affiche un code d'état 200 OK. Le corps de la réponse inclura la ressource de l'ensemble de filtres créé, qui sera identique à l'ensemble de filtres envoyé dans la demande.
Exemple au niveau du compte
Pour créer un ensemble de filtres au niveau du compte, envoyez une requête POST à l'URI de ressource bidders.accounts.filterSets, au format suivant:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
Remarque: L'ID de ressource spécifié pour accounts peut être l'ID de n'importe quel compte Authorized Buyers accessible au compte d'enchérisseur spécifié dans l'URI, y compris le compte d'enchérisseur lui-même.
Voici un exemple de requête POST qui crée un ensemble de filtres au niveau du compte non temporaire:
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"
}
Réponse
Si la requête aboutit, le serveur affiche un code d'état 200 OK. Le corps de la réponse inclura la ressource d'ensemble de filtres créée, qui sera identique à l'ensemble de filtres envoyé dans la requête.
Obtenir un ensemble de filtres
La méthode get ne permet d'obtenir qu'un ensemble de filtres au même niveau que celui où il a été créé. Par exemple, un compte d'enchérisseur doit utiliser bidders.accounts.filterSets.get pour récupérer un ensemble de filtres créé au niveau du compte plutôt que la méthode bidders.filterSets.get.
Au niveau de l'enchérisseur
Pour récupérer un filtre défini au niveau de l'enchérisseur, envoyez une requête HTTP GET à l'URI de ressource bidders.filterSets, dont le format est le suivant:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}
Demande
Exemple :
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fsRéponse
Si la requête aboutit, le serveur affiche un code d'état HTTP 200 OK et renvoie l'ensemble de filtres:
{
"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"
}
Au niveau du compte
Pour récupérer un filtre au niveau du compte, envoyez une requête HTTP GET à l'URI de la ressource bidders.accounts.filterSets, dont le format est le suivant:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}
Demande
Exemple :
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fsRéponse
Si la requête aboutit, le serveur affiche un code d'état HTTP 200 OK et renvoie l'ensemble de filtres:
{
"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"
}
Lister les ensembles de filtres
La méthode "list" ne renverra que les ensembles de filtres accessibles à partir du niveau auquel elle est appelée.
Par exemple, un compte d'enchérisseur ne verra pas les ensembles de filtres créés pour lui-même via bidders.accounts.filterSets.create lors de l'appel de bidders.filterSets.list.
Au niveau de l'enchérisseur
Pour récupérer tous les ensembles de filtres au niveau d'un enchérisseur spécifique, envoyez une requête HTTP GET à l'URI de ressource bidders.filtersets, au format suivant:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
Demande
Voici un exemple listant tous les ensembles de filtres au niveau d'un enchérisseur pour un enchérisseur dont l'ID de compte est 12345678:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSetsRéponse
{
"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"
}
]
}
Au niveau du compte
Pour récupérer tous les ensembles de filtres au niveau du compte pour un compte donné, envoyez une requête HTTP GET à l'URI de ressource bidders.accounts.filtersets, au format suivant:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
Demande
Voici un exemple répertoriant tous les ensembles de filtres au niveau du compte pour un compte enfant portant l'ID 87654321:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSetsRéponse
{
"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"
}
]
}
Supprimer un ensemble de filtres
Vous pouvez utiliser la méthode delete pour supprimer tous les ensembles de filtres non temporaires dont vous n'avez plus besoin. Seuls les ensembles de filtres accessibles à partir du niveau d'appel peuvent être supprimés. Par exemple, un compte d'enchérisseur ne peut pas supprimer un ensemble de filtres créé avec bidders.accounts.filterSets.create et bidders.filterSets.delete.
Au niveau de l'enchérisseur
Vous pouvez supprimer un ensemble de filtres au niveau de l'enchérisseur pour un compte donné en envoyant une requête HTTP DELETE à l'URI de ressource bidders.filtersets, au format suivant:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}
Demande
Voici un exemple de suppression d'un ensemble de filtres au niveau de l'enchérisseur:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2Réponse
Si la requête aboutit, le corps de la requête sera vide. L'ensemble de filtres spécifié ne sera plus accessible.
Au niveau du compte
Pour supprimer un ensemble de filtres au niveau du compte pour un compte donné, envoyez une requête HTTP DELETE à l'URI de ressource bidders.accounts.filtersets, au format suivant:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}
Demande
Voici un exemple de suppression d'un ensemble de filtres au niveau du compte:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1Réponse
Si la requête aboutit, le corps de la requête sera vide. L'ensemble de filtres spécifié ne sera plus accessible.
Récupérer les métriques de dépannage RTB
Toutes les ressources de dépannage RTB qui reçoivent des métriques fonctionnent de la même manière. Elles disposent d'une seule méthode pour répertorier les métriques de l'ensemble de filtres spécifié via un paramètre de chemin filterSetName. L'ensemble de filtres spécifié détermine les filtres et les paramètres qui seront appliqués lors de l'interrogation des métriques. L'appel de ces ressources au niveau de l'enchérisseur renvoie les métriques agrégées du compte de l'enchérisseur et de tous les comptes enfants associés, tandis qu'un appel effectué au niveau du compte ne renvoie que les métriques d'un compte individuel.
Métriques sur les enchères
La ressource bidMetrics permet de récupérer les métriques mesurées en nombre d'enchères. Par exemple, vous pouvez l'utiliser pour déterminer le nombre total d'enchères sur une période donnée et le nombre d'enchères qui n'ont pas été exclues de la mise aux enchères, qui ont remporté une impression, etc. Comme toutes les autres ressources de dépannage RTB utilisées pour collecter des métriques, elle ne dispose que d'une méthode list.
Lister les métriques d'enchères au niveau de l'enchérisseur
Vous pouvez répertorier les métriques d'enchères au niveau de l'enchérisseur pour un filtre donné en envoyant une requête HTTP GET à l'URI de ressource bidders.filtersets.bidMetrics, au format suivant:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetrics
Demande
Voici un exemple de métriques d'enchères au niveau de l'enchérisseur:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetricsRéponse
Si la requête aboutit, le serveur renvoie un code d'état 200 OK et un corps contenant des lignes de métriques correspondant aux dimensions et au niveau de précision spécifiés.
{
"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": {}
}
]
}
Remarque: Les champs définis sur 0 pour une métrique donnée n'apparaîtront pas dans la réponse.
Les métriques vides billedImpressions et measurableImpressions ci-dessus indiquent que leur valeur et leur variance sont définies sur 0.
Avertissement: Pour toute répartition des données dans la réponse, la réponse n'inclura pas les lignes si elles ne contiennent pas au moins une métrique non nulle. Par exemple, lorsqu'un élément timeSeriesGranularity est spécifié, la réponse n'inclut pas les lignes correspondant aux timeInterval au cours de la période spécifiée pour l'ensemble de filtres, dans laquelle toutes les métriques sont nulles.
Lister les métriques d'enchères au niveau du compte
Vous pouvez répertorier les métriques d'enchères au niveau du compte pour un ensemble de filtres donné en envoyant une requête HTTP GET à l'URI de la ressource bidders.accounts.filtersets.bidMetrics, au format suivant:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetrics
Demande
Voici un exemple de liste de métriques d'enchères au niveau du compte:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetricsRéponse
Si la requête aboutit, le serveur renvoie un code d'état 200 OK et un corps contenant des lignes de métriques correspondant aux dimensions et au niveau de précision spécifiés.
{
"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": {}
}
]
}
Remarque: Les champs définis sur 0 pour une métrique donnée n'apparaîtront pas dans la réponse. Les métriques vides billedImpressions et measurableImpressions ci-dessus indiquent que leur valeur et leur variance sont définies sur 0.
Avertissement: Pour toute répartition des données dans la réponse, la réponse n'inclura pas les lignes si elles ne contiennent pas au moins une métrique non nulle. Par exemple, lorsqu'un élément timeSeriesGranularity est spécifié, la réponse n'inclut pas les lignes correspondant aux timeInterval au cours de la période spécifiée pour l'ensemble de filtres, dans laquelle toutes les métriques sont nulles.