La fonctionnalité de liens dynamiques Google Livres vous permet de créer des liens plus fiables et personnalisables vers Google Livres à partir de votre site. Par exemple, cet outil vous permet de générer des liens "intelligents" qui ne s'affichent que lorsqu'un livre figure dans notre index, ou d'afficher des liens qui indiquent aux utilisateurs si un livre peut être prévisualisé sur Google Livres. La fonctionnalité Liens dynamiques vous permet également d'inclure une vignette dans votre lien vers Google Livres. L'objectif de ce document est de vous permettre d'ajouter rapidement cette fonctionnalité à votre site.
Remarque: Cette fonctionnalité était auparavant appelée "API Book Visibility".
L'assistant de prévisualisation est un outil intégré à Dynamic Links. Il vous permet d'ajouter encore plus facilement des liens vers des aperçus de livres à partir d'un site en copiant simplement quelques lignes de code. Ce document s'adresse aux développeurs plus avancés qui souhaitent personnaliser la façon dont ils établissent un lien vers Google Recherche de Livres.
Sommaire
- Audience
- Terminologie de Recherche de Livres
- Introduction
- Consignes relatives à la marque
- L'API côté client
- Modes synchrone et asynchrone
- Questions fréquentes
- Exemples de code
Audience
La documentation sur les liens dynamiques est destinée aux programmeurs qui souhaitent créer des applications Web qui redirigent vers des livres dans Google Livres. Dans cette documentation, nous partons du principe que vous connaissez le protocole HTTP et le langage JavaScript de base.
Terminologie de Google Recherche de Livres
Google Livres respecte les restrictions locales applicables aux droits d'auteur. Par conséquent, les aperçus ou l'affichage intégral de certains livres ne sont pas disponibles dans tous les pays. La visibilité est regroupée dans les classes suivantes:
- Tout afficher
- L'intégralité du livre peut être consultée. Ces livres peuvent appartenir au domaine public.
- Aperçu limité
- Une partie du livre est consultable. Ce livre est protégé par des droits d'auteur, et l'équipe Google Livres a reçu l'autorisation de rendre ces pages accessibles aux utilisateurs. À la différence de l'affichage d'extraits, ces livres ne permettent pas aux utilisateurs de consulter des pages entières.
- Affichage d'extraits et pas d'aperçu
- Les utilisateurs ne voient qu'une page "À propos du livre". Seuls de courts extraits du livre sont disponibles tout au plus. Ce livre n'a pas été numérisé ou est protégé par des droits d'auteur. Google Livres n'a pas reçu l'autorisation de présenter plus de quelques "extraits" liés au terme de recherche d'un utilisateur.
Présentation
La documentation sur les liens statiques décrit un moyen très simple de générer des URL vers la page d'un livre spécifique sur Google Livres. Malheureusement, il arrive qu'un livre donné ne figure pas dans l'index Google Livres ou qu'aucun aperçu ne soit disponible pour un utilisateur situé dans une zone géographique donnée. Les liens statiques étant "aveugles", ils n'aboutissent pas toujours correctement.
Les liens dynamiques constituent une autre méthode programmatique côté client permettant d'interroger la visibilité d'un livre à l'aide de JavaScript. Vous pouvez ainsi inclure des liens plus fiables et prévisibles vers Google Recherche de Livres, et proposer une expérience plus cohérente à vos utilisateurs. La visibilité varie en fonction de l'emplacement de l'utilisateur final. Par conséquent, l'interface de lien dynamique n'est pas conçue pour les requêtes côté serveur ou hors connexion.
Pour découvrir les fonctionnalités des liens dynamiques, passez aux exemples de code à la fin de ce document.
Consignes relatives à la marque
Lorsque vous affichez des liens dynamiques, vous devez respecter les consignes relatives à la marque qui régissent la famille de l'API Google Livres. En particulier,
- Vous devez gérer les mentions et les liens vers Google Livres.
- Vous ne devez utiliser que le bouton "Aperçu Google" approuvé lorsque vous créez un lien vers des aperçus sur Google Livres.
- Les liens textuels, les boutons, la documentation ou le texte descriptif doivent respecter les conventions d'attribution de noms approuvées. Par exemple, n'utilisez pas les verbes "télécharger" ou "lire" lorsque vous créez un lien vers des aperçus Google Livres, car seules les œuvres appartenant au domaine public peuvent être téléchargées dans leur intégralité.
Exemple de branding
![](https://google-developers.gonglchuangl.net/static/books/images/gbs_preview_button1.gif?authuser=0&hl=fr)
La section "Exemples" à la fin de ce document fournit des exemples supplémentaires conformes aux consignes actuelles relatives à la marque.
API côté client
Au cœur du lien dynamique côté client se trouve un format d'URL qui permet aux développeurs de créer des URL demandant des informations sur un ou plusieurs livres et d'envoyer les requêtes à Google Livres à l'aide de la balise <script>
.
- Exemple de syntaxe:
<script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback"></script>
Format de requête
Le format de l'URL est semblable à la syntaxe d'URL utilisée pour créer un lien vers des livres. Toutefois, le champ d'ID de livre peut contenir plusieurs ID de livre séparés par une virgule, et des paramètres "jscmd" et "callback" supplémentaires peuvent être ajoutés. Des arguments supplémentaires peuvent éventuellement être présents pour contrôler les filtres de visibilité.
Dynamic Links accepte plusieurs méthodes d'identification des livres: les ISBN, les numéros OCLC et les clés LCCN. L'API autorise les requêtes par lot dont la taille ne dépasse pas la taille maximale d'une requête GET.
- ISBN
&bibkeys=ISBN:0451526538
(L'API est compatible avec les codes ISBN 10 et 13.)- OCLC
&bibkeys=OCLC:36792831
- Numéro de contrôle de la Bibliothèque du Congrès
&bibkeys=LCCN:96072233
Format des résultats JSON
La réponse à cet appel contient des informations sur les livres demandés, qui sont renvoyés sous la forme d'un ou de plusieurs objets JSON. Les objets JSON utilisent la structure suivante:
JsonSearchResult { string bib_key; string info_url; string preview_url; string thumbnail_url; string preview; };
Ces champs fournissent les informations suivantes:
- bib_key
- Identifiant utilisé pour interroger ce livre.
- info_url
- URL d'une page Google Livres contenant des informations sur le livre (page "À propos de ce livre").
- preview_url
- URL vers l'aperçu du livre, qui redirige l'utilisateur directement vers la couverture du livre. Si vous ne disposez que de l'affichage d'extraits ou de l'absence d'aperçu des livres pour une requête, aucune URL d'aperçu n'est renvoyée.
- thumbnail_url
- URL d'une vignette de la couverture du livre.
- preview
- Valeur indiquant l'état de visibilité du livre:
full
(pour les livres en intégralité),partial
(pour les livres en aperçu limité) ounoview
(pour les livres avec aperçu ou sans aperçu). - intégrable
- Cette valeur booléenne est
true
si le livre peut être intégré à des pages tierces à l'aide de la visionneuse intégrée Recherche de Livres. - jscmd
- La demande est envoyée à Google Livres.
- rappel
- Nom de la fonction JavaScript à laquelle le retour est transmis.
- Q: Ai-je besoin d'une clé API ou d'une autre autorisation pour utiliser des liens dynamiques ?
- R: Aucune clé API ni autre autorisation n'est nécessaire pour utiliser des liens dynamiques. Pour commencer, copiez et collez l'un de nos exemples et commencez à le bricoler.
- Q: Qu'en est-il des navigateurs qui ne sont pas compatibles avec JavaScript ou qui l'ont désactivé ?
- R: Il n'existe aucun moyen de vérifier si Google Livres propose un livre lorsque JavaScript n'est pas activé dans le navigateur d'un utilisateur. Nous vous recommandons d'utiliser la structure de liens statique de Google Livres pour les navigateurs sans JavaScript. Toutefois, n'oubliez pas que vous ne pouvez pas savoir à l'avance si Google Livres dispose du livre vers lequel vous redirigez les internautes.
- Q: Combien de livres puis-je rechercher à la fois ?
- R: Le nombre de livres que vous pouvez rechercher n'est limité que par la longueur des demandes GET. Dans Microsoft Internet Explorer, la longueur d'URL maximale (2 083 caractères) limite la longueur des requêtes GET.
- Q: Google Livres affichait des résultats pour un livre il y a quelques instants. Pourquoi l'outil ne renvoie-t-il pas de résultats à présent ?
- R: Les développeurs émettent souvent un nombre atypique de requêtes. Vous risquez donc de faire pencher accidentellement les précautions de sécurité de Google Livres. Pour vérifier si c'est le cas, affichez les éléments renvoyés par l'API. S'il s'agit d'une demande de saisie d'un captcha, cela signifie que vous avez émis trop de requêtes. Nous vous recommandons de vous connecter à Google Livres et de réessayer.
- Q: Qu'en est-il de la confidentialité ?
- R: Lorsqu'il répond aux requêtes concernant la visibilité des livres, Google reçoit des données de journaux de serveur ne permettant pas d'identifier personnellement l'utilisateur. Nous accordons une grande importance à la confidentialité des utilisateurs et traitons ces données comme indiqué dans nos Règles de confidentialité. Si vous proposez un service qui inclut la visibilité des livres, vous pouvez les informer que votre service envoie également des requêtes à Google via des liens dynamiques.
- Bouton "Aperçu" d'une page de livre
Si vous prévoyez d'utiliser des liens dynamiques pour ajouter des boutons "Aperçu" à des pages de livres spécifiques sur votre site, cet exemple est fait pour vous. Cette implémentation utilise un appel synchrone vers Google Livres. - Liste de lecture du cours
Cet exemple présente une liste de livres typique pour un cours universitaire. Nous utilisons un seul appel synchrone pour créer des liens vers les pages des livres sur Google Livres, ajouter des images de couverture et indiquer la disponibilité des aperçus. - Autre liste de livres
Comme dans l'exemple précédent, cet exemple ajoute des liens à Recherche de Livres à l'aide d'un rappel d'API asynchrone. - AJAX interactif
L'utilisation de liens dynamiques dans une application AJAX hautement interactive peut vous intéresser. Cet exemple montre comment émettre plusieurs appels différents sans actualiser la page.
La réponse est un objet JSON avec deux champs, "books" (livres) qui ont la valeur "map" d'objets "book" et "options", qui contient la liste des options activées pour cette requête. Si aucune option n'a été spécifiée, le champ "options" peut être omis dans la réponse. Exemple :
Request: https://books.google.com/books?jscmd=viewapi&bibkeys=0596000278,00-invalid-isbn,ISBN0765304368,0439554934&callback=ProcessGBSBookInfo Response: ProcessGBSBookInfo({ "0596000278":{ "bib_key":"0596000278", "info_url":"https://books.google.com/books?id=ezqe1hh91q4C&source=gbs_ViewAPI", "preview_url":"https://books.google.com/books?id=ezqe1hh91q4C&printsec=frontcover&sig=zSQ5gwlX1NZl_24M86KS8Rbj33Q&source=gbs_ViewAPI", "thumbnail_url":"https://books.google.com/books?id=ezqe1hh91q4C&pg=PR3&img=1&zoom=5&sig=bBmzIAIiCtMcM7Ii7TUHycqqEWg", "preview":"partial" }, "ISBN0765304368":{ "bib_key":"ISBN0765304368", "info_url":"https://books.google.com/books?id=gfg13CM_kU8C&source=gbs_ViewAPI", "preview_url":"https://books.google.com/books?id=gfg13CM_kU8C&printsec=frontcover&sig=jIrSb_SkcQRhy_VvtnKbTXjmvos&source=gbs_ViewAPI", "thumbnail_url":"https://books.google.com/books?id=gfg13CM_kU8C&pg=PP1&img=1&zoom=5&sig=LsTwGVAsy_qWYMPM6HVDTPAMokg", "preview":"full" }, "0439554934":{ "bib_key":"0439554934", "info_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI", "preview_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI", "thumbnail_url":"https://books.google.com/books?id=iwiYGwAACAAJ&printsec=frontcover&img=1&zoom=5&sig=_L6ySKDAs-8gNK28c3NyFdO22ZM", "preview":"noview"} });
Les développeurs peuvent ensuite modifier le contenu et l'apparence de leurs pages Web en fonction des résultats JSON récupérés sur le serveur GBS. Pour le moment, GBS ne fournit pas de bibliothèques permettant de modifier le DOM à cet effet.
Paramètres et champs supplémentaires
Modes synchrone et asynchrone
Mode asynchrone
En mode asynchrone, le développeur place la balise <script>
dans la section <head>
du document et construit l'URL avec tous les identifiants nécessaires à l'affichage de la page. Les données sont reçues de l'appel dans une variable. Les informations du livre sont ainsi disponibles dans le reste du document et sont accessibles immédiatement dans les langages HTML et JavaScript.
Mode synchrone
En mode synchrone, le développeur utilise l'URL au milieu du fichier HTML <body>
. La réponse est gérée à l'aide d'un rappel JavaScript.
Questions fréquentes
Exemples de code
Cette section fournit des exemples qui illustrent différentes manières d'utiliser Dynamic Links. Vous pouvez cliquer sur n'importe quel exemple pour le voir en action. Pour voir le code sous-jacent, affichez le code source depuis votre navigateur.