Principes de base des protocoles

Avertissement: Cette page concerne les anciennes API Google, les API Google Data. Elle ne concerne que les API répertoriées dans l'annuaire des API Google Data, dont la plupart ont été remplacées par de nouvelles API. Pour en savoir plus sur une nouvelle API spécifique, consultez sa documentation. Pour en savoir plus sur l'autorisation des requêtes avec une API plus récente, consultez Authentification et autorisation des comptes Google.

Ce document décrit les principes de base du protocole de données Google utilisé par de nombreuses API Google, y compris des exemples de requêtes, de résultats, etc.

Pour en savoir plus sur le protocole de données Google, consultez la page de présentation du Guide du développeur et la documentation de référence du protocole.

Audience

Ce document est destiné à toute personne souhaitant comprendre l'idée générale du format et du protocole XML utilisés par les API Google Data.

Même si vous souhaitez simplement écrire du code utilisant des bibliothèques clientes spécifiques à chaque langage, vous pouvez consulter ce document pour comprendre ce qui se passe sous la couche d'abstraction de la bibliothèque cliente.

Dans ce document, nous partons du principe que vous comprenez les principes de base du XML, les espaces de noms, les flux syndiqués, les requêtes GET, POST, PUT et DELETE en HTTP, ainsi que le concept de "ressource" de HTTP. Pour en savoir plus, consultez la section Autres ressources de ce document.

Ce document ne repose sur aucun langage de programmation particulier. Votre client peut interagir avec le serveur à l'aide de n'importe quel langage de programmation qui vous permet d'émettre des requêtes HTTP et d'analyser les réponses XML.

Si vous voulez essayer les exemples de ce document sans écrire la moindre ligne de code, vous pouvez utiliser les utilitaires de ligne de commande cURL ou Wget. Pour en savoir plus, consultez les pages d'ajout manuel de ces utilitaires ou le document sur l'utilisation de cURL pour interagir avec les services utilisant le protocole de données Google.

Exemples

Les exemples suivants montrent les requêtes HTTP que vous pouvez envoyer directement à un service générique à l'aide du protocole de l'API Google Data Protocol, ainsi que les résultats que vous pouvez recevoir. Pour obtenir des exemples sur l'envoi des requêtes à l'aide de divers langages de programmation, consultez les exemples et les bibliothèques clientes propres aux différents langages. Pour en savoir plus sur l'utilisation du protocole de données Google avec des services Google spécifiques, consultez la documentation spécifique à ces services.

Demander un flux ou une autre ressource

Supposons qu'un flux s'appelle "/myFeed" et qu'il ne contienne actuellement aucune entrée. Pour l'afficher, envoyez la requête HTTP suivante au serveur:

GET /myFeed

Le serveur répond:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Bien que le flux ne contienne aucune entrée, il contient des métadonnées telles qu'un titre et le nom d'un auteur. Il contient également un identifiant de version, sous la forme d'un ETag HTTP.

Insérer une nouvelle entrée

Pour créer une entrée, envoyez une requête POST et fournissez la représentation XML de la nouvelle entrée:

POST /myFeed

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Notez que vous ne fournissez pas les éléments Atom <id>, <link> ou <updated> standards. Le serveur les crée en réponse à votre requête POST. Notez également que l'auteur d'un flux ne doit pas nécessairement être l'auteur d'une entrée.

Le serveur répond:

201 CREATED

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/1/'/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Rechercher une chaîne

Pour effectuer une recherche en texte intégral sur une chaîne particulière, envoyez une requête GET avec le paramètre q lorsque vous utilisez un service compatible avec les recherches en texte intégral. Pour en savoir plus sur les paramètres de requête, consultez la section Requêtes de requête dans le document de référence de protocole.

GET /myFeed?q=This

Le serveur renvoie un flux contenant toutes les entrées correspondant à la chaîne de recherche This. (Dans le cas présent, il n'y en a qu'un seul.)

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"S0wCTlpIIip7ImA0X0QI"'>
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my entry</content>
  </entry>
</feed>

Mettre à jour une entrée

Pour mettre à jour une entrée existante, procédez comme suit :

  1. Récupérez l'entrée que vous souhaitez mettre à jour.
  2. Apportez les modifications souhaitées.
  3. Envoyez une requête PUT, avec l'entrée mise à jour dans le corps du message, à l'URI de modification de l'entrée. Dans l'exemple précédent, l'URI de modification apparaît en tant qu'attribut href de l'élément <link rel='edit'>.

