Ce document décrit le protocole utilisé par les API Google Data, y compris des informations sur la requête, ses résultats, etc.
Pour en savoir plus sur les API Google Data, consultez le guide du développeur de données Google ainsi que le guide du protocole.
Audience
Ce document est destiné à toute personne souhaitant comprendre les détails du format XML et du protocole utilisés par les API Google Data.
Si vous souhaitez simplement écrire du code utilisant les API clientes Google Data, vous n'avez pas besoin de connaître ces informations détaillées. Vous pouvez utiliser les bibliothèques clientes spécifiques à chaque langage.
Toutefois, si vous souhaitez comprendre le protocole, lisez ce document. Par exemple, vous pouvez consulter ce document pour vous aider à effectuer les tâches suivantes:
- évaluer l'architecture de données Google
- coder à l'aide du protocole sans utiliser les bibliothèques clientes Google Data fournies
- Écrire une bibliothèque cliente dans un nouveau langage
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. Vous pouvez envoyer et recevoir des messages Google Data en utilisant un langage de programmation qui vous permet d'émettre des requêtes HTTP et d'analyser les réponses XML.
Détails du protocole
Cette section décrit le format des documents de données Google et la syntaxe des requêtes.
Format du document
Les données Google, Atom et RSS 2.0 partagent le même modèle de données de base: un conteneur qui contient à la fois des données globales et un nombre illimité d'entrées. Pour chaque protocole, le format est défini par un schéma de base, mais il peut être étendu à l'aide d'espaces de noms étrangers.
Les API Google Data peuvent utiliser le format de syndication Atom (pour les lectures et les écritures) ou le format RSS (pour les lectures uniquement).
Atom est le format par défaut de Google Data. Pour demander une réponse au format RSS, utilisez le paramètre /alt=rss/. Pour en savoir plus, consultez la section Requêtes de requête.
Lorsque vous demandez des données au format RSS, Google Data fournit un flux (ou une autre représentation de la ressource) au format RSS. S'il n'existe pas de propriété RSS équivalente pour une propriété de données Google donnée, Google Data utilise la propriété Atom et lui associe un espace de noms approprié pour indiquer qu'il s'agit d'une extension de RSS.
Remarque : La plupart des flux de données Google au format Atom utilisent l'espace de noms Atom comme espace de noms par défaut en spécifiant un attribut xmlns dans l'élément du flux. Consultez les exemples fournis dans la section consacrée aux exemples. Ainsi, les exemples de ce document ne spécifient pas explicitement atom: pour des éléments d'un flux au format Atom.
Les tableaux suivants présentent les représentations Atom et RSS des éléments du schéma. Toutes les données non mentionnées dans ces tableaux sont traitées comme du texte brut et s'affichent de la même manière dans les deux représentations. Sauf indication contraire, les éléments XML d'une colonne donnée se trouvent dans l'espace de noms correspondant à cette colonne. Ce récapitulatif utilise la notation XPath standard. Plus précisément, les barres obliques indiquent la hiérarchie des éléments et le signe @ indique l'attribut d'un élément.
Dans chacun des tableaux suivants, les éléments en surbrillance sont obligatoires.
Le tableau suivant présente les éléments d'un flux de données Google:
| Élément de schéma de flux | Représentation Atom | Représentation RSS |
|---|---|---|
| Titre du flux | /feed/title |
/rss/channel/title |
| ID du flux | /feed/id |
/rss/channel/atom:id |
| Lien HTML du flux | /feed/link[@rel="alternate"] \[@type="text/html"]/@href |
/rss/channel/link |
| Description du flux | /feed/subtitle |
/rss/channel/description |
| Langue du flux | /feed/@xml:lang |
/rss/channel/language |
| Droits d'auteur du flux | /feed/rights |
/rss/channel/copyright |
| Auteur du flux |
(Obligatoire dans certains cas ; voir la spécification Atom). |
/rss/channel/managingEditor |
| Date de la dernière mise à jour du flux | /feed/updated(format RFC 3339) |
/rss/channel/lastBuildDate(format RFC 822) |
| Catégorie de flux | /feed/category/@term |
/rss/channel/category |
| Schéma de catégorie de flux | /feed/category/@scheme |
/rss/channel/category/@domain |
| Générateur de flux | /feed/generator/feed/generator/@uri |
/rss/channel/generator |
| Icône du flux | /feed/icon |
/rss/channel/image/url (sauf s'il y a également un logo, auquel cas l'icône n'est pas incluse dans le flux) |
| Logo du flux | /feed/logo |
/rss/channel/image/url |
Le tableau suivant présente les éléments d'un flux de résultats de recherche Google Data. Notez que Google Data présente certains des éléments OpenSearch 1.1 Response dans ses flux de résultats de recherche.
| Élément de schéma du flux de résultats de recherche | Représentation Atom | Représentation RSS/OpenSearch |
|---|---|---|
| Nombre de résultats de recherche | /feed/openSearch:totalResults |
/rss/channel/openSearch:totalResults |
| Indice de départ des résultats de recherche | /feed/openSearch:startIndex |
/rss/channel/openSearch:startIndex |
| Nombre de résultats de recherche par page | /feed/openSearch:itemsPerPage |
/rss/channel/openSearch:itemsPerPage |
Le tableau suivant présente les éléments d'une entrée de données Google:
| Élément du schéma d'entrée | Représentation Atom | Représentation RSS |
|---|---|---|
| ID d'entrée | /feed/entry/id |
/rss/channel/item/guid |
| ID de la version d'entrée | (Facultatif) Intégrés dans EditURI (consultez la section Simultanéité optimale de ce document) | — |
| Titre de l'entrée | /feed/entry/title |
/rss/channel/item/title |
| Lien d'entrée | /feed/entry/link |
/rss/channel/item/link/rss/channel/item/enclosure/rss/channel/item/comments |
| Résumé de l'entrée |
(Obligatoire dans certains cas ; voir la spécification Atom). |
/rss/channel/item/atom:summary |
| Contenu de l'entrée |
Si aucun élément de contenu, l'entrée doit contenir au moins un élément |
/rss/channel/item/description |
| Auteur de l'entrée |
(Obligatoire dans certains cas ; voir la spécification Atom). |
/rss/channel/item/author |
| Catégorie d'entrée | /feed/entry/category/@term |
/rss/channel/item/category |
| Schéma de catégorie d'entrée | /feed/entry/category/@scheme |
/rss/channel/item/category/@domain |
| Date de publication de l'entrée | /feed/entry/published(RFC 3339) |
/rss/channel/item/pubDate(RFC 822) |
| Date de mise à jour de l'entrée | /feed/entry/updated(RFC 3339) |
/rss/channel/item/atom:updated(RFC 3339) |
Queries
Cette section explique comment utiliser le système de requête.
Principes de conception des modèles de requête
Le modèle de requête est intentionnellement très simple. Les principes de base sont les suivants:
- Les requêtes sont exprimées sous forme d'URI HTTP, et non plus comme des en-têtes HTTP ou dans la charge utile. L'un des avantages de cette approche est que vous pouvez créer un lien vers une requête.
- Les prédicats sont limités à un seul élément. Il n'existe donc aucun moyen d'envoyer une requête de corrélation, telle que "trouver tous les e-mails des personnes qui m'ont envoyé au moins 10 e-mails aujourd'hui".
- L'ensemble de propriétés sur lesquelles les requêtes peuvent effectuer des prédicats est très limité. La plupart des requêtes sont simplement des requêtes de recherche en texte intégral.
- L'ordre des résultats dépend de la mise en œuvre.
- Le protocole est naturellement extensible. Si vous souhaitez exposer d'autres prédicats ou trier votre service, vous pouvez facilement le faire en introduisant de nouveaux paramètres.
Requêtes de requête
Un client interroge un service Google Data en envoyant une requête HTTP GET. L'URI de la requête comprend l'URI de la ressource (FeedURI dans Atom) suivi des paramètres de requête. La plupart des paramètres de requête sont représentés par des paramètres d'URL ?name=value[&...] traditionnels. Les paramètres de catégorie sont gérés différemment (voir ci-dessous).
Par exemple, si l'URI est http://www.example.com/feeds/jo, vous pouvez envoyer une requête avec l'URI suivant:
http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z
Les services Google Data sont compatibles avec le protocole GET conditionnel HTTP. Ils définissent l'en-tête de réponse "Last-Modified" en fonction de la valeur de l'élément <atom:updated> dans le flux ou l'entrée renvoyés. Un client peut renvoyer cette valeur comme valeur de l'en-tête de requête If-Modified-Since pour éviter de récupérer à nouveau le contenu s'il n'a pas été modifié. Si le contenu n'a pas changé depuis le délai de modification If-Modified-Since, le service Google Data renvoie une réponse HTTP 304 (Non modifiée).
Un service Google Data doit accepter les requêtes par catégorie et les requêtes alt. La compatibilité avec d'autres paramètres est facultative. La transmission d'un paramètre standard non compris par un service donné génère une réponse 403 Forbidden. La transmission d'un paramètre non standard non compatible entraîne une réponse 400 Bad Request. Pour en savoir plus sur les autres codes d'état, consultez la section Codes d'état HTTP de ce document.
Les paramètres de requête standards sont résumés dans le tableau suivant. Toutes les valeurs des paramètres doivent être encodées au format URL.
| Paramètre | Signification | Remarques |
|---|---|---|
q |
Chaîne de requête en texte intégral |
|
/-/category |
Filtre par catégorie |
|
category |
Filtre par catégorie |
|
author |
Auteur de l'entrée |
|
alt |
Autre type de représentation |
|
updated-min, updated-max |
Limites à la date de mise à jour de l'entrée |
|
published-min, published-max |
Limites à la date de publication de l'entrée |
|
start-index |
Index de base 1 du premier résultat à récupérer |
|
max-results |
Nombre maximal de résultats à récupérer | Pour tout service associé à une valeur max-results par défaut (pour limiter la taille de flux par défaut), vous pouvez indiquer un nombre très élevé si vous souhaitez recevoir l'intégralité du flux. |
| ID d'entrée | ID d'une entrée spécifique à récupérer |
|
À propos des requêtes par catégorie
Nous avons décidé de spécifier un format légèrement inhabituel pour les requêtes de catégorie. Au lieu d'une requête semblable à celle-ci:
http://example.com/jo?category=Fritz&category=2006
nous utilisons:
http://example.com/jo/-/Fritz/2006
Cette approche identifie une ressource sans utiliser de paramètres de requête et génère des URI plus propres. Nous avons choisi cette approche pour les catégories, car nous pensons que les requêtes par catégorie seront les plus courantes.
Cette approche présente un inconvénient : nous vous demandons d'utiliser /-/ dans les requêtes de catégorie, afin que les services Google Data puissent distinguer les requêtes de catégorie des autres URI de ressources, tels que http://example.com/jo/MyPost/comments.
Réponses aux requêtes
Les requêtes renvoient un flux Atom, une entrée Atom ou un flux RSS, en fonction des paramètres de requête.
Les résultats de requête contiennent les éléments OpenSearch suivants directement sous l'élément <feed> ou l'élément <channel> (selon que les résultats sont Atom ou RSS):
openSearch:totalResults- Nombre total de résultats de recherche pour la requête (pas nécessairement présents dans le flux de résultats).
openSearch:startIndex- Index en base 1 du premier résultat.
openSearch:itemsPerPage- Nombre maximal d'éléments pouvant apparaître sur une page. Cela permet aux clients de générer des liens directs vers n'importe quel ensemble de pages suivantes. Toutefois, si vous pensez qu'il existe un problème avec ce nombre, consultez la remarque concernant
start-indexdans le tableau de la section Requêtes de requête.
Le flux de réponse et les entrées Atom peuvent également inclure l'un des éléments Atom et Google Data suivants (ainsi que d'autres éléments listés dans la spécification Atom):
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>- Spécifie l'URI vers lequel le flux Atom complet peut être récupéré.
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>- Indique l'URI (PostURI) du flux Atom (où les nouvelles entrées peuvent être publiées).
<link rel="self" type="..." href="..."/>- Contient l'URI de cette ressource. La valeur de l'attribut
typedépend du format demandé. Si aucune donnée n'est modifiée entre temps, l'envoi d'un autre GET à cet URI renvoie la même réponse. <link rel="previous" type="application/atom+xml" href="..."/>- Spécifie l'URI du fragment précédent de cet ensemble de résultats de requête, s'il est fragmenté.
<link rel="next" type="application/atom+xml" href="..."/>- Spécifie l'URI du prochain fragment de cet ensemble de résultats de requête, s'il est fragmenté.
<link rel="edit" type="application/atom+xml" href="..."/>- Indique l'URI de l'entrée Atom (dans laquelle vous envoyez une entrée mise à jour).
Voici un exemple de corps de réponse à une requête de recherche:
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
<id>http://www.example.com/feed/1234.1/posts/full</id>
<updated>2005-09-16T00:42:06Z</updated>
<title type="text">Books and Romance with Jo and Liz</title>
<link rel="alternate" type="text/html" href="http://www.example.net/"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="http://schemas.google.com/g/2005#post"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="self" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<generator version="1.0"
uri="http://www.example.com">Example Generator Engine</generator>
<openSearch:totalResults>2</openSearch:totalResults>
<openSearch:startIndex>0</openSearch:startIndex>
<entry>
<id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id>
<published>2005-01-09T08:00:00Z</published>
<updated>2005-01-09T08:00:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1009</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
<entry>
<id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id>
<published>2005-01-07T08:00:00Z</published>
<updated>2005-01-07T08:02:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1007</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
</feed>
Si le flux demandé est au format Atom, si aucun paramètre de requête n'est spécifié et si le résultat ne contient pas toutes les entrées, l'élément suivant est inséré dans le flux de premier niveau : <link rel="next" type="application/atom+xml" href="..."/>. Elle pointe vers un flux contenant l'ensemble d'entrées suivant. Les ensembles suivants contiennent un élément <link rel="previous" type="application/atom+xml" href="..."/> correspondant. En suivant tous les liens suivants, un client peut récupérer toutes les entrées d'un flux.
Codes d'état HTTP
Le tableau suivant décrit la signification des différents codes d'état HTTP dans le contexte des services de données Google.
| Coder | Explication |
|---|---|
| 200 OK | Aucune erreur. |
| CRÉATION 201 | La ressource a bien été créée. |
| 304 NON MODIFIÉ | La ressource n'a pas changé depuis l'heure spécifiée dans l'en-tête If-Modified-Since de la requête. |
| DEMANDE DE 400 MAL | URI ou en-tête de requête non valide, ou paramètre non standard non compatible. |
| 401 UNAUTHORIZED | Autorisation nécessaire. |
| 403 INTERDIT | Paramètre standard non compatible, échec de l'authentification ou de l'autorisation. |
| 404 INTROUVABLE | Ressource (flux ou entrée, par exemple) introuvable. |
| 409 CONFLICT | Le numéro de version spécifié ne correspond pas au dernier numéro de version de la ressource. |
| ERREUR DU SERVEUR INTERNE 500 | Erreur interne. Il s'agit du code par défaut utilisé pour toutes les erreurs non reconnues. |
Simultanéité (gestion des versions)
Il est parfois important de s'assurer que plusieurs clients ne s'écraseront pas accidentellement les uns avec les autres. Le plus simple est de s'assurer que la version actuelle d'une entrée modifiée par un client est identique à celle sur laquelle le client s'appuie sur ses modifications. Si un deuxième client effectue une mise à jour avant le premier, la mise à jour du premier est refusée, car le premier client ne base plus ses modifications sur la dernière version.
Dans les flux de données Google compatibles avec la gestion des versions, nous obtenons cette sémantique en ajoutant un ID de version à l'URI de chaque entrée. Notez que seul l'URI de modification est concerné, et non l'ID d'entrée. Dans ce schéma, chaque mise à jour modifie l'URI de l'entrée, ce qui garantit que les mises à jour ultérieures basées sur la version d'origine échouent. Les suppressions, bien entendu, sont identiques aux mises à jour de cette fonctionnalité. Si vous envoyez une suppression avec un ancien numéro de version, la suppression échoue.
Tous les flux de données Google ne sont pas compatibles avec la simultanéité optimiste. Dans un flux compatible, si le serveur détecte un conflit de version sur PUT ou DELETE, il répond par 409 Conflict. Le corps de la réponse contient l'état actuel de l'entrée (document d'entrée Atom). Il est conseillé au client de résoudre le conflit et de renvoyer la demande à l'aide de l'URI de la réponse 409.
Notes de motivation et de design
Cette approche de la simultanéité optimiste nous permet d'implémenter la sémantique que nous souhaitons sans nécessiter de nouveau balisage pour les ID de version, ce qui rend les réponses de Google Data compatibles avec les points de terminaison autres que Google Data Atom.
Au lieu de spécifier les ID de version, nous aurions pu examiner l'horodatage de la mise à jour sur chaque entrée (/atom:entry/atom:updated). Toutefois, l'utilisation de l'horodatage de mise à jour présente deux problèmes:
- Cela ne fonctionne que pour les mises à jour, pas pour les suppressions.
- Il oblige les applications à utiliser des valeurs de date/heure comme ID de version, ce qui complique l'ajustement des données Google sur de nombreux datastores existants.
Authentification
Lorsqu'un client tente d'accéder à un service, il peut être amené à lui fournir ses identifiants afin de prouver qu'il est autorisé à effectuer l'action en question.
L'approche qu'un client doit utiliser pour l'authentification dépend du type de client:
- Une application de bureau doit utiliser un système d'authentification spécifique à Google appelé Authentification du compte pour les applications installées (également appelé "ClientLogin"). (Les clients Web ne doivent pas utiliser ce système.)
- Un client Web (par exemple, une interface tierce à un service de données Google) doit utiliser un système d'authentification spécifique à Google appelé proxy d'authentification de compte pour les applications Web (également appelé "AuthSub").
Dans le système ClientLogin, le client de bureau demande à l'utilisateur ses identifiants, puis les envoie au système d'authentification de Google.
Si l'authentification réussit, le système renvoie un jeton que le client utilise par la suite (dans un en-tête d'autorisation HTTP) lors de l'envoi de requêtes Google Data.
Si l'authentification échoue, le serveur renvoie un code d'état 403 "Interdit" accompagné d'un en-tête WWW-Authenticate incluant une question d'authentification applicable à l'authentification.
Le système AuthSub fonctionne de la même manière, mais au lieu de demander ses identifiants à l'utilisateur, il le connecte à un service Google qui les demande. Le service renvoie ensuite un jeton que l'application Web peut utiliser. L'avantage de cette approche est que Google (plutôt que le frontal Web) traite et stocke les identifiants de l'utilisateur de manière sécurisée.
Pour en savoir plus sur ces systèmes d'authentification, consultez la présentation de l'authentification des données Google ou la documentation sur l'authentification des comptes Google.
État de la session
De nombreuses implémentations de la logique métier nécessitent de maintenir la durée de session, ce qui permet de suivre l'état de la session d'un utilisateur.
Google suit l'état de la session de deux façons: en utilisant des cookies et en utilisant un jeton qui peut être envoyé en tant que paramètre de requête. Les deux méthodes produisent le même effet. Nous recommandons aux clients d'accepter l'une de ces méthodes de suivi de l'état de la session (une seule suffit). Si un client n'accepte aucune de ces méthodes, il continuera à travailler avec les services Google Data, mais les performances risquent d'en pâtir par rapport à ceux qui acceptent ces méthodes. Plus précisément, si un client n'accepte pas ces méthodes, chaque requête entraîne une redirection. Par conséquent, chaque requête (et toutes les données associées) est envoyée deux fois au serveur, ce qui affecte les performances du client et du serveur.
Les bibliothèques clientes Google gèrent automatiquement l'état des sessions. Par conséquent, si vous utilisez nos bibliothèques, vous n'avez rien à faire pour bénéficier de l'assistance relative à l'état de la session.
Ressources supplémentaires
Les documents tiers suivants peuvent vous être utiles:
- Comparaison entre Atom et RSS
- Présentation d'Atom, par IBM
- Extensions Dublin Core vers RSS
- Les définitions de méthodes HTTP 1.1 et les spécifications pour
GET,POST,PUTetDELETE - Définitions des codes d'état HTTP 1.1
- Créer un protocole REST
- Concevoir des services Web de façon REST
- Présentation technique du langage XML
- Espaces de noms XML par l'exemple