Questions fréquentes

    Présentation

  1. Qu'est-ce qu'une API Google Data ?
  2. J'ai une demande de fonctionnalité ou un rapport de bug. Où dois-je publier ?
  3. Où puis-je poser une question sur une API spécifique ?
  4. Qu'est-ce que JSON ?
  5. Dois-je utiliser le format XML ? D'autres formats de données sont-ils disponibles ?
  6. Pourquoi utilisez-vous REST ?
  7. Avez-vous des conseils ou des exemples de code courts pour les problèmes courants ?
  8. Gmail dispose-t-il d'une API Data ?

    9. Authentification

  9. Quel est le nom du service dans ClientLogin pour chaque API Data ?
  10. Lorsqu'un utilisateur se déconnecte d'une application, est-il nécessaire d'en informer les serveurs de l'API ?
  11. Un jeton d'authentification ClientLogin a-t-il une date d'expiration ?
  12. J'ai une question d'ordre général sur les comptes Google. Où dois-je aller ?
  13. Comment m'authentifier auprès d'une API ?
  14. Quelle valeur dois-je utiliser pour le paramètre d'étendue AuthSub/OAuth 1 ?
  15. Existe-t-il différents types de jetons AuthSub ? Les jetons expirent-ils ?
  16. Quelle est la principale différence entre ClientLogin et AuthSub/OAuth 1 ?
  17. Puis-je utiliser l'authentification ClientLogin dans des applications Web tierces ?
  18. Qu'est-ce qu'un test CAPTCHA ?
  19. Comment générer un test CAPTCHA ?
  20. Dois-je utiliser ClientLogin dans mon application Web ?
  21. Comment trouver le nom d'utilisateur d'un utilisateur lorsque j'utilise AuthSub/OAuth 1 ?
  22. Comment utiliser OAuth 1 avec les bibliothèques clientes des API Google Data ?
  23. Comment utiliser AuthSub avec les bibliothèques clientes des API Google Data ?
  24. Comment utiliser ClientLogin avec les bibliothèques clientes des API Google Data ?

    25. Bibliothèques clientes

  25. Quels langages de programmation disposent de bibliothèques clientes compatibles avec Google ?
  26. Comment signaler un bug ou demander une fonctionnalité pour l'une des bibliothèques clientes Google Data ?
  27. Comment activer les options de débogage dans les bibliothèques clientes ?
  28. Où puis-je trouver des documents de référence pour les classes de la bibliothèque cliente ?

    29. Dépannage

  29. Quels sont les bons outils pour déboguer HTTP ?
  30. Comment obtenir des informations de journalisation HTTP dans la bibliothèque cliente Java ?
  31. Comment obtenir des informations de journalisation HTTP dans la bibliothèque cliente .NET ?
  32. Comment activer l'encodage gzip à partir des flux de données Google ?
  33. Pourquoi l'erreur "Unable to Connect to sslv2" s'affiche-t-elle lorsque j'utilise le client PHP ?
  34. Comment obtenir le document de service Atom qui décrit un flux ?

Présentation

Qu'est-ce qu'une API Google Data ?

Une API Google Data est une API basée sur le protocole Google Data. Le protocole Google Data est basé sur les formats de syndication Atom 1.0 et RSS 2.0, ainsi que sur le protocole de publication Atom (APP).

Le protocole Google Data étend ces normes de différentes manières, en utilisant les mécanismes d'extension intégrés aux normes. Les flux sont conformes aux formats de syndication Atom ou RSS. Le modèle de publication est conforme au protocole de publication Atom.

Le protocole fournit également un modèle général pour les flux, les requêtes et les résultats. Vous pouvez l'utiliser pour envoyer des requêtes et des mises à jour à n'importe quelle API Data.

J'ai une demande de fonctionnalité ou un rapport de bug. Où dois-je publier ?
 Consultez notre outil de suivi des problèmes. Recherchez votre demande de fonctionnalité et ajoutez-la à vos favoris pour montrer votre soutien et recevoir des informations sur son état.
Où puis-je poser une question sur une API spécifique ?
Si votre problème ne figure pas dans la liste ou si vous souhaitez obtenir des informations supplémentaires, vous pouvez consulter les groupes de discussion spécifiques à chaque API Google Data :
Qu'est-ce que JSON ?

