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 mes posts ?
  3. Où dois-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 un exemple de code 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 d'API ?
  11. Un jeton d'authentification ClientLogin a-t-il une date d'expiration ?
  12. J'ai une question d'ordre général concernant les comptes Google. Où dois-je aller ?
  13. Comment puis-je m'authentifier auprès d'une API ?
  14. Quelle valeur dois-je utiliser pour le paramètre de champ d'application 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 captcha ?
  19. Comment puis-je générer un test CAPTCHA ?
  20. Dois-je utiliser ClientLogin dans mon application Web ?
  21. Comment trouver le nom d'utilisateur de l'utilisateur lorsque j'utilise AuthSub/OAuth 1 ?
  22. Comment utiliser OAuth 1 avec les bibliothèques clientes de l'API Google Data ?
  23. Comment utiliser AuthSub avec les bibliothèques clientes de l'API Google Data ?
  24. Comment utiliser ClientLogin avec les bibliothèques clientes de l'API Google Data ?

    25. Bibliothèques clientes

  25. Quels langages de programmation les bibliothèques clientes sont-elles 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 les documents de référence sur les classes de la bibliothèque cliente ?

    29. Dépannage

  29. Quels sont les bons outils pour le débogage 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 depuis les flux de données Google ?
  33. Pourquoi le message d'erreur "Impossible de se connecter à sslv2" s'affiche-t-il lorsque j'utilise le client PHP ?
  34. Comment obtenir le document de service Atom décrivant un flux ?

Présentation

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

Une API Google Data est une API basée sur le protocole de données Google. 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, à l'aide des 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 mes posts ?
Découvrez notre outil de suivi des problèmes. Recherchez votre demande de fonctionnalité et ajoutez-la à vos favoris pour ajouter votre soutien et recevoir des informations sur son état.
Où dois-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 précisions, il existe des groupes de discussion spécifiques à chaque API Google Data :
Qu'est-ce que JSON ?

JSON fait référence à JavaScript Object Notation.

JSON est un format d'échange de données léger dont la simplicité a été largement utilisée par les développeurs Web. Elle est facile à lire et à écrire. Vous pouvez l'analyser à l'aide de n'importe quel langage de programmation, et ses structures sont directement mappées aux structures de données utilisées dans la plupart des langages de programmation.

Découvrez comment utiliser JSON avec les API Google Data.

Dois-je utiliser le format 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 au format RSS.
  • alt=json ou alt=json-in-script
    Renvoie une représentation JSON de la structure XML du flux Atom. L'avantage 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.

    Découvrez comment demander et utiliser des flux JSON.

  • alt=atom-in-script
    Semblable à alt=json-in-script, mais les résultats sont renvoyés sous forme de chaîne Atom XML 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 que Atom.

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

Pourquoi utilisez-vous REST ?
REST est simple, léger, évolutif et peut parfaitement représenter et exposer des données.
Avez-vous des conseils ou un exemple de code pour les problèmes courants ?
Pour obtenir de l'aide concernant nos bibliothèques clientes et l'envoi de requêtes brutes, consultez le blog Astuces Google Data.
Gmail dispose-t-il d'une API Data ?

Non, mais vous pouvez utiliser le flux Atom de Gmail avec AuthSub ou OAuth 1 afin de demander un accès en lecture seule aux messages non lus d'un utilisateur. Le champ d'application doit être défini sur https://mail.google.com/mail/feed/atom/. 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 le protocole 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 individuelle.

Quel est le nom du service dans ClientLogin pour chaque API Data ?
Un "nom de service" est une brève chaîne que le système d'authentification ClientLogin utilise pour identifier un service Google.
API Google Nom du service
API de données Google Analytics analytics
API G Suite
(Information et gestion du domaine)		 apps
API Google Sites Data jotspot
API de données Blogger 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 de données Picasa Albums Web lh2
API Sidewiki Data annotateweb
API Table Data wise
API Outils pour les webmasters 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 d'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.
Les jetons d'authentification ClientLogin ont-ils 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 inférieure.
J'ai une question d'ordre général concernant les comptes Google. Où dois-je aller ?
Consultez le Centre d'aide des comptes Google.
Comment puis-je 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 de champ d'application 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 de données Blogger 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 de données Picasa Albums Web 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 Table Data http(s)://spreadsheets.google.com/feeds/
API Outils pour les webmasters 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, 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 via l'utilisateur ou l'appel d'API AuthSubRevokeToken. Un jeton de session unique ne peut être échangé contre un jeton de session que si l'URL d'origine AuthSubRequest spécifie session=1 comme 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 permet de s'assurer que les identifiants utilisateur 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 nécessite que l'application demandeuse transmette les identifiants de l'utilisateur à Google pour le compte de l'utilisateur.

Consultez la documentation sur l'API Google Account Authentication.