Vous devez également spécifier l'ETag de l'entrée d'origine pour vous assurer de ne pas écraser les modifications des autres.

Dans l'exemple suivant, nous remplaçons le texte de l'entrée de son ancienne valeur ("This is my entry") par une nouvelle valeur ("This is my first entry"):

PUT /myFeed/1/1/

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

Le serveur répond:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

Notez que l'ETag a changé. Pour en savoir plus sur les versions des ressources, consultez la section Gestion des versions des ressources (ETags) du document de référence du protocole.

Pour voir la nouvelle entrée en contexte, redemandez l'intégralité de la ressource:

GET /myFeed

Le serveur répond:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D08FQn8-eil7ImA9WxZbFEw."'>
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my first entry.</content>
  </entry>
</feed>

Remarque : Si votre pare-feu n'autorise pas PUT, exécutez un POST HTTP et définissez l'en-tête de remplacement de méthode comme suit:

X-HTTP-Method-Override: PUT

Supprimer une entrée

Pour supprimer une entrée existante, envoyez une requête DELETE à l'aide de l'URI de modification de l'entrée (fourni par le serveur dans l'exemple précédent).

Si votre pare-feu n'autorise pas DELETE, exécutez une requête HTTP POST et définissez l'en-tête de remplacement de méthode comme suit:

X-HTTP-Method-Override: DELETE

Lorsque vous supprimez une entrée, vous pouvez choisir d'effectuer une suppression conditionnelle (supprimer uniquement si l'entrée n'a pas changé depuis la dernière fois que vous l'avez récupérée) ou une suppression inconditionnelle. Pour en savoir plus, consultez la section Gestion des versions des ressources (ETags) du document de référence du protocole. Pour effectuer une suppression inconditionnelle, définissez l'en-tête HTTP suivant:

If-Match: *

L'exemple suivant supprime une entrée (si les en-têtes sont définis correctement):

DELETE /myFeed/1/

Le serveur répond:

200 OK

Exécutez un autre GET pour vérifier que le flux ne contient plus aucune entrée:

GET /myFeed

Le serveur répond avec un flux ne contenant que des métadonnées:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Si la suppression échoue, le serveur répond avec un code d'erreur. Pour en savoir plus, consultez la section Codes d'état HTTP du document de référence du protocole.

Demander des flux partiels ou des entrées (fonctionnalité expérimentale)

Contrairement à l'exemple simple fourni dans ce document, les flux peuvent être assez complexes dans la pratique. Avec certaines API, vous ne pouvez demander que les éléments ou les attributs qui vous intéressent, plutôt que la représentation complète des ressources. Lorsque vous évitez de récupérer et d'analyser des données inutiles, vous pouvez considérablement améliorer l'efficacité de votre application cliente.

Pour demander une réponse partielle, utilisez le paramètre de requête fields pour spécifier les éléments ou les attributs que vous souhaitez afficher. Pour en savoir plus, consultez la section Réponse partielle du document de référence du protocole.

L'exemple suivant ne demande que l'ID du flux, ainsi que l'auteur et le titre de chaque entrée de flux.

GET /myFeed?fields=id,entry(author)

Le serveur répond:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.example.com/myFeed</id>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
  </entry>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 2</title>
  </entry>
</feed>

Vous pouvez utiliser le paramètre fields avec tout type de requête qui renvoie des données. En plus de GET, cela inclut POST et PUT (ainsi que PATCH, qui est utilisé pour effectuer des requêtes de mise à jour partielle).

Remarque : Le paramètre de requête fields ne contrôle que les données renvoyées en réponse à une requête. Il n'a aucune incidence sur les données que vous devez fournir dans le corps d'une requête PUT, POST ou PATCH.

Vous trouverez ci-dessous des exemples pour POST et PUT.

  • Lorsque vous effectuez une requête POST pour une réponse partielle, vous devez toujours fournir les mêmes données que celles décrites dans la section Insérer une nouvelle entrée. L'exemple suivant demande une réponse partielle qui ne contient que le titre de la nouvelle entrée : 
    POST /myFeed?fields=title
      