JSON signifie JavaScript Object Notation.

JSON est un format d'échange de données léger dont la simplicité a entraîné une utilisation généralisée par les développeurs Web. Il est facile à lire et à écrire. Vous pouvez l'analyser à l'aide de n'importe quel langage de programmation, et ses structures correspondent directement aux structures de données utilisées dans la plupart des langages de programmation.

En savoir plus sur l'utilisation de JSON avec les API Google Data

Dois-je utiliser XML ? D'autres formats de données sont-ils disponibles ?
 Le format de données par défaut des API Google Data est XML, sous la forme d'un flux Atom. Toutefois, lorsque vous demandez un flux, vous pouvez spécifier un autre format à l'aide du paramètre de requête alt.
  • alt=rss
    Les données de réponse sont mises en forme en tant que flux RSS.
  • alt=json ou alt=json-in-script
     : renvoie une représentation JSON de la structure XML du flux Atom. L'avantage supplémentaire du format JSON est qu'il est plus facile à "analyser" dans le code client JavaScript. Pour le moment, l'utilisation de JSON n'est disponible qu'en lecture seule. Toutefois, l'utilisation de la bibliothèque cliente JavaScript avec les services Blogger, Contacts ou Agenda permet de lire et d'écrire des données.

    En savoir plus sur la demande et l'utilisation de flux JSON

  • alt=atom-in-script
    Semblable à alt=json-in-script, mais les résultats sont renvoyés sous forme de chaîne XML Atom plutôt que JSON.
  • alt=rss-in-script
    Semblable à alt=atom-in-script, mais les résultats sont renvoyés sous forme de chaîne XML RSS plutôt qu'Atom.

Pour en savoir plus sur les formats alternatifs, consultez le Guide de référence des données Google.

Pourquoi utilisez-vous REST ?
REST est simple, léger et évolutif. Il permet de représenter et d'exposer des données de manière très efficace.
Avez-vous des conseils ou des exemples de code courts pour les problèmes courants ?
Consultez le blog sur les conseils concernant les API Google Data pour obtenir de l'aide sur nos bibliothèques clientes et sur l'envoi de requêtes brutes.
Gmail dispose-t-il d'une API Data ?

Non, mais vous pouvez utiliser le flux Atom de Gmail avec AuthSub ou OAuth 1 pour demander un accès en lecture seule aux messages non lus d'un utilisateur. Le champ "scope" doit être défini sur https://mail.google.com/mail/feed/atom/. Voici un exemple de requête :

GET https://mail.google.com/mail/feed/atom/

Si vous souhaitez gérer vos e-mails, Gmail est également compatible avec IMAP/POP.

Authentification

Dans la documentation des API Google Data, "OAuth" fait référence à OAuth 1. Pour en savoir plus sur OAuth 2.0, consultez la documentation de votre API.

Quel est le nom du service dans ClientLogin pour chaque API Data ?
Un "nom de service" est une courte chaîne que le système d'authentification ClientLogin utilise pour identifier un service Google.
API Google Nom du service
API Data de Google Analytics analytics
API G Suite
(informations et gestion des domaines)		 apps
API Google Sites Data jotspot
API Blogger Data blogger
API Book Search Data print
API Calendar Data cl
API Google Code Search Data codesearch
API Contacts Data cp
Content API for Shopping structuredcontent
API Documents List Data writely
API Finance Data finance
Flux Atom Gmail mail
API Health Data health
weaver (bac à sable H9)
API Maps Data local
API Picasa Albums Web Data lh2
API Sidewiki Data annotateweb
API Spreadsheets Data wise
API Webmaster Tools sitemaps
API YouTube Data youtube

Pour en savoir plus sur les autres paramètres utilisés dans une requête ClientLogin, consultez la documentation ClientLogin.