Puis-je utiliser l'authentification ClientLogin dans des applications Web tierces ?
L'utilisation de ClientLogin dans des applications Web tierces est acceptable, mais vivement déconseillée. L'application Web ne doit jamais demander à un utilisateur ses identifiants de connexion (ce qui peut être risqué). À la place, une application doit stocker les identifiants utilisateur côté serveur et posséder un seul "compte de service", qui sert toujours à s'authentifier auprès de Google.
Qu'est-ce qu'un captcha ?
Un test CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) est un type de test de type "réponse-test" permettant de déterminer si un utilisateur est humain ou non. Le terme est déposé par l'université Carnegie Mellon. Pour en savoir plus, consultez Wikipédia. Nous avons implémenté le captcha dans ClientLogin.
Comment puis-je générer un test CAPTCHA ?
Un algorithme propriétaire détermine si une CAPTCHA est requise lors de l'authentification. Les tentatives d'authentification répétées avec des identifiants incorrects entraînent souvent un test 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 des applications Web n'est pas sécurisée et est fortement déconseillée.
Comment trouver le nom d'utilisateur de l'utilisateur lorsque j'utilise AuthSub/OAuth 1 ?
Étant donné que Google ne vous fournit qu'un jeton qui accorde l'accès aux flux des utilisateurs, vous ne connaissez peut-être pas leur nom d'utilisateur. Cela peut poser un problème si l'URL de flux que vous souhaitez utiliser contient le nom d'utilisateur. Dans ce cas, vous pouvez utiliser le nom d'utilisateur spécial default pour désigner l'utilisateur dont vous utilisez le jeton d'authentification.
Comment utiliser OAuth 1 avec les bibliothèques clientes de l'API Google Data ?
Consultez l'article Utiliser OAuth 1 avec les bibliothèques clientes de l'API Google Data.
Comment utiliser AuthSub avec les bibliothèques clientes de l'API Google Data ?
Consultez l'article Utiliser AuthSub avec les bibliothèques clientes de l'API Google Data.
Comment utiliser ClientLogin avec les bibliothèques clientes de l'API Google Data ?
Consultez l'article Utiliser ClientLogin avec les bibliothèques clientes de l'API Google Data.

Bibliothèques clientes

Quels langages de programmation les bibliothèques clientes sont-elles compatibles avec Google ?

Les bibliothèques clientes Java, .NET, Python et Objective-C sont officiellement compatibles avec Google. En outre, notre partenaire Zend a écrit une bibliothèque cliente PHP. Ces bibliothèques vous permettent de créer des requêtes de protocole Google Data, de les envoyer à un service et de 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 un langage autre que Java, .Net, Python ou Objective-C et que vous souhaitez la partager avec la communauté de développeurs de l'API Data, publiez un message dans le groupe de discussion consacré aux API Google Data. Votre avis nous intéresse !

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

Les bugs ou les demandes de fonctionnalités liés aux bibliothèques clientes peuvent être signalés aux emplacements suivants:

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

Comment activer les options de débogage dans les bibliothèques clientes de l'API Google Data ?
Veuillez consulter l'article suivant pour découvrir comment activer le débogage avec certaines bibliothèques clientes : Déboguer les clients API Google Data: Explorer le trafic depuis votre programme
Où puis-je trouver les documents de référence sur 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 de débogage HTTP ?

Plusieurs outils sont listés ci-dessous, mais vous pouvez également consulter l'article On the Wire: Network Capture Tools for API Developers, qui fournit des exemples détaillés sur WireShark et Fiddler.

Wireshark
Wireshark est un "analyseur de protocole réseau". Il permet de capturer le trafic réseau et d'analyser le contenu. Elle est très utile pour déboguer le trafic survenant dans les bibliothèques pour lesquelles vous n'avez pas accès direct 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 avec 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 en tant que code source et programme d'installation Windows. Les 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 passe entre votre application et les services de données Google pour vous permettre 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. Elle est très utile pour tester rapidement les interactions avec un service sans avoir à créer d'abord la compatibilité avec le protocole 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. Vous pourrez ainsi activer la journalisation des en-têtes pour les requêtes et les réponses, ainsi que les codes d'état et les URL des requêtes. Actuellement, les requêtes et flux de réponse complets ne sont pas consignés. Le nom de l'enregistreur utilisé pour ces journaux est com.google.gdata.client.http.HttpGDataRequest.

Dans le cas où un code d'erreur est renvoyé par les serveurs, une exception est levée. Les classes d'exceptions héritent de com.google.gdata.util.ServiceException et incluent une méthode publique appelée getResponseBody(). Consultez Javadoc pour en savoir plus.

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é. En outre, en cas d'erreur, une exception 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 depuis les flux de données Google ?

Pour recevoir une réponse encodée au format gzip de l'une des API de données Google, 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". Exemple d'en-têtes correctement formés:

User-Agent: my program (gzip)
Accept-Encoding: gzip
Pourquoi le message d'erreur "Impossible de se connecter à sslv2" s'affiche-t-il lorsque j'utilise le client PHP ?

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

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, effectuez une mise à niveau vers une version plus récente de la bibliothèque cliente PHP, disponible à l'adresse http://framework.zend.com/download.

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

$gdata->getHttpClient()->setConfig(array('ssltransport' => 'ssl'));
Comment obtenir le document de service Atom décrivant 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 renvoie un document de service conforme à la syntaxe du document de service AtomPub. La version 1 des API Google Data renvoie quand même un document de service, mais elle est basée sur une spécification AtomPub brouillon précédente (des modifications de la syntaxe et de l'espace de noms ont été apportées entre les deux versions).