Sommaire
Introduction
Ce document est destiné aux développeurs qui souhaitent créer des applications pouvant interagir avec l'API Livres. Google Livres s'est donné pour mission de numériser le contenu littéraire mondial et de le rendre plus visible sur le Web. L'API Books permet de rechercher ce contenu et d'y accéder, ainsi que de créer et d'afficher une personnalisation autour de ce contenu.
Si vous ne connaissez pas les concepts de Google Livres, nous vous recommandons de lire la section Premiers pas avant de commencer à coder.
Autoriser les requêtes et identifier votre application
Chaque requête que votre application envoie à l'API Livres doit permettre à Google d'identifier votre application. Pour cela, vous pouvez procéder de deux manières : à l'aide d'un jeton OAuth 2.0 (qui autorise également la requête) et/ou à l'aide de la clé API de l'application. Voici comment déterminer l'option à utiliser :
- Si la requête nécessite une autorisation (par exemple, une demande de données privées d'un individu), l'application doit fournir un jeton OAuth 2.0 avec la requête. L'application peut également fournir la clé API, mais ce n'est pas obligatoire.
- Si la demande ne nécessite pas d'autorisation (par exemple, s'il s'agit d'une demande de données publiques), l'application doit fournir soit la clé API, soit un jeton OAuth 2.0, soit les deux, selon ce qui vous convient le mieux.
À propos des protocoles d'autorisation
Votre application doit autoriser les requêtes via le protocole OAuth 2.0. Les autres protocoles d'autorisation ne sont pas acceptés. Si votre application utilise la fonctionnalité Se connecter avec Google, certains aspects de l'autorisation sont traités pour vous.
Autoriser des requêtes avec OAuth 2.0
Les requêtes adressées à l'API Livres portant sur des données utilisateur non publiques doivent être autorisées par un utilisateur authentifié.
Les détails de la procédure d'autorisation (ou "flux") concernant OAuth 2.0 varient légèrement selon le type d'application que vous développez. La procédure générale suivante s'applique à tous les types d'applications :
- Lorsque vous créez votre application, vous l'enregistrez dans la console d'API Google. Google fournit ensuite des informations dont vous aurez besoin ultérieurement, dont un ID client et un code secret du client.
- Activez l'API Books dans la console Google APIs. Si l'API ne figure pas dans la console, ignorez cette étape.
- Lorsque votre application doit accéder à des données utilisateur, elle demande à Google un champ d'application d'accès particulier.
- Google affiche alors un écran d'autorisation, dans lequel l'utilisateur est invité à autoriser votre application à demander certaines de ses données.
- Si l'utilisateur accepte, Google attribue à votre application un jeton d'accès temporaire.
- Votre application demande des données utilisateur en joignant le jeton d'accès à la requête.
- Dès lors que Google valide la requête et le jeton, les données demandées sont renvoyées.
Certains flux comportent d'autres étapes, comme l'utilisation de jetons d'actualisation afin d'obtenir de nouveaux jetons d'accès. Pour en savoir plus sur les flux concernant divers types d'applications, consultez la documentation OAuth 2.0 de Google.
Voici les informations concernant le champ d'application OAuth 2.0 pour l'API Books:
https://www.googleapis.com/auth/books
Pour demander l'accès via OAuth 2.0, vous avez besoin du champ d'application ainsi que des informations fournies par Google lors de l'enregistrement de l'application (l'ID client et le code secret du client, par exemple).
Conseil : Les bibliothèques clientes des API Google peuvent gérer une partie de la procédure d'autorisation à votre place. Elles sont proposées pour une grande variété de langages de programmation. Pour en savoir plus, explorez les bibliothèques clientes et les exemples de code présentés sur la page Installer les bibliothèques clientes.
Obtenir et utiliser une clé API
Les requêtes adressées à l'API Livres portant sur des données publiques doivent être accompagnées d'un identifiant, qui peut être une clé API ou un jeton d'accès.
Pour obtenir une clé API :
- Ouvrez la page Identifiants dans la console API.
-
Deux types d'identifiants sont disponibles pour cette API.
Créez les identifiants appropriés pour votre projet :
-
OAuth 2.0 : chaque fois que votre application demande des données utilisateur privées, elle doit envoyer un jeton OAuth 2.0 en même temps que la requête. Votre application envoie d'abord un identifiant client, puis éventuellement un code secret du client pour obtenir un jeton. Vous pouvez générer des identifiants OAuth 2.0 pour des applications Web, des comptes de service ou des applications installées.
Pour en savoir plus, consultez la documentation OAuth 2.0.
-
Clés API : une demande qui ne fournit pas de jeton OAuth 2.0 doit envoyer une clé API. Cette clé identifie votre projet et vous donne accès à l'API, aux quotas et aux rapports.
L'API propose plusieurs types de restrictions applicables aux clés API. Si la clé API dont vous avez besoin n'existe pas déjà, créez-en une dans la console en cliquant sur Créer des identifiants > Clé API. Vous pouvez restreindre la clé avant de l'utiliser en production en cliquant sur Restreindre la clé et en sélectionnant l'une des restrictions.
-
Pour sécuriser vos clés API, suivez les bonnes pratiques pour utiliser des clés API en toute sécurité.
Une fois la clé API obtenue, votre application peut ajouter le paramètre de requête key=yourAPIKey à toutes les URL de requête.
La clé API peut s'intégrer aux URL en toute sécurité et ne nécessite pas d'encodage.
ID Google Livres
Vous devez spécifier des champs d'ID avec certains appels de méthode d'API. Trois types de pièces d'identité sont utilisés dans Google Livres:
- ID de volume : chaînes uniques attribuées à chaque volume dont Google Livres a connaissance.
_LettPDhwR0Cest un exemple d'ID de volume. Vous pouvez utiliser l'API pour obtenir l'ID de volume en envoyant une requête qui renvoie une ressource de volume. Vous trouverez l'ID de volume dans son champid. - ID d'étagère : valeurs numériques attribuées à une étagère dans la bibliothèque d'un utilisateur. Google fournit des sections prédéfinies pour chaque utilisateur avec les ID suivants :
- Favoris: 0
- Acheté: 1
- À lire: 2
- À lire: 3
- Déjà lus: 4
- Examiné: 5
- Consultés récemment: 6
- Mes e-books: 7
- Livres pour vous: 8 Si nous n'avons pas de recommandations pour l'utilisateur, cette étagère n'existe pas.
id). - ID utilisateur : valeurs numériques uniques attribuées à chaque utilisateur. Ces valeurs ne correspondent pas nécessairement à la même valeur d'ID que celle utilisée dans les autres services Google. Actuellement, le seul moyen de récupérer l'ID utilisateur consiste à l'extraire à partir de la ressource "selfLink" d'une ressource Bookshelf récupérée avec une requête authentifiée. Les utilisateurs peuvent également obtenir leur propre ID utilisateur sur le site Livres. Un utilisateur ne peut pas obtenir l'ID utilisateur d'un autre utilisateur via l'API ou le site Google Livres. L'autre utilisateur doit partager ces informations explicitement, par e-mail, par exemple.
ID sur le site Google Livres
Les ID que vous utilisez avec l'API Books sont les mêmes que ceux utilisés sur le site Google Livres.
- ID du volume
Lorsque vous consultez un volume particulier sur le site, vous pouvez trouver son ID dans le paramètre d'URL
id. Voici un exemple :https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
- ID de l'étagère (
)Lorsque vous affichez une étagère spécifique sur le site, vous pouvez trouver son ID dans le paramètre d'URL
as_coll. Voici un exemple :https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary
- ID utilisateur
Lorsque vous consultez votre bibliothèque sur le site, vous trouverez l'ID utilisateur dans le paramètre d'URL
uid. Voici un exemple :https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
Définition de la position géographique de l'utilisateur
Google Livres respecte les droits d'auteur, les contrats et les autres restrictions légales associés à la zone géographique de l'utilisateur final. Par conséquent, il se peut que certains utilisateurs ne puissent pas accéder au contenu des livres dans certains pays. Par exemple, certains livres ne peuvent être prévisualisés qu'aux États-Unis. Nous ignorons ces liens d'aperçu pour les utilisateurs d'autres pays. Par conséquent, les résultats de l'API sont limités en fonction de l'adresse IP de votre serveur ou de votre application cliente.
Utiliser des volumes
Effectuer une recherche
Vous pouvez effectuer une recherche de volumes en envoyant une requête HTTP GET à l'URI suivant:
https://www.googleapis.com/books/v1/volumes?q=search+terms
Cette requête ne comporte qu'un seul paramètre obligatoire:
q: recherche des volumes contenant cette chaîne de texte. Vous pouvez spécifier des mots clés spéciaux dans les termes de recherche à rechercher dans des champs spécifiques, par exemple :intitle:Renvoie les résultats contenant le texte qui suit ce mot clé.inauthor:Renvoie les résultats où le texte qui suit ce mot clé se trouve dans l'auteur.inpublisher:Renvoie les résultats où le texte qui suit ce mot clé se trouve dans l'éditeur.subject:Renvoie des résultats pour lesquels le texte qui suit ce mot clé figure dans la liste des catégories du volume.isbn:Renvoie les résultats où le texte qui suit ce mot clé correspond au numéro ISBN.lccn:Renvoie les résultats où le texte qui suit ce mot clé est le numéro de contrôle de la Bibliothèque du Congrès.oclc:Renvoie des résultats où le texte qui suit ce mot clé correspond au numéro du Online Computer Library Center.
Requête
Voici un exemple de recherche de l'expression "Flowers for Algernon" de Daniel Keyes :
GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey
Remarque: Une recherche ne nécessite pas d'authentification. Vous n'avez donc pas besoin de fournir l'en-tête HTTP Authorization avec la requête GET. Toutefois, si l'appel est effectué avec une authentification, chaque volume inclura des informations spécifiques à l'utilisateur, telles que l'état de l'achat.
Réponse
Si la requête aboutit, le serveur répond avec un code d'état HTTP 200 OK et les résultats du volume:
200 OK
{
"kind": "books#volumes",
"items": [
{
"kind": "books#volume",
"id": "_ojXNuzgHRcC",
"etag": "OTD2tB19qn4",
"selfLink": "https://www.googleapis.com/books/v1/volumes/_ojXNuzgHRcC",
"volumeInfo": {
"title": "Flowers",
"authors": [
"Vijaya Khisty Bodach"
],
...
},
{
"kind": "books#volume",
"id": "RJxWIQOvoZUC",
"etag": "NsxMT6kCCVs",
"selfLink": "https://www.googleapis.com/books/v1/volumes/RJxWIQOvoZUC",
"volumeInfo": {
"title": "Flowers",
"authors": [
"Gail Saunders-Smith"
],
...
},
{
"kind": "books#volume",
"id": "zaRoX10_UsMC",
"etag": "pm1sLMgKfMA",
"selfLink": "https://www.googleapis.com/books/v1/volumes/zaRoX10_UsMC",
"volumeInfo": {
"title": "Flowers",
"authors": [
"Paul McEvoy"
],
...
},
"totalItems": 3
}
Paramètres de requête facultatifs
Outre les paramètres de requête standards, vous pouvez utiliser les paramètres de requête suivants lorsque vous effectuez une recherche de volumes.
Format de téléchargement
Utilisez le paramètre download pour limiter les résultats renvoyés aux volumes dont le format de téléchargement est epub, en définissant sur la valeur epub.
L'exemple suivant permet de rechercher des livres qu'un téléchargement ePub est disponible:
GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
Filtrage
Vous pouvez utiliser le paramètre filter pour restreindre davantage les résultats renvoyés en le définissant sur l'une des valeurs suivantes:
partial: renvoie des résultats où au moins une partie du texte peut être prévisualisée.full: renvoie uniquement les résultats où l'ensemble du texte est visible.free-ebooks: renvoie uniquement les résultats correspondant à des e-books Google sans frais.paid-ebooks: renvoie uniquement les résultats qui sont des livres numériques Google avec un prix.ebooks: renvoie uniquement des e-books Google payants ou sans frais. Il peut s'agir, par exemple, de contenus d'éditeurs dont l'aperçu est limité et non commercialisé, ou de magazines.
L'exemple suivant limite les résultats de recherche aux livres disponibles en tant qu'e-books sans frais:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
Pagination
Vous pouvez paginer la liste des volumes en spécifiant deux valeurs dans les paramètres de la requête:
startIndex: position à laquelle commencer dans la collection. L'index du premier élément est 0.maxResults: nombre maximal de résultats à renvoyer. La valeur par défaut est 10, et la valeur maximale autorisée est 40.
Type d'impression
Vous pouvez utiliser le paramètre printType pour limiter les résultats renvoyés à un type d'impression ou de publication spécifique en le définissant sur l'une des valeurs suivantes:
all: pas de restriction selon le type d'impression (par défaut).books: renvoie uniquement les résultats qui sont des livres.magazines: renvoie des résultats sous forme de magazines.
L'exemple suivant limite les résultats de recherche aux magazines:
GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
Projection
Vous pouvez utiliser le paramètre projection avec l'une des valeurs suivantes pour spécifier un ensemble prédéfini de champs de volume à renvoyer:
full: renvoie tous les champs de volume.lite: renvoie uniquement certains champs. Consultez les descriptions des champs signalées par deux astérisques dans la documentation de référence sur le volume pour savoir quels champs sont inclus.
L'exemple suivant renvoie des résultats de recherche avec des informations de volume limitées:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
Tri
Par défaut, une requête de recherche de volumes renvoie des résultats maxResults, où maxResults est le paramètre utilisé dans la pagination (ci-dessus), triés par pertinence par rapport aux termes de recherche.
Vous pouvez modifier l'ordre en définissant le paramètre orderBy sur l'une des valeurs suivantes:
relevance: renvoie les résultats par ordre de pertinence des termes de recherche (valeur par défaut).newest: renvoie les résultats du plus récent au plus ancien.
L'exemple suivant répertorie les résultats par date de publication, de la plus récente à la plus ancienne:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey
Récupérer un volume spécifique
Vous pouvez récupérer des informations sur un volume spécifique en envoyant une requête HTTP GET à l'URI de la ressource de volume:
https://www.googleapis.com/books/v1/volumes/volumeId
Remplacez le paramètre de chemin d'accès volumeId par l'ID du volume à récupérer. Pour en savoir plus sur les ID de volume, consultez la section Identifiants Google Livres.
Requête
Voici un exemple de requête GET qui reçoit un seul volume:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey
Remarque: La récupération des informations de volume ne nécessite pas d'authentification. Vous n'avez donc pas besoin de fournir l'en-tête HTTP Authorization avec la requête GET. Toutefois, si l'appel est effectué avec une authentification, le volume inclura des informations spécifiques à l'utilisateur, telles que l'état de l'achat.
Réponse
Si la requête aboutit, le serveur affiche le code d'état HTTP 200 OK et la ressource de volume demandée:
200 OK
{
"kind": "books#volume",
"id": "zyTCAlFPjgYC",
"etag": "f0zKg75Mx/I",
"selfLink": "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC",
"volumeInfo": {
"title": "The Google story",
"authors": [
"David A. Vise",
"Mark Malseed"
],
"publisher": "Random House Digital, Inc.",
"publishedDate": "2005-11-15",
"description": "\"Here is the story behind one of the most remarkable Internet
successes of our time. Based on scrupulous research and extraordinary access
to Google, ...",
"industryIdentifiers": [
{
"type": "ISBN_10",
"identifier": "055380457X"
},
{
"type": "ISBN_13",
"identifier": "9780553804577"
}
],
"pageCount": 207,
"dimensions": {
"height": "24.00 cm",
"width": "16.03 cm",
"thickness": "2.74 cm"
},
"printType": "BOOK",
"mainCategory": "Business & Economics / Entrepreneurship",
"categories": [
"Browsers (Computer programs)",
...
],
"averageRating": 3.5,
"ratingsCount": 136,
"contentVersion": "1.1.0.0.preview.2",
"imageLinks": {
"smallThumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
"thumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
"small": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=2&edge=curl&source=gbs_api",
"medium": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=3&edge=curl&source=gbs_api",
"large": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=4&edge=curl&source=gbs_api",
"extraLarge": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=6&edge=curl&source=gbs_api"
},
"language": "en",
"infoLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&source=gbs_api",
"canonicalVolumeLink": "https://books.google.com/books/about/The_Google_story.html?id=zyTCAlFPjgYC"
},
"saleInfo": {
"country": "US",
"saleability": "FOR_SALE",
"isEbook": true,
"listPrice": {
"amount": 11.99,
"currencyCode": "USD"
},
"retailPrice": {
"amount": 11.99,
"currencyCode": "USD"
},
"buyLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&buy=&source=gbs_api"
},
"accessInfo": {
"country": "US",
"viewability": "PARTIAL",
"embeddable": true,
"publicDomain": false,
"textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
"epub": {
"isAvailable": true,
"acsTokenLink": "https://books.google.com/books/download/The_Google_story-sample-epub.acsm?id=zyTCAlFPjgYC&format=epub&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api"
},
"pdf": {
"isAvailable": false
},
"accessViewStatus": "SAMPLE"
}
}
Informations d'accès
La section accessInfo présente un intérêt particulier pour déterminer les fonctionnalités disponibles pour un e-book. epub est un e-book au format texte flottant. La section epub comporte une propriété isAvailable indiquant si ce type d'e-book est disponible.
Un lien de téléchargement s'affiche s'il existe un extrait du livre ou si l'utilisateur peut le lire parce qu'il l'a acheté ou s'il appartient au domaine public dans la zone géographique de l'utilisateur. pdf pour Google Livres indique une version numérisée de l'e-book avec des informations similaires, par exemple si elle est disponible et un lien de téléchargement. Google recommande des fichiers epub pour les lecteurs de livres numériques et les smartphones, car les pages numérisées peuvent être difficiles à lire sur ces appareils.
S'il n'y a pas de section accessInfo, le volume n'est pas disponible en tant qu'e-book Google.
Paramètres de requête facultatifs
Outre les paramètres de requête standards, vous pouvez utiliser le paramètre de requête suivant lorsque vous récupérez un volume spécifique.
Projection
Vous pouvez utiliser le paramètre projection avec l'une des valeurs suivantes pour spécifier un ensemble prédéfini de champs de volume à renvoyer:
full: renvoie tous les champs de volume.lite: renvoie uniquement certains champs. Consultez les descriptions des champs signalées par deux astérisques dans la documentation de référence sur le volume pour savoir quels champs sont inclus.
L'exemple suivant renvoie des informations de volume limitées pour un seul volume:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey
Utiliser des étagères
Récupérer la liste des étagères publiques d'un utilisateur
Pour récupérer la liste des étagères publiques d'un utilisateur, envoyez une requête HTTP GET à l'URI au format suivant:
https://www.googleapis.com/books/v1/users/userId/bookshelves
Remplacez le paramètre de chemin userId par l'ID de l'utilisateur dont vous souhaitez récupérer les étagères. Pour en savoir plus sur les ID utilisateur, consultez la section Identifiants Google Livres.
Requête
Voici un exemple :
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey
Étant donné qu'un utilisateur n'a pas besoin d'être authentifié pour récupérer des informations sur les étagères publiques, vous n'avez pas besoin de fournir l'en-tête HTTP Authorization avec la requête GET.
Réponse
Si la requête aboutit, le serveur répond avec le code d'état HTTP 200 OK et la liste des étagères:
200 OK
{
"kind": "books#bookshelves",
"items": [
{
...
},
{
"kind": "books#bookshelf",
"id": 3,
"selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
"title": "Reading now",
"description": "",
"access": "PUBLIC",
"updated": "2011-02-02T20:34:20.146Z",
"created": "2011-02-02T20:34:20.146Z",
"volumeCount": 2,
"volumesLastUpdated": "2011-02-02T20:34:20.110Z"
},
...
]
}
Paramètres de requête facultatifs
Vous pouvez utiliser les paramètres de requête standards lors de la récupération de la liste des étagères publiques d'un utilisateur.
Récupérer une étagère publique spécifique
Vous pouvez récupérer une étagère publique spécifique en envoyant une requête HTTP GET à l'URI au format suivant:
https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf
Remplacez les paramètres de chemin d'accès userId et étagère par les ID qui spécifient l'utilisateur et l'étagère que vous souhaitez récupérer. Pour en savoir plus, consultez la section Identifiants Google Livres.
Requête
Voici un exemple :
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey
Étant donné qu'un utilisateur n'a pas besoin d'être authentifié pour récupérer des informations sur les étagères publiques, vous n'avez pas besoin de fournir l'en-tête HTTP Authorization avec la requête GET.
Réponse
Si la requête aboutit, le serveur répond avec le code d'état HTTP 200 OK et la ressource "étagère" :
200 OK
{
"kind": "books#bookshelf",
"id": 3,
"selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
"title": "Reading now",
"description": "",
"access": "PUBLIC",
"updated": "2011-02-02T20:34:20.146Z",
"created": "2011-02-02T20:34:20.146Z",
"volumeCount": 2,
"volumesLastUpdated": "2011-02-02T20:34:20.110Z"
}
Paramètres de requête facultatifs
Vous pouvez utiliser les paramètres de requête standards lors de la récupération d'une étagère publique spécifique.
Récupérer une liste de volumes sur une étagère publique
Vous pouvez récupérer la liste des volumes figurant sur l'étagère publique d'un utilisateur en envoyant une requête HTTP GET à un URI au format suivant:
https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes
Requête
Voici un exemple :
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey
Remplacez les paramètres de chemin d'accès userId et étagère par les ID qui spécifient l'utilisateur et l'étagère que vous souhaitez récupérer. Pour en savoir plus, consultez la section Identifiants Google Livres.
Étant donné qu'un utilisateur n'a pas besoin d'être authentifié pour récupérer des informations sur les étagères publiques, vous n'avez pas besoin de fournir l'en-tête HTTP Authorization avec la requête GET.
Réponse
Si la requête aboutit, le serveur répond avec un code d'état HTTP 200 OK et la liste des étagères de l'utilisateur:
200 OK
{
"kind": "books#volumes",
"items": [
{
"kind": "books#volume",
"id": "AZ5J6B1-4BoC",
"etag": "kIzQA7IUObk",
"selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
"volumeInfo": {
"title": "The Girl Who Kicked the Hornet's Nest",
"authors": [
"Stieg Larsson"
],
"publisher": "Knopf",
"publishedDate": "2010-05-25",
...
},
{
"kind": "books#volume",
"id": "UvK1Slvkz3MC",
"etag": "otKmdbRgdFQ",
"selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
"volumeInfo": {
"title": "The Girl who Played with Fire",
"authors": [
"Stieg Larsson"
],
"publisher": "Knopf",
"publishedDate": "2009-07-28",
...
},
{
"kind": "books#volume",
"id": "OBM3AAAAIAAJ",
"etag": "xb47kTr8HsQ",
"selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
"volumeInfo": {
"title": "The Sign of Four",
"authors": [
"Sir Arthur Conan Doyle"
],
"publishedDate": "1890",
...
}
],
"totalItems": 3
}
Paramètres de requête facultatifs
Outre les paramètres de requête standards, vous pouvez utiliser le paramètre de requête suivant lorsque vous récupérez une liste de volumes sur une étagère publique.
Pagination
Vous pouvez paginer la liste des volumes en spécifiant deux valeurs dans les paramètres de la requête:
startIndex: position à laquelle commencer dans la collection. L'index du premier élément est 0.maxResults: nombre maximal de résultats à renvoyer. La valeur par défaut est 10, et la valeur maximale autorisée est 40.
Utiliser des étagères dans "Ma bibliothèque"
Toutes les requêtes "Ma bibliothèque" s'appliquent aux données de l'utilisateur authentifié.
Récupérer une liste de mes étagères
Vous pouvez récupérer la liste de toutes les étagères de l'utilisateur authentifié en envoyant une requête HTTP GET à l'URI, au format suivant:
https://www.googleapis.com/books/v1/mylibrary/bookshelves
Requête
Voici un exemple :
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey Authorization: /* auth token here */
Remarque: L'utilisateur doit être authentifié pour récupérer la liste des étagères "Ma bibliothèque". Vous devez donc fournir l'en-tête HTTP Authorization avec la requête GET.
Réponse
Si la requête aboutit, le serveur répond avec le code d'état HTTP 200 OK et la liste de toutes les étagères pour l'utilisateur actuellement authentifié:
200 OK
{
"kind": "books#bookshelves",
"items": [
{
"kind": "books#bookshelf",
"id": 0,
"selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/0",
"title": "Favorites",
"access": "PRIVATE",
"updated": "2011-04-22T04:03:15.416Z",
"created": "2011-04-22T04:03:15.416Z",
"volumeCount": 0,
"volumesLastUpdated": "2011-04-22T04:03:17.000Z"
},
{
"kind": "books#bookshelf",
"id": 3,
"selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
"title": "Reading now",
"access": "PUBLIC",
"updated": "2010-11-11T19:44:22.377Z",
"created": "2010-11-11T19:44:22.377Z",
"volumeCount": 1,
"volumesLastUpdated": "2010-11-11T19:44:22.341Z"
}
]
}
Paramètres de requête facultatifs
Vous pouvez utiliser les paramètres de requête standards lors de la récupération de la liste des étagères de l'utilisateur authentifié.
Récupérer une liste de volumes sur ma bibliothèque
Vous pouvez récupérer la liste des volumes figurant sur la bibliothèque de l'utilisateur authentifié en envoyant une requête HTTP GET à l'URI, au format suivant:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
Remplacez le paramètre de chemin d'accès étagère par l'ID de l'étagère. Consultez la section ID Google Livres pour en savoir plus sur les ID d'étagère.
Requête
Voici un exemple :
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey Authorization: /* auth token here */
Remarque: L'utilisateur doit être authentifié pour récupérer une liste des volumes "Ma bibliothèque". Vous devez donc fournir l'en-tête HTTP Authorization avec la requête GET.
Réponse
Si la requête aboutit, le serveur répond avec le code d'état HTTP 200 OK et la liste des volumes "étagère" :
200 OK
{
"kind": "books#volumes",
"items": [
{
"kind": "books#volume",
"id": "AZ5J6B1-4BoC",
"etag": "kIzQA7IUObk",
"selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
"volumeInfo": {
"title": "The Girl Who Kicked the Hornet's Nest",
"authors": [
"Stieg Larsson"
],
"publisher": "Knopf",
"publishedDate": "2010-05-25",
...
},
{
"kind": "books#volume",
"id": "UvK1Slvkz3MC",
"etag": "otKmdbRgdFQ",
"selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
"volumeInfo": {
"title": "The Girl who Played with Fire",
"authors": [
"Stieg Larsson"
],
"publisher": "Knopf",
"publishedDate": "2009-07-28",
...
},
{
"kind": "books#volume",
"id": "OBM3AAAAIAAJ",
"etag": "xb47kTr8HsQ",
"selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
"volumeInfo": {
"title": "The Sign of Four",
"authors": [
"Sir Arthur Conan Doyle"
],
"publishedDate": "1890",
...
}
],
"totalItems": 3
}
Paramètres de requête facultatifs
En plus des paramètres de requête standards, vous pouvez utiliser le paramètre de requête suivant lorsque vous récupérez une liste de volumes dans l'une des étagères de l'utilisateur authentifié.
Pagination
Vous pouvez paginer la liste des volumes en spécifiant deux valeurs dans les paramètres de la requête:
startIndex: position à laquelle commencer dans la collection. L'index du premier élément est 0.maxResults: nombre maximal de résultats à renvoyer. La valeur par défaut est 10.
Ajout d'un volume à ma étagère
Pour ajouter un volume à l'étagère de l'utilisateur authentifié, envoyez une requête HTTP POST à l'URI au format suivant:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume
Remplacez le paramètre de chemin d'accès étagère par l'ID de l'étagère. Consultez la section ID Google Livres pour en savoir plus sur les ID d'étagère.
La requête ne comporte qu'un seul paramètre obligatoire:
volumeId: ID du volume. Pour en savoir plus sur les ID de volume, consultez la section Identifiants Google Livres.
Requête
Voici un exemple d'ajout de "Flowers for Algernon" (Fleurs pour Algernon) à l'étagère "Favorites" (Favoris) :
POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/addVolume?volumeId=NRWlitmahXkC&key=yourAPIKey Authorization: /* auth token here */ Content-Type: application/json Content-Length: CONTENT_LENGTH
Remarque: L'utilisateur doit être authentifié pour apporter des modifications à une étagère. Vous devez donc fournir l'en-tête HTTP Authorization avec la requête POST. Cependant, aucune donnée n'est requise avec ce POST.
Réponse
Si la requête aboutit, le serveur répond avec le code d'état HTTP 204 No Content.
Paramètres de requête facultatifs
Vous pouvez utiliser les paramètres de requête standards lorsque vous ajoutez un volume à l'une des étagères de l'utilisateur authentifié.
Supprimer un volume de ma bibliothèque
Pour supprimer un volume de l'étagère de l'utilisateur authentifié, envoyez une requête HTTP POST à l'URI au format suivant:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume
Remplacez le paramètre de chemin d'accès étagère par l'ID de l'étagère. Consultez la section ID Google Livres pour en savoir plus sur les ID d'étagère.
La requête ne comporte qu'un seul paramètre obligatoire:
volumeId: ID du volume. Consultez la section ID Google Livres pour en savoir plus sur les ID de volume.
Requête
Voici un exemple de suppression de "Flowers for Algernon" (Fleurs pour Algernon) de l'étagère "Favorites" (Favoris) :
POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/removeVolume?volumeId=NRWlitmahXkC&key=yourAPIKey Authorization: /* auth token here */ Content-Type: application/json Content-Length: CONTENT_LENGTH
Remarque: L'utilisateur doit être authentifié pour apporter des modifications à une étagère. Vous devez donc fournir l'en-tête HTTP Authorization avec la requête POST. Cependant, aucune donnée n'est requise avec ce POST.
Réponse
Si la requête aboutit, le serveur affiche un code d'état 204 No Content.
Paramètres de requête facultatifs
Vous pouvez utiliser les paramètres de requête standards lorsque vous supprimez un volume de l'une des étagères de l'utilisateur authentifié.
Effacer tous les volumes de ma bibliothèque
Pour supprimer tous les volumes de la bibliothèque de l'utilisateur authentifié, envoyez une requête HTTP POST à l'URI au format suivant:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes
Remplacez le paramètre de chemin d'accès étagère par l'ID de l'étagère. Consultez la section ID Google Livres pour en savoir plus sur les ID d'étagère.
Requête
Voici un exemple pour effacer l'étagère "Favorites" (Favoris) :
POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/clearVolumes?key=yourAPIKey Authorization: /* auth token here */ Content-Type: application/json Content-Length: CONTENT_LENGTH
Remarque: L'utilisateur doit être authentifié pour apporter des modifications à une étagère. Vous devez donc fournir l'en-tête HTTP Authorization avec la requête POST. Cependant, aucune donnée n'est requise avec ce POST.
Réponse
Si la requête aboutit, le serveur affiche un code d'état 204 No Content.
Paramètres de requête facultatifs
Vous pouvez utiliser les paramètres de requête standards lorsque vous effacez tous les volumes de l'une des étagères de l'utilisateur authentifié.
Documentation de référence sur les paramètres de requête
Cette section récapitule les paramètres de requête que vous pouvez utiliser avec l'API Books.Toutes les valeurs des paramètres doivent être encodées au format URL.
Paramètres de requête standards
Les paramètres de requête qui s'appliquent à toutes les opérations de l'API Livres sont décrits sur la page Paramètres système.
Paramètres de requête spécifiques à l'API
Les paramètres de requête qui s'appliquent uniquement à des opérations spécifiques dans l'API Livres sont résumés dans le tableau suivant.
| Paramètres | Signification | Remarques | Applicabilité |
|---|---|---|---|
download |
Limiter l'accès aux volumes en fonction de la disponibilité du téléchargement. |
|
|
filter |
Filtrez les résultats de recherche par type de volume et par disponibilité. |
|
|
langRestrict |
Limite les volumes renvoyés à ceux associés à la langue spécifiée. |
|
|
maxResults |
Nombre maximal d'éléments à renvoyer avec cette requête. |
|
|
orderBy |
Ordre des résultats de recherche de volume. |
|
|
printType |
Limiter l'accès aux livres ou aux magazines. |
|
|
projection |
Limitez les informations de volume renvoyées à un sous-ensemble de champs. |
|
|
q |
Chaîne de requête en texte intégral. |
|
|
startIndex |
Position dans la collection à laquelle démarrer la liste des résultats. |
|
|
volumeId |
Identifie un volume associé à la requête. |
|