Lorsqu'un utilisateur se déconnecte d'une application, est-il nécessaire d'en informer les serveurs de l'API ?
Non, il n'est pas nécessaire d'informer l'API Google Data lorsqu'un utilisateur se déconnecte d'une application. Toutefois, si votre application n'a plus besoin d'utiliser un jeton AuthSub émis, elle doit révoquer le jeton.
Un jeton d'authentification ClientLogin a-t-il une date d'expiration ?
Un jeton ClientLogin peut durer deux semaines à compter de la date d'émission, mais cette limite est spécifique au service et peut être plus courte.
J'ai une question d'ordre général sur les comptes Google. Où dois-je aller ?
Consultez le Centre d'aide des comptes Google.
Comment m'authentifier auprès d'une API ?
 Votre requête HTTP doit inclure un en-tête d'autorisation contenant un jeton obtenu à l'aide de ClientLogin, AuthSub ou OAuth 1.
Quelle valeur dois-je utiliser pour le paramètre d'étendue AuthSub/OAuth 1 ?
Un paramètre scope est requis par AuthSub et OAuth 1 pour identifier les services Google auxquels votre application aura accès. Pour en savoir plus sur OAuth 2.0, consultez la documentation de votre API spécifique.

API Google Nom du service ClientLogin
API Data de Google Analytics https://www.google.com/analytics/feeds/
API Google Sites Data http(s)://sites.google.com/feeds/
API Blogger Data http://www.blogger.com/feeds/
API Book Search Data http://www.google.com/books/feeds/
API Calendar Data http(s)://www.google.com/calendar/feeds/
API Contacts Data http(s)://www.google.com/m8/feeds/
Content API for Shopping https://www.googleapis.com/auth/structuredcontent
API Documents List Data http(s)://docs.google.com/feeds/
API Finance Data http://finance.google.com/finance/feeds/
Flux Atom Gmail https://mail.google.com/mail/feed/atom/
API Health Data https://www.google.com/health/feeds/
https://www.google.com/h9/feeds/ (bac à sable H9)
API Maps Data http://maps.google.com/maps/feeds/
API Picasa Albums Web Data http://picasaweb.google.com/data/
API Portable Contacts http://www-opensocial.googleusercontent.com/api/people
API Sidewiki Data http://www.google.com/sidewiki/feeds/
API Spreadsheets Data http(s)://spreadsheets.google.com/feeds/
API Webmaster Tools http://www.google.com/webmasters/tools/feeds/
API YouTube Data http://gdata.youtube.com
Existe-t-il différents types de jetons AuthSub ? Les jetons expirent-ils ?
 Il existe deux types de jetons AuthSub. Le premier est un jeton à usage unique qui est présenté à votre application Web via le paramètre de requête "token". Ce jeton expire la première fois qu'il est utilisé avec le service pour lequel il a été émis ou lorsqu'il est échangé contre un jeton de session.

Les jetons de session n'expirent pas, sauf s'ils sont explicitement révoqués par l'utilisateur ou par l'appel d'API AuthSubRevokeToken. Un jeton à usage unique ne peut être échangé contre un jeton de session que si l'URL AuthSubRequest d'origine est spécifiée session=1 en tant que paramètre de requête.
Quelle est la principale différence entre ClientLogin et AuthSub/OAuth 1 ?

AuthSub est conçu pour les applications Web. Il garantit que les identifiants des utilisateurs sont envoyés de manière sécurisée directement depuis le navigateur Web d'un utilisateur vers les serveurs de Google, plutôt que via un site Web tiers.

ClientLogin est destiné aux applications de bureau installées. Elle exige que l'application qui envoie la demande transmette les identifiants utilisateur à Google au nom de l'utilisateur.

Consultez la documentation sur l'API d'authentification du compte Google.

Puis-je utiliser l'authentification ClientLogin dans des applications Web tierces ?
 L'utilisation de ClientLogin dans des applications Web tierces est acceptable, mais fortement déconseillée. En règle générale, l'application Web ne doit jamais demander à un utilisateur ses identifiants de connexion (ils peuvent être espionnés). À la place, une application doit stocker les identifiants utilisateur côté serveur et disposer d'un seul "compte de service" qui est toujours utilisé pour l'authentification auprès de Google.