...data...

    Le serveur répond:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
  • Lorsque vous effectuez une requête PUT pour une réponse partielle, vous devez toujours fournir une version modifiée de la représentation complète de la ressource, comme décrit dans la section Mettre à jour une entrée. L'exemple suivant demande une réponse partielle qui ne contient que la nouvelle valeur ETag de l'entrée modifiée : 
    PUT /myFeed/1/1?fields=@gd:etag
  
...data...

    Le serveur répond:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
  gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>

Mettre à jour des champs spécifiques (expérimental)

Si l'API que vous utilisez prend en charge les réponses partielles et comporte des champs modifiables, vous pouvez également éviter d'envoyer des données inutiles lors de la modification d'une entrée. La mise à jour partielle vous permet de n'envoyer que les données des champs à modifier.

Pour utiliser une mise à jour partielle, vous devez envoyer une requête PATCH au même URI de modification que celui que vous utilisez pour PUT. Les données que vous envoyez avec PATCH doivent respecter certaines conventions. Cependant, la sémantique est suffisamment flexible pour vous permettre de remplacer des données dans la ressource cible, d'y ajouter des données ou même d'en supprimer, le tout avec une seule requête.

Remarque : Comme pour PUT, vous devez spécifier l'ETag de l'entrée d'origine pour vous assurer de ne pas écraser les modifications des autres.

Pour en savoir plus sur PATCH et sa sémantique, consultez la section Mise à jour partielle du document de référence de protocole.

Cet exemple présente une requête de mise à jour partielle qui modifie le titre de l'entrée:

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag="EksPTg1Bfyp7IWA6WhJT"
    gd:fields='title'>
  <title>New Title</title>
</entry>

Lorsque le serveur reçoit une requête PATCH, il supprime d'abord tous les champs spécifiés par l'attribut gd:fields de l'entrée (le cas échéant). Il fusionne ensuite les données fournies dans le corps de la requête avec la ressource cible. Dans cet exemple, l'élément title est d'abord supprimé de la ressource cible, puis la nouvelle valeur "title" est fusionnée. Dans les faits, cette demande remplace l'ancien titre par le nouveau.

Notez cependant que la sémantique de PATCH consiste à fusionner la représentation partielle dans la ressource existante. Il n'est pas toujours nécessaire de supprimer un champ pour mettre à jour sa valeur.

  • Si le champ ne peut exister qu'une seule fois dans l'entrée cible, lors de la fusion, le champ de la représentation partielle écrase le champ correspondant dans l'entrée cible.
  • Si le champ peut exister plusieurs fois dans l'entrée cible, le champ partiel est ajouté à l'entrée cible lors de la fusion.

La différence entre la fusion des champs répétés et non répétés est présentée dans l'exemple suivant, qui ajoute un titre et un auteur à l'entrée sans utiliser l'attribut gd:fields pour supprimer l'un ou l'autre.

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:edtag="EksPTg1Bfyp7IWA6WhJT">
  <title>A new title</title>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>darcy@gmail.com</email>
  </author>
</entry>

Étant donné que la représentation d'entrée partielle ne comporte pas d'attribut gd:fields, aucun champ n'est supprimé. Toutefois, les nouvelles valeurs des éléments <title> et <author> sont fusionnées avec la ressource cible:

  • Étant donné qu'Atom n'autorise qu'un seul titre par entrée, le nouveau titre remplace la valeur existante. 
  • Étant donné qu'Atom autorise plusieurs auteurs par entrée, le nouvel auteur est ajouté à la liste des éléments d'auteur déjà présents dans la ressource cible.

    Remarque:Toutes les API ne sont pas conformes à la norme Atom. Par exemple, certaines API n'autorisent qu'un seul élément <author> par entrée, tandis que d'autres héritent de l'auteur d'entrée au niveau du flux (le champ est donc en lecture seule).

Une fois que le serveur a traité une requête PATCH valide, il renvoie un code d'état HTTP 200 ainsi qu'une copie de la représentation complète de l'entrée mise à jour.

Si vous préférez que le serveur ne renvoie que certains éléments ou attributs, vous pouvez utiliser le paramètre de requête fields avec PATCH pour demander une réponse partielle.

Ressources supplémentaires

Les documents tiers suivants peuvent vous être utiles:

Haut de page