Ce document présente quelques techniques que vous pouvez utiliser pour améliorer les performances votre application. Dans certains cas, des exemples provenant d'autres API implémentées sont utilisés pour illustrer les idées présentées. Toutefois, les mêmes concepts s'appliquent sur le Réseau Display et l'API Video 360.
Utiliser une partie des ressources
Un autre moyen d'améliorer les performances de vos appels d'API consiste à demander uniquement la partie des données qui vous intéresse. Cela permet à votre application d'éviter de transférer, d'analyser et de stocker des champs inutiles, car il peut utiliser les ressources telles que le réseau, le processeur et la mémoire.
Réponse partielle
Par défaut, le serveur renvoie la représentation complète d'une ressource après qui traite les demandes. Pour de meilleures performances, vous pouvez demander au serveur d'envoyer uniquement les champs dont vous avez vraiment besoin et d'obtenir une réponse partielle à la place.
Pour demander une réponse partielle, utilisez le paramètre de requête fields
afin de spécifier
les champs que vous souhaitez obtenir. Vous pouvez utiliser ce paramètre avec n'importe quelle requête
qui renvoie des données de réponse.
Exemple
L'exemple suivant illustre l'utilisation du paramètre fields
avec
Display & l'API Video 360.
Requête simple:cette requête HTTP GET
omet le paramètre fields
et
renvoie la ressource complète.
GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1
Réponse de la ressource complète:les données de la ressource complète incluent les éléments suivants ainsi que de nombreux autres champs qui ont été omis pour des raisons de concision.
200 OK
{
"advertisers": [
{
"name": "advertisers/1",
"advertiserId": "1",
"partnerId": "1",
"displayName": "Example Advertiser 1",
"entityStatus": "ENTITY_STATUS_ACTIVE",
"updateTime": "2019-01-01T00:00:00.000000Z",
"generalConfig": {
"domainUrl": "http://example.com",
"timeZone": "America/New_York",
"currencyCode": "USD",
"address": {
}
},
"adServerConfig": {
"thirdPartyOnlyConfig": {
}
},
"creativeConfig": {
},
"dataAccessConfig": {
"sdfConfig": {
"sdfConfig": {
"version": "VERSION_3_1"
}
}
},
"integrationDetails": {
}
},
{
"name": "advertisers/2",
"advertiserId": "2",
"partnerId": "1",
"displayName": "Example Advertiser 2",
"entityStatus": "ENTITY_STATUS_ACTIVE",
"updateTime": "2019-01-01T00:00:00.000000Z",
"generalConfig": {
"domainUrl": "http://example.com",
"timeZone": "America/New_York",
"currencyCode": "USD",
"address": {
}
},
"adServerConfig": {
"thirdPartyOnlyConfig": {
}
},
"creativeConfig": {
},
"dataAccessConfig": {
"sdfConfig": {
"sdfConfig": {
"version": "VERSION_3_1"
}
}
},
"integrationDetails": {
}
},
...
],
"nextPageToken": "..."
}
Requête de réponse partielle:la requête suivante portant sur cette même ressource
utilise le paramètre fields
pour réduire de manière significative la quantité de données renvoyées.
GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)
Réponse partielle:suite à la requête ci-dessus, le serveur renvoie un Réponse contenant un tableau d'annonceurs dépouillé comprenant uniquement les la référence annonceur, le nom à afficher et la propriété de la référence partenaire de chaque annonceur, si à l'heure actuelle.
200 OK
{
"advertisers": [
{
"advertiserId": "1",
"partnerId": "1",
"displayName": "Example Advertiser 1"
},
{
"advertiserId": "2",
"partnerId": "1",
"displayName": "Example Advertiser 2"
},
...
]
}
Notez que la réponse est un objet JSON qui ne comprend que les champs sélectionnés. et leurs objets parents englobants.
Vous trouverez ci-dessous des informations détaillées sur le formatage du paramètre fields
, puis sur
plus de détails sur ce qui est
exactement renvoyé dans la réponse.
Récapitulatif de la syntaxe du paramètre "fields"
Le format de la valeur du paramètre de requête fields
est vaguement basé sur XPath.
syntaxe. La syntaxe acceptée est résumée ci-dessous, et des exemples supplémentaires sont
fournies dans la section suivante.
Incluez une liste dont les éléments sont séparés par une virgule pour sélectionner plusieurs champs.
Utilisez
a/b
pour sélectionner un champb
imbriqué dans le champa
. utilisera/b/c
pour sélectionner un champc
imbriqué dansb
.Utilisez un sous-sélecteur pour demander un ensemble de sous-champs spécifiques de tableaux ou en plaçant des expressions entre parenthèses "
( )
".Exemple:
fields=advertisers(advertiserId,generalConfig/domainUrl)
renvoie uniquement le numéro d'annonceur et l'URL de domaine pour chaque élément de la annonceurs. Vous pouvez également spécifier un sous-champ unique, oùfields=advertisers(advertiserId)
équivaut àfields=advertisers/advertiserId
Autres exemples d'utilisation du paramètre "fields"
Les exemples ci-dessous décrivent la manière dont la valeur du paramètre fields
affecte la réponse.
- Identifiez les champs devant être renvoyés ou effectuez des sélections de champs.
La valeur de paramètre de requête
fields
est une liste de champs séparés par une virgule. chaque champ est spécifié par rapport à la racine de la réponse. Ainsi, si vous effectuent une opérationlist
, la réponse est une collection, et elle comprend généralement un tableau de ressources. Si vous effectuez une opération qui renvoie une ressource unique, les champs sont spécifiés par rapport ressource. Si le champ que vous sélectionnez est (ou fait partie) d'un tableau, le serveur renvoie la partie sélectionnée de tous les éléments du tableau.Exemples pour les collections :
Exemple Effet advertisers
Renvoie tous les éléments de la méthode Tableau advertisers
, y compris tous les champs de chaque élément, mais aucun autre champ.advertisers,nextPageToken
Renvoie à la fois nextPageToken
et tous les éléments du Tableauadvertisers
.advertisers/advertiserId
Ne renvoie que advertiserId
pour tous les éléments Tableauadvertisers
.
Chaque fois qu'un champ imbriqué est renvoyée, la réponse inclut les objets parents englobants. Les champs parents n'incluent pas tout autre champ enfant, sauf ils sont aussi sélectionnés explicitement.advertisers/generalConfig/domainUrl
Renvoie le champ domainUrl
. pour l'objetgeneralConfig
, qui est elle-même imbriquée sous laadvertisers
.Exemples pour les ressources :
Exemple Effet advertiserId
Renvoie le champ advertiserId
. de la ressource demandée.generalConfig/domainUrl
Renvoie le champ domainUrl
. pour l'objetgeneralConfig
dans la ressource demandée.- Ne demandez que des parties de champs spécifiques à l'aide de sous-sélections.
Par défaut, si votre requête spécifie des champs particuliers, le serveur renvoie les objets ou les éléments du tableau dans leur intégralité. Vous pouvez spécifier une réponse qui ne comprend que certains sous-champs. Vous utilisez "
( )
" de sous-sélection, comme dans l'exemple ci-dessous.Exemple Effet advertisers(advertiserId,generalConfig/domainUrl)
Renvoie uniquement la valeur valeurs de advertiserId
et GeneralConfigdomainUrl
pour chaque élément de leadvertisers
tableau.
Traitement des réponses partielles
Une fois qu'un serveur a traité une requête valide incluant la requête fields
, il renvoie un code d'état HTTP 200 OK
, ainsi que la valeur
données. Si le paramètre de requête fields
comporte une erreur ou n'est pas valide pour une autre raison, le
renvoie un code d'état HTTP 400 Bad Request
, ainsi qu'une erreur
vous indiquant le problème rencontré lors de la sélection des champs (par exemple,
"Invalid field selection a/b"
).