Qu'est-ce qu'un test CAPTCHA ?
Un CAPTCHA (acronyme de l'anglais "Completely Automated Public Turing test to tell Computers and Humans Apart") est un type de test question-réponse utilisé pour déterminer si l'utilisateur est un humain. Le terme est une marque déposée de l'université Carnegie Mellon. Pour en savoir plus, consultez Wikipédia. Nous avons implémenté CAPTCHA dans ClientLogin.
Comment générer un test CAPTCHA ?
Un algorithme propriétaire est utilisé pour déterminer quand un test CAPTCHA est requis lors de l'authentification. Les tentatives d'authentification répétées avec des identifiants incorrects génèrent souvent un défi CAPTCHA.
Dois-je utiliser ClientLogin dans mon application Web ?
Non, ClientLogin doit être utilisé par les applications installées sur le matériel appartenant à l'utilisateur. L'utilisation de l'API ClientLogin dans les applications Web n'est pas sécurisée et est fortement déconseillée.
Comment puis-je connaître le nom d'utilisateur de l'utilisateur lorsque j'utilise AuthSub/OAuth1 ?
 Étant donné que Google ne vous fournit qu'un jeton qui vous donne accès aux flux de l'utilisateur, vous ne connaissez peut-être pas son nom d'utilisateur. Cela peut poser problème si l'URL du flux que vous souhaitez utiliser contient le nom d'utilisateur. Dans ce cas, vous pouvez utiliser le nom d'utilisateur spécial default pour indiquer "l'utilisateur dont j'utilise le jeton d'authentification".
Comment utiliser OAuth 1 avec les bibliothèques clientes des API Google Data ?
 Consultez l'article Utiliser OAuth 1 avec les bibliothèques clientes des Google Data APIs.
Comment utiliser AuthSub avec les bibliothèques clientes des API Google Data ?
 Consultez l'article Utiliser AuthSub avec les bibliothèques clientes des Google Data APIs.
Comment utiliser ClientLogin avec les bibliothèques clientes des API Google Data ?
 Consultez l'article Utiliser ClientLogin avec les bibliothèques clientes des Google Data APIs.

Bibliothèques clientes

Quels langages de programmation disposent de bibliothèques clientes compatibles avec Google ?

Les bibliothèques clientes Java, .NET, Python et Objective-C sont officiellement compatibles avec Google. Notre partenaire Zend a également écrit une bibliothèque cliente PHP. À l'aide de ces bibliothèques, vous pouvez créer des requêtes de protocole de données Google, les envoyer à un service et traiter les réponses du serveur. Il existe également une bibliothèque cliente JavaScript qui n'est actuellement compatible qu'avec Blogger, Agenda et Google Contacts.

Si vous écrivez une bibliothèque cliente dans une langue autre que Java, .Net, Python ou Objective-C, et que vous souhaitez la partager avec la communauté des développeurs de l'API Data, publiez-la dans le groupe de discussion des API Google Data. Votre avis nous intéresse !

Comment signaler un bug ou demander une fonctionnalité pour l'une des bibliothèques clientes ?

Vous pouvez signaler les bugs ou demander des fonctionnalités pour les bibliothèques clientes aux emplacements suivants :

Après avoir signalé votre bug, créez un fil de discussion dans le forum des développeurs pour l'API concernée.

Comment activer les options de débogage dans les bibliothèques clientes de l'API Google Data ?
Pour savoir comment activer le débogage avec certaines bibliothèques clientes, veuillez consulter l'article suivant : Débogage des clients des API Google Data : explorer le trafic depuis votre programme.
Où puis-je trouver des documents de référence pour les classes de la bibliothèque cliente ?
Bibliothèque cliente Guide de référence
Java Javadoc
JavaScript JSdoc
.NET NDoc
PHP phpDoc
Python PyDoc

Dépannage

Quels sont les bons outils pour le débogage HTTP ?

Vous trouverez ci-dessous plusieurs outils, mais vous pouvez également lire l'article On the Wire: Network Capture Tools for API Developers (Sur le fil : outils de capture réseau pour les développeurs d'API), qui décrit en détail des exemples de WireShark et de Fiddler.

