Ce document présente quelques techniques que vous pouvez utiliser pour améliorer les performances de votre application. Dans certains cas, des exemples d'autres API ou d'API génériques permettent d'illustrer les idées exposées. Toutefois, les mêmes concepts s'appliquent à l'API Library de Google Photos.
Compression avec gzip
La compression gzip est un moyen pratique et facile de réduire la bande passante requise pour chaque requête. Même si la décompression des résultats nécessite un temps CPU supplémentaire, la compression est généralement très avantageuse en termes de coûts de réseau.
Pour pouvoir recevoir une réponse encodée au format gzip, vous devez effectuer deux opérations : définir un en-tête Accept-Encoding
et modifier votre user-agent afin d'y inclure la chaîne gzip
. Voici un exemple d'en-têtes HTTP syntaxiquement corrects pour l'activation de la compression gzip :
Accept-Encoding: gzip User-Agent: my program (gzip)
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 définir 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 une API générique (fictive) nommée "demo".
Requête simple : cette requête HTTP GET
omet le paramètre fields
et renvoie la ressource complète.
https://www.googleapis.com/demo/v1
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.
{ "kind": "demo", ... "items": [ { "title": "First title", "comment": "First comment.", "characteristics": { "length": "short", "accuracy": "high", "followers": ["Jo", "Will"], }, "status": "active", ... }, { "title": "Second title", "comment": "Second comment.", "characteristics": { "length": "long", "accuracy": "medium" "followers": [ ], }, "status": "pending", ... }, ... ] }
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.
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
Réponse partielle : suite à la requête ci-dessus, le serveur renvoie une réponse qui ne contient que les informations "kind" ainsi qu'un tableau d'éléments ("items") dépouillé, ne comprenant que les données de titre HTML et des caractéristiques de longueur dans chaque élément.
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
Notez que la réponse est un objet JSON, qui ne comprend que les champs sélectionnés et leurs objets parents englobants.
La syntaxe du paramètre fields
et le détail des éléments renvoyés dans la réponse sont décrits 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/b
pour sélectionner un champb
imbriqué dans le champa
. Inclueza/b/c
pour sélectionner un champc
imbriqué dans le champb
.
Exception : Pour les réponses de l'API qui utilisent des wrappers "data", lorsque la réponse est imbriquée dans un objet
data
de typedata: { ... }
, n'incluez pasdata
dans la spécificationfields
. L'ajout de l'objet de données à une spécification "fields" commedata/a/b
génère une erreur. Utilisez plutôt une spécificationfields
simple commea/b
. - 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=items(id,author/email)
ne renvoie que l'ID d'élément et l'adresse e-mail de l'auteur pour chaque élément du tableau. Vous pouvez aussi spécifier un sous-champ unique, oùfields=items(id)
équivaut àfields=items/id
. - Si nécessaire, incluez des caractères génériques dans les sélections de champs.
Par exemple,
fields=items/pagemap/*
sélectionne tous les objets du champ "pagemap".
Autres exemples d'utilisation du paramètre "fields"
Les exemples ci-dessous décrivent l'impact de l'utilisation de la valeur de paramètre fields
sur la réponse.
Remarque : Comme toutes les valeurs de paramètre de requête, la valeur du paramètre fields
doit être encodée au format URL. Pour faciliter la lecture, les exemples de ce document omettent l'encodage.
- 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, et chaque champ est spécifié en relation avec la racine de la réponse. Ainsi, lorsque vous exécutez une opération list, 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 :
Exemples Effet items
Renvoie tous les éléments du tableau d'éléments, y compris tous les champs de chaque élément, mais aucun autre champ. etag,items
Renvoie le champ etag
ainsi que tous les éléments du tableau "items".items/title
Ne renvoie que le champ title
pour tous les éléments du tableau "items".
Chaque fois qu'un champ imbriqué est renvoyé, la réponse inclut les objets parents qui le contiennent. Les champs parents n'incluent pas d'autres champs enfants, sauf si ceux-ci sont également sélectionnés de manière explicite.context/facets/label
Ne renvoie que le champ label
pour tous les membres du tableaufacets
, qui est lui-même imbriqué sous l'objetcontext
.items/pagemap/*/title
Pour chaque élément du tableau "items", ne renvoie que le champ title
(s'il existe) de tous les objets qui sont des enfants depagemap
.
Exemples pour les ressources :Exemples Effet title
Renvoie le champ title
de la ressource demandée.author/uri
Renvoie le sous-champ uri
de l'objetauthor
de la ressource demandée.links/*/href
Renvoie le champ href
de tous les objets enfants delinks
. - 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
( )
, conformément à l'exemple ci-dessous.Exemple Effet items(title,author/uri)
Ne renvoie que la valeur title
et la valeururi
de l'auteur pour chaque élément du tableau "items".
Traitement des réponses partielles
Après qu'un serveur a traité une demande correctement formulée 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 n'est pas correctement formulé 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"
).
Voici l'exemple de réponse partielle mentionné dans l'introduction ci-dessus. La requête contient le paramètre fields
de manière à spécifier les champs à renvoyer.
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
La réponse partielle se présente comme suit :
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
Remarque : Dans le cas des API qui acceptent des paramètres de requête pour la pagination des données (par exemple, maxResults
et nextPageToken
), utilisez ces paramètres afin que la taille des résultats de chaque requête soit gérable. Cela permet de garantir l'amélioration des performances possible grâce à la réponse partielle.