Principes de base du protocole des API Google Data

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

Pour en savoir plus sur les API Google Data, consultez le guide du développeur de données Google et le guide de référence.

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.

Exemples

Les exemples suivants montrent les requêtes de protocole de l'API Data simples que vous pouvez envoyer à un service générique, 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 des API Google Data 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 suivante au serveur:

GET /myFeed

Le serveur répond:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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.

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"?>
<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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <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 répond avec 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"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <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>
</feed>

Mettre à jour une entrée

Pour mettre à jour une entrée existante, utilisez PUT avec l'URI de modification de l'entrée (tel que fourni par le serveur dans l'exemple précédent, dans l'élément <link rel="edit">).

Si votre pare-feu n'autorise pas PUT, 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: PUT

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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <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'URI de modification a changé. Il se termine maintenant par "/2/" au lieu de "/1/". Le numéro final de l'URI de modification correspond à un numéro de version. Pour en savoir plus sur les versions, consultez la section Simultanéité optimisée 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"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <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>

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

L'exemple suivant permet de supprimer une entrée:

DELETE /myFeed/1/2/

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:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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.

Ressources supplémentaires

Les documents tiers suivants peuvent vous être utiles:

Haut de page