Wireshark
Wireshark est un "analyseur de protocole réseau". Il permet de capturer le trafic réseau et d'analyser le contenu. Il est très utile pour déboguer le trafic qui se produit dans les bibliothèques où vous n'avez pas accès directement aux flux de requêtes et de réponses HTTP. Le trafic entre votre application et les services d'authentification ne peut pas être analysé à l'aide de Wireshark, car la communication est chiffrée à l'aide de SSL. Wireshark peut également être utilisé pour analyser le trafic capturé à l'aide d'outils tels que tcpdump. Wireshark est disponible auprès des développeurs sous forme de code source et d'installateur Windows. Des packages tiers sont disponibles pour de nombreuses plates-formes.
Fiddler
Fiddler est un "proxy de débogage HTTP". Si vous pouvez configurer votre code ou votre environnement d'exécution pour utiliser un serveur proxy pour le trafic HTTP, Fiddler se situera entre votre application et les services de données Google, ce qui vous permettra d'inspecter le trafic. Fiddler 2 est compatible avec SSL. Fiddler n'est actuellement disponible que pour Windows.
cURL
cURL est un outil de ligne de commande qui peut effectuer des requêtes HTTP/HTTPS. Il est très utile pour tester rapidement les interactions avec un service sans avoir à créer d'abord la compatibilité HTTP dans votre client.
Comment obtenir des informations de journalisation HTTP dans la bibliothèque cliente Java ?

Les bibliothèques clientes Java utilisent le package java.util.logging pour activer la journalisation des requêtes HTTP. Cela vous permettra d'activer la journalisation des en-têtes pour les requêtes et les réponses, ainsi que des codes d'état et des URL de requête. Actuellement, les flux de requête et de réponse complets ne sont pas journalisés. Le nom de l'enregistreur utilisé pour ces journaux est com.google.gdata.client.http.HttpGDataRequest.

Si un code d'erreur est renvoyé par les serveurs, une exception est générée. Les classes d'exception héritent de com.google.gdata.util.ServiceException et incluent une méthode publique appelée getResponseBody(). Pour en savoir plus, consultez la documentation Javadoc.

Comment obtenir des informations de journalisation HTTP dans la bibliothèque cliente .NET ?
La bibliothèque .NET utilise les méthodes de traçage System.Diagnostics pour consigner le chemin d'exécution, si le traçage est activé. De plus, en cas d'erreur, une GDataRequestException est générée. L'exception contient un ResponseString qui vous permet d'accéder au corps de la réponse HTTP.
Comment activer l'encodage gzip à partir des flux de données Google ?

Pour pouvoir recevoir une réponse encodée au format gzip de l'une des API Google Data, 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 correctement mis en forme :

User-Agent: my program (gzip)
Accept-Encoding: gzip
Pourquoi l'erreur "Unable to Connect to sslv2" s'affiche-t-elle lorsque j'utilise le client PHP ?

Depuis juillet 2009, nous avons commencé à désactiver SSLv2 sur nos serveurs par mesure de précaution pour améliorer la sécurité. Malheureusement, un bug dans les premières versions de la bibliothèque cliente PHP publiées avant juillet 2007 (version 1.0.0 et versions antérieures) force les connexions à utiliser SSLv2. Lorsque vous vous connectez à un serveur sur lequel SSLv2 est désactivé, l'erreur suivante s'affiche :

PHP Fatal error:  Uncaught exception 'Zend_Http_Client_Adapter_Exception' with message 'Unable to Connect to sslv2://www.google.com:443.'

Pour corriger cette erreur, passez à une version plus récente de la bibliothèque cliente PHP, disponible sur http://framework.zend.com/download.

Si vous ne parvenez pas à passer à une version plus récente, vous pouvez résoudre ce problème en ajoutant le code suivant à votre application, où $gdata est votre instance existante de Zend_Gdata (ou la sous-classe appropriée) :

$gdata->getHttpClient()->setConfig(array('ssltransport' => 'ssl'));
Comment obtenir le document de service Atom qui décrit un flux ?

Vous pouvez obtenir le document de service Atom en transmettant le paramètre alt=atom-service dans la requête. Remarque : Seule la version 2 des API Google Data renverra un document de service conforme à la syntaxe du document de service AtomPub. La version 1 des API Google Data renverra toujours un document de service, mais il sera basé sur une spécification AtomPub antérieure (il existe des différences de syntaxe et d'espace de noms entre les deux versions).