Conseils pour l'optimisation des performances

Ce document présente quelques techniques dont vous pouvez vous servir afin d'améliorer les performances de votre application. Dans certains cas, des exemples d'autres API ou d'API génériques sont utilisés pour illustrer les idées exposées. Les mêmes concepts sont valables pour l'API AdSense Host.

Sommaire

  1. Utiliser gzip
  2. Utiliser une partie des ressources
    1. Réponse partielle

Utiliser gzip

La compression gzip est un moyen pratique et facile de réduire la bande passante requise pour chaque demande. Même si la décompression des résultats nécessite du temps de traitement supplémentaire, la compression est généralement très avantageuse en matière de coûts de réseau.

Afin de recevoir une réponse codée au format gzip, vous devez effectuer deux opérations : définir un en-tête Accept-Encoding et modifier votre user-agent pour 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 API, vous pouvez également ne demander que l'ensemble des données qui vous intéressent. Ainsi, votre application ne transfère pas de champs inutiles, ne les analyse pas et ne les stocke pas, et peut utiliser les ressources, telles que le réseau, l'unité centrale et la mémoire, plus efficacement.

Réponse partielle

Par défaut, le serveur renvoie la représentation complète d'une ressource après avoir traité les demandes. 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 demande fields afin de spécifier les champs qui vous intéressent. Vous pouvez l'utiliser avec n'importe quelle demande renvoyant des données de réponse.

Exemple

L'exemple suivant illustre l'utilisation du paramètre fields avec une API générique "Démo" (fictive).

Demande simple : cette demande HTTP GET omet le paramètre fields et renvoie la ressource complète.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY

Réponse de la ressource complète : les données de la ressource complète comprennent 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",
    ...
  },
  ...
  ]
}

Demande de réponse partielle : la demande 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?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)

Réponse partielle : suite à la demande 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é, comprenant seulement 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 inclut seulement les champs sélectionnés et leurs objets parents englobants.

Le formatage du paramètre fields ainsi que les éléments précis renvoyés dans la réponse sont décrits en détail ci-après.

Récapitulatif de la syntaxe du paramètre fields

Le format de la valeur du paramètre de demande fields repose globalement sur la syntaxe XPath. La syntaxe qui est acceptée est résumée ci-après, et des exemples supplémentaires sont présentés dans la section suivante.

  • Utilisez 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 champ b imbriqué dans le champ a. Utilisez a/b/c pour sélectionner un champ c imbriqué dans le champ b.

    Exception : pour les réponses de l'API qui utilisent des codes d'accompagnement "data", lorsque la réponse est imbriquée dans un objet data de type data: { ... }, n'incluez pas "data" dans la spécification de fields. L'ajout de l'objet de données à une spécification fields telle que data/a/b génère une erreur. Utilisez plutôt une spécification fields simple telle que a/b.

  • Utilisez 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) renvoie seulement l'identifiant 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, utilisez des caractères génériques dans les sélections de champs.

    Par exemple : fields=items/pagemap/* sélectionne tous les objets au format 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 : À l'instar de toutes les valeurs de paramètre de requête, la valeur de paramètre fields doit être codée au format URL. Pour faciliter la lecture, les exemples de ce document omettent le codage.

Identifier les champs devant être renvoyés ou effectuer des sélections de champs
La valeur de paramètre de demande fields est une liste de champs séparés par une virgule, et chaque champ est spécifié relativement à la racine de la réponse. Ainsi, si 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 relativement à 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 "items", 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 d'éléments
items/title Renvoie seulement le champ title pour tous les éléments du tableau d'éléments

À chaque fois qu'un champ imbriqué est renvoyé, la réponse comprend les objets parents inclusifs. Les champs parents ne comprennent aucun autre champ enfant, sauf s'ils sont également explicitement sélectionnés.
context/facets/label Renvoie seulement le champ label pour tous les membres du tableau facets, qui est lui-même imbriqué sous l'objet context
items/pagemap/*/title Pour chaque élément du tableau "items", renvoie seulement le champ title (s'il existe) de tous les objets qui sont des enfants de pagemap

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'objet author de la ressource demandée
links/*/href
Renvoie le champ href de tous les objets qui sont des enfants de links
Demander seulement des parties de champs spécifiques à l'aide de sous-sélections
Par défaut, si votre demande spécifie des champs particuliers, le serveur renvoie les objets ou les éléments de tableau entiers. 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) Renvoie seulement la valeur title et la valeur uri 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 demande utilise le paramètre fields pour spécifier les champs à renvoyer.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&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 : Si l'API accepte des paramètres de requête pour la pagination des données (maxResults et nextPageToken, par exemple), utilisez-les afin de réduire à un niveau raisonnable la taille des résultats de chaque requête. Autrement, vous pourriez ne pas bénéficier des gains de performances associés aux réponses partielles.

Envoyer des commentaires concernant…