Ce document présente quelques techniques dont vous pouvez vous servir pour améliorer les performances de votre application. Dans certains cas, nous nous basons sur des exemples d'autres API implémentées pour illustrer les idées exposées. Toutefois, les mêmes concepts s'appliquent à l'API Display & Video 360.
Utiliser une partie des ressources
Pour améliorer les performances de vos appels d'API, vous pouvez aussi ne demander que la partie des données qui vous intéressent. Ainsi, vous évitez à votre application le transfert, l'analyse et le stockage de champs inutiles. En outre, cela permet une utilisation plus efficace des ressources, y compris le réseau, l'unité centrale et la mémoire.
Réponse partielle
Par défaut, le serveur renvoie la représentation complète d'une ressource après avoir traité les requêtes. Pour de meilleures performances, vous pouvez demander au serveur de n'envoyer que les champs dont vous avez vraiment besoin afin d'obtenir une réponse partielle.
Pour demander une réponse partielle, utilisez le paramètre de requête fields afin de spécifier les champs qui vous intéressent. Vous pouvez utiliser ce paramètre pour toute requête qui renvoie des données de réponse.
Exemple
L'exemple suivant illustre l'utilisation du paramètre fields avec l'API Display & 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/v4/advertisers?partnerId=1
Réponse complète:les données de la ressource complète incluent les champs suivants, en plus de plusieurs 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 afin de réduire de manière significative le volume de données renvoyées.
GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)
Réponse partielle:en réponse à la requête ci-dessus, le serveur renvoie une réponse contenant un tableau d'annonceurs dépouillé qui n'inclut que l'ID de l'annonceur, le nom à afficher et la propriété d'ID du partenaire de chaque annonceur, le cas échéant.
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.
La mise en forme du paramètre fields et les éléments précis renvoyés dans la réponse sont détaillés ci-dessous.
Récapitulatif de la syntaxe du paramètre "fields"
Le format de la valeur du paramètre de requête fields repose globalement sur la syntaxe XPath. La syntaxe acceptée est résumée ci-dessous, et des exemples supplémentaires sont présentés dans la section suivante.
Incluez une liste dont les éléments sont séparés par une virgule pour sélectionner plusieurs champs.
Incluez
a/bpour sélectionner un champbimbriqué dans le champa. Inclueza/b/cpour sélectionner un champcimbriqué dans le champb.Incluez un sous-sélecteur pour demander un ensemble de sous-champs spécifiques de tableaux ou d'objets en plaçant des expressions entre parenthèses : "
( )".Par exemple,
fields=advertisers(advertiserId,generalConfig/domainUrl)ne renvoie que l'ID de l'annonceur et l'URL du domaine pour chaque élément du tableau "annonceurs". Vous pouvez aussi 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 l'impact de la valeur de paramètre fields sur la réponse.
- Identifiez les champs devant être renvoyés ou effectuez des sélections de champs.
La valeur du paramètre de requête
fieldsest une liste de champs séparés par une virgule, et chaque champ est spécifié en relation avec la racine de la réponse. Ainsi, si vous exécutez une opérationlist, la réponse correspond à une collection et inclut généralement un tableau de ressources. Si vous exécutez une opération qui renvoie une ressource unique, les champs sont spécifiés par rapport à cette ressource. Si le champ que vous sélectionnez est un tableau (ou figure dans un tableau), le serveur renvoie la partie sélectionnée de tous les éléments du tableau.Exemples pour les collections :
Exemple Effet advertisersRenvoie tous les éléments du tableau advertisers, y compris tous les champs de chaque élément, mais aucun autre champ.advertisers,nextPageTokenRenvoie le champ nextPageTokenainsi que tous les éléments du tableauadvertisers.advertisers/advertiserIdNe renvoie que le advertiserIdpour tous les éléments du tableauadvertisers.
Chaque fois qu'un champ imbriqué est renvoyé, la réponse inclut les objets parents englobants. Les champs parents ne contiennent pas d'autres champs enfants, sauf si ceux-ci sont également sélectionnés explicitement.advertisers/generalConfig/domainUrlRenvoie le champ domainUrlpour l'objetgeneralConfig, qui est lui-même imbriqué sous le tableauadvertisers.Exemples pour les ressources :
Exemple Effet advertiserIdRenvoie le champ advertiserIdde la ressource demandée.generalConfig/domainUrlRenvoie le champ domainUrlpour l'objetgeneralConfigde 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 de tableau dans leur intégralité. Vous pouvez spécifier une réponse n'incluant que certains sous-champs. Pour ce faire, utilisez la syntaxe de sous-sélection "
( )", comme indiqué dans l'exemple ci-dessous.Exemple Effet advertisers(advertiserId,generalConfig/domainUrl)Ne renvoie que les valeurs de advertiserIdet de generalConfigdomainUrlpour chaque élément du tableauadvertisers.
Traitement des réponses partielles
Une fois qu'un serveur a traité une requête valide incluant le paramètre de requête fields, il renvoie le code d'état HTTP 200 OK ainsi que les données demandées. Si le paramètre de requête fields comporte une erreur ou s'il n'est pas valide pour une autre raison, le serveur renvoie le code d'état HTTP 400 Bad Request ainsi qu'un message d'erreur indiquant à l'utilisateur la raison pour laquelle sa sélection de champs est incorrecte (par exemple, "Invalid field selection a/b").