Contenuti
Introduzione
Questo documento è rivolto agli sviluppatori che desiderano scrivere applicazioni in grado di interagire con l'API Books. La missione di Google Libri è digitalizzare i contenuti dei libri a livello mondiale e renderli più rilevabili sul Web. L'API Books è un modo per cercare e accedere a tali contenuti, nonché per creare e visualizzare la personalizzazione per questi contenuti.
Se non hai dimestichezza con i concetti di Google Libri, ti consigliamo di leggere la Guida introduttiva prima di iniziare a programmare.
Autorizzazione delle richieste e identificazione dell'applicazione
Ogni richiesta che la tua applicazione invia all'API Books deve identificare la tua applicazione a Google. Esistono due modi per identificare la tua applicazione: utilizzando un token OAuth 2.0 (che autorizza anche la richiesta) e/o la chiave API dell'applicazione. Ecco come stabilire quali opzioni utilizzare:
- Se la richiesta richiede l'autorizzazione (ad esempio una richiesta per i dati privati di un privato), l'applicazione deve fornire un token OAuth 2.0 insieme alla richiesta. Anche l'applicazione potrebbe fornire la chiave API, ma non è obbligatorio.
- Se la richiesta non richiede l'autorizzazione (ad esempio una richiesta di dati pubblici), l'applicazione deve fornire la chiave API, un token OAuth 2.0 o entrambi, a seconda dell'opzione che preferisci.
Informazioni sui protocolli di autorizzazione
La tua applicazione deve utilizzare il protocollo OAuth 2.0 per autorizzare le richieste. Non sono supportati altri protocolli di autorizzazione. Se la tua applicazione utilizza la funzionalità Accedi con Google, alcuni aspetti dell'autorizzazione vengono gestiti per te.
Autorizzazione delle richieste con OAuth 2.0
Le richieste all'API Books relative a dati utente non pubblici devono essere autorizzate da un utente autenticato.
I dettagli della procedura di autorizzazione, o "flusso", per il protocollo OAuth 2.0 variano a seconda del tipo di applicazione che stai scrivendo. La seguente procedura generale si applica a tutti i tipi di applicazione:
- Quando crei la tua applicazione, la registri utilizzando la console API di Google. Quindi, Google fornisce informazioni che ti saranno necessarie in un secondo momento, ad esempio un ID client e un client secret.
- Attiva l'API Books nella console API di Google. (Se l'API non è elencata nella console API, salta questo passaggio.)
- Quando la tua applicazione vuole accedere ai dati dell'utente, chiede a Google un particolare ambito di accesso.
- Google mostra una schermata di consenso all'utente, chiedendo di autorizzare l'applicazione a richiedere dei dati.
- Se l'utente approva, Google fornisce alla tua applicazione un token di accesso di breve durata.
- L'applicazione richiede i dati utente, allegando il token di accesso alla richiesta.
- Se Google ritiene validi la richiesta e il token, restituisce i dati richiesti.
Alcuni flussi includono passaggi aggiuntivi, come l'uso di token di aggiornamento per acquisire nuovi token di accesso. Per informazioni dettagliate sui flussi per vari tipi di applicazioni, consulta la documentazione relativa al protocollo OAuth 2.0 di Google.
Ecco le informazioni relative all'ambito OAuth 2.0 per l'API Books:
https://www.googleapis.com/auth/books
Per richiedere l'accesso utilizzando il protocollo OAuth 2.0, l'applicazione richiede le informazioni relative all'ambito e le informazioni che Google fornisce quando registri la tua applicazione (ad esempio l'ID client e il client secret).
Suggerimento: le librerie client delle API di Google possono gestire parte del processo di autorizzazione per te. Sono disponibili per una varietà di linguaggi di programmazione; consulta la pagina delle librerie e dei campioni per maggiori dettagli.
Acquisizione e utilizzo di una chiave API
Le richieste all'API Books relative a dati pubblici devono essere accompagnate da un identificatore, che può essere una chiave API o un token di accesso.
Per acquisire una chiave API:
- Apri la pagina Credenziali nella console API.
-
Questa API supporta due tipi di credenziali.
Crea le credenziali appropriate per il tuo progetto:
-
OAuth 2.0:ogni volta che l'applicazione richiede dati privati dell'utente, deve inviare un token OAuth 2.0 insieme alla richiesta. L'applicazione invia innanzitutto un ID client e, possibilmente, un client secret per ottenere un token. Puoi generare credenziali OAuth 2.0 per applicazioni web, account di servizio o applicazioni installate.
Per ulteriori informazioni, consulta la documentazione relativa a OAuth 2.0.
-
Chiavi API: una richiesta che non fornisce un token OAuth 2.0 deve inviare una chiave API. La chiave identifica il progetto e fornisce accesso API, quota e report.
L'API supporta diversi tipi di limitazioni sulle chiavi API. Se la chiave API di cui hai bisogno non esiste già, creane una nella console facendo clic su Crea credenziali > Chiave API. Puoi limitare la chiave prima di utilizzarla in produzione facendo clic su Limita chiave e selezionando una delle Restrizioni.
-
Per proteggere le tue chiavi API, segui le best practice per l'utilizzo sicuro delle chiavi API.
Dopo aver ottenuto una chiave API, l'applicazione può aggiungere il parametro di query
key=yourAPIKey
a tutti gli URL delle richieste.
La chiave API è sicura per l'incorporamento negli URL; non è necessaria alcuna codifica.
ID Google Libri
Devi specificare i campi ID con determinate chiamate al metodo API. In Google Libri vengono utilizzati tre tipi di documenti di identità:
- ID volume: stringhe univoche assegnate a ogni volume noto a Google Libri. Un esempio di ID volume è
_LettPDhwR0C
. Puoi utilizzare l'API per ottenere l'ID volume effettuando una richiesta che restituisce una risorsa volume. Puoi trovare l'ID volume nel campoid
. - ID scaffale: valori numerici assegnati a uno scaffale nella raccolta di un utente. Google fornisce alcuni scaffali predefiniti per ogni utente con i seguenti ID:
- Preferiti: 0
- Acquistati: 1
- Da leggere: 2
- In lettura: 3
- Letto: 4
- Esaminato: 5
- Visualizzati di recente: 6
- I miei eBook: 7
- Libri per te: 8 Se non abbiamo consigli per l'utente, questa sezione non esiste.
id
. - ID utente: valori numerici univoci assegnati a ciascun utente. Questi valori non sono necessariamente lo stesso valore ID utilizzato in altri servizi Google. Attualmente, l'unico modo per recuperare l'ID utente è estrarlo dal selfLink in una risorsa BookSheet recuperata con una richiesta autenticata. Gli utenti possono anche ottenere il proprio ID utente dal sito Libri. Un utente non può ottenere l'ID utente di un altro utente tramite l'API o il sito Libri; l'altro utente dovrà condividere queste informazioni in modo esplicito, ad esempio via email.
ID sul sito di Google Libri
Gli ID che utilizzi con l'API Books sono gli stessi utilizzati sul sito di Google Libri.
- ID volume
Quando visualizzi un determinato volume sul sito, puoi trovare l'ID volume nel parametro URL
id
. Ecco un esempio:https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
- ID scaffale
Quando visualizzi un determinato scaffale sul sito, puoi trovare l'ID dello scaffale nel parametro URL
as_coll
. Ecco un esempio:https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary
- ID utente
Quando visualizzi la raccolta sul sito, puoi trovare lo User-ID nel parametro URL
uid
. Ecco un esempio:https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
Impostazione della località dell'utente
Google Libri rispetta copyright, contratto e altre restrizioni legali associate alla località dell'utente finale. Di conseguenza, alcuni utenti potrebbero non essere in grado di accedere ai contenuti dei libri da determinati paesi. Ad esempio, alcuni libri sono "visualizzabili in anteprima" solo negli Stati Uniti; i link di anteprima vengono omessi per gli utenti di altri paesi. Di conseguenza, i risultati dell'API sono limitati in base all'indirizzo IP del server o dell'applicazione client.
Utilizzo dei volumi
Esecuzione di una ricerca
Puoi eseguire una ricerca di volumi inviando una richiesta GET
HTTP al seguente URI:
https://www.googleapis.com/books/v1/volumes?q=search+terms
Questa richiesta ha un singolo parametro obbligatorio:
q
: cerca i volumi che contengono questa stringa di testo. Esistono parole chiave speciali che puoi specificare nei termini di ricerca per eseguire ricerche in determinati campi, ad esempio:intitle:
Restituisce risultati in cui il testo che segue questa parola chiave si trova nel titolo.inauthor:
Restituisce risultati in cui il testo che segue questa parola chiave si trova nell'autore.inpublisher:
restituisce i risultati in cui il testo che segue questa parola chiave si trova nel publisher.subject:
Restituisce risultati in cui il testo che segue questa parola chiave è elencato nell'elenco di categorie del volume.isbn:
restituisce risultati in cui il testo che segue questa parola chiave è il numero ISBN.lccn:
Restituisce risultati in cui il testo che segue questa parola chiave è il numero di controllo della Biblioteca del Congresso.oclc:
restituisce risultati in cui il testo che segue questa parola chiave è il numero dell'Online Computer Library Center.
Richiesta
Ecco un esempio di ricerca di "Fiori per Algernon" di Daniel Keyes:
GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey
Nota: l'esecuzione di una ricerca non richiede l'autenticazione, quindi
non devi fornire l'intestazione HTTP Authorization
con la
richiesta GET
. Tuttavia, se la chiamata viene effettuata con autenticazione, ogni volume includerà informazioni specifiche dell'utente, come lo stato dell'acquisto.
Risposta
Se la richiesta riesce, il server risponde con un codice di stato HTTP 200 OK
e i risultati del 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 }
Parametri di query facoltativi
Oltre ai parametri di query standard, puoi utilizzare i seguenti parametri di query quando esegui una ricerca di volumi.
Scarica formato
Puoi utilizzare il parametro download
per limitare i risultati restituiti ai volumi che hanno un formato di download epub
disponibile impostando
sul valore epub
.
Il seguente esempio consente di cercare libri per cui è disponibile il download epub:
GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
Applicazione dei filtri
Puoi utilizzare il parametro filter
per limitare ulteriormente i risultati restituiti impostandolo su uno dei seguenti valori:
partial
- Restituisce risultati in cui almeno parti del testo sono visualizzabili in anteprima.full
- Restituisce solo risultati in cui tutto il testo è visualizzabile.free-ebooks
- restituisce solo risultati che sono Google eBook senza costi.paid-ebooks
: restituisce solo risultati che sono Google eBook con un prezzo.ebooks
- Restituisce solo risultati che sono Google eBook, a pagamento o senza costi. Esempi di contenuti non ebook sono i contenuti degli editori disponibili in anteprima limitata e non per la vendita o le riviste.
L'esempio seguente limita i risultati di ricerca a quelli disponibili come ebook senza costi:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
Impaginazione
È possibile impaginare l'elenco dei volumi specificando due valori nei parametri per la richiesta:
startIndex
: la posizione nella raccolta da cui iniziare. L'indice del primo elemento è 0.maxResults
: il numero massimo di risultati da restituire. Il valore predefinito è 10, mentre il valore massimo consentito è 40.
Tipo di stampa
Puoi utilizzare il parametro printType
per limitare i risultati restituiti a un tipo di stampa o pubblicazione specifico impostandoli su uno dei seguenti valori:
all
: non limita in base al tipo di stampa (impostazione predefinita).books
: restituisce solo i risultati che sono libri.magazines
: restituisce risultati corrispondenti a riviste.
L'esempio seguente consente di limitare i risultati di ricerca alle riviste:
GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
Projection
Puoi utilizzare il parametro projection
con uno dei seguenti
valori per specificare un insieme predefinito di campi Volume da restituire:
full
- Restituisce tutti i campi del volume.lite
- Restituisce solo determinati campi. Consulta le descrizioni dei campi contrassegnati da doppi asterischi nel Riferimento al volume per scoprire quali campi sono inclusi.
L'esempio seguente restituisce risultati di ricerca con informazioni sul volume limitato:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
Ordinamento
Per impostazione predefinita, una richiesta di ricerca con volume restituisce risultati maxResults
, in cui maxResults
è il parametro utilizzato nell'impaginazione (vedi sopra), in ordine di pertinenza rispetto ai termini di ricerca.
Puoi modificare l'ordinamento impostando il parametro orderBy
su uno di questi valori:
relevance
: restituisce i risultati in ordine di pertinenza dei termini di ricerca (valore predefinito).newest
: restituisce i risultati in ordine di pubblicazione, dalla più recente alla meno recente.
L'esempio seguente elenca i risultati per data di pubblicazione, dalla più recente alla meno recente:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey
Recupero di un volume specifico
Puoi recuperare le informazioni per un volume specifico inviando una richiesta HTTP GET
all'URI della risorsa del volume:
https://www.googleapis.com/books/v1/volumes/volumeId
Sostituisci il parametro del percorso volumeId
con l'ID del volume da recuperare. Consulta la sezione ID Google Libri per ulteriori
informazioni sugli ID volume.
Richiesta
Ecco un esempio di richiesta GET
che ottiene un singolo volume:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey
Nota: il recupero delle informazioni sul volume non richiede
l'autenticazione, quindi non devi fornire l'intestazione HTTP Authorization
con la richiesta GET
. Tuttavia, se la chiamata viene effettuata con
l'autenticazione, il volume includerà informazioni specifiche dell'utente, ad esempio
lo stato acquistato.
Risposta
Se la richiesta riesce, il server risponde con il codice di stato HTTP 200 OK
e la risorsa Volume richiesta:
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" } }
Informazioni di accesso
La sezione accessInfo
è di particolare interesse nel determinare
quali funzionalità sono disponibili per un ebook. Un ebook epub
è un ebook in formato di testo scorrevole; la sezione epub
avrà una proprietà isAvailable
che indica se questo tipo di ebook è disponibile.
Avrà un link per il download se esiste un'anteprima del libro o se l'utente può leggerlo perché lo ha acquistato o perché è di dominio pubblico nella località dell'utente. Un pdf
per Google Libri indica una versione dell'ebook con pagine digitalizzate con dettagli simili, ad esempio se è disponibile e un link per il download. Google consiglia i file epub
per eReader e smartphone, in quanto le pagine scansionate potrebbero essere difficili da leggere su questi dispositivi.
Se non è presente una sezione accessInfo
, il volume non è disponibile come Google eBook.
Parametri di query facoltativi
Oltre ai parametri di query standard, puoi usare il seguente parametro di query quando recuperi un volume specifico.
Projection
Puoi utilizzare il parametro projection
con uno dei seguenti
valori per specificare un insieme predefinito di campi Volume da restituire:
full
- Restituisce tutti i campi del volume.lite
- Restituisce solo determinati campi. Consulta le descrizioni dei campi contrassegnati da doppi asterischi nel Riferimento al volume per scoprire quali campi sono inclusi.
L'esempio seguente restituisce informazioni sul volume limitato di un singolo volume:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey
Uso degli scaffali
Recupero di un elenco degli scaffali pubblici di un utente
Puoi recuperare un elenco degli scaffali pubblici di un utente inviando una richiesta HTTP GET
all'URI con il seguente formato:
https://www.googleapis.com/books/v1/users/userId/bookshelves
Sostituisci il parametro di percorso userId con l'ID dell'utente di cui vuoi recuperare gli scaffali. Consulta la sezione ID di Google Libri per ulteriori informazioni sugli ID utente.
Richiesta
Ecco un esempio:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey
Poiché non è necessario che un utente sia autenticato per recuperare informazioni relative agli
scaffali pubblici, non è necessario fornire l'intestazione HTTP Authorization
con la richiesta GET
.
Risposta
Se la richiesta riesce, il server risponde con il codice di stato HTTP 200 OK
e l'elenco di scaffali:
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" }, ... ] }
Parametri di query facoltativi
Puoi utilizzare i parametri di query standard per recuperare l'elenco degli scaffali pubblici di un utente.
Recupero di uno scaffale pubblico specifico
Puoi recuperare uno scaffale pubblico specifico inviando una richiesta HTTP GET
all'URI con il formato seguente:
https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf
Sostituisci i parametri userId e scaffale con gli ID che specificano l'utente e lo scaffale che vuoi recuperare. Consulta la sezione ID Google Libri per ulteriori informazioni.
Richiesta
Ecco un esempio:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey
Poiché non è necessario che un utente sia autenticato per recuperare informazioni relative agli
scaffali pubblici, non è necessario fornire l'intestazione HTTP Authorization
con la richiesta GET
.
Risposta
Se la richiesta riesce, il server risponde con il
codice di stato HTTP 200 OK
e la risorsa scaffale:
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" }
Parametri di query facoltativi
Puoi utilizzare i parametri di query standard quando recuperi uno specifico scaffale pubblico.
Recupero di un elenco di volumi su uno scaffale pubblico
Puoi recuperare un elenco di volumi nello scaffale pubblico di un utente inviando una richiesta HTTP GET
di un URI con il seguente formato:
https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes
Richiesta
Ecco un esempio:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey
Sostituisci i parametri userId e scaffale con gli ID che specificano l'utente e lo scaffale che vuoi recuperare. Consulta la sezione ID Google Libri per ulteriori informazioni.
Poiché non è necessario che un utente sia autenticato per recuperare informazioni relative agli
scaffali pubblici, non è necessario fornire l'intestazione HTTP Authorization
con la richiesta GET
.
Risposta
Se la richiesta ha esito positivo, il server risponde con un codice di stato HTTP 200 OK
e con l'elenco degli scaffali dell'utente:
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 }
Parametri di query facoltativi
Oltre ai parametri di query standard, puoi utilizzare il seguente parametro di query quando recuperi un elenco di volumi su uno scaffale pubblico.
Impaginazione
È possibile impaginare l'elenco dei volumi specificando due valori nei parametri per la richiesta:
startIndex
: la posizione nella raccolta da cui iniziare. L'indice del primo elemento è 0.maxResults
: il numero massimo di risultati da restituire. Il valore predefinito è 10, mentre il valore massimo consentito è 40.
Utilizzo degli scaffali in "La mia biblioteca"
Tutte le richieste della sezione "La mia raccolta" si applicano ai dati dell'utente autenticato.
Recupero di un elenco dei miei scaffali
Puoi recuperare un elenco di tutti gli scaffali dell'utente autenticato inviando una richiesta GET
HTTP all'URI con il seguente formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves
Richiesta
Ecco un esempio:
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey Authorization: /* auth token here */
Nota. Per recuperare un elenco degli scaffali della sezione "La mia biblioteca", l'utente deve essere autenticato. Devi quindi fornire l'intestazione HTTP Authorization
con la
richiesta GET
.
Risposta
Se la richiesta riesce, il server risponde con il codice di stato HTTP 200 OK
e l'elenco di tutti gli scaffali per l'utente attualmente autenticato:
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" } ] }
Parametri di query facoltativi
Puoi utilizzare i parametri di query standard per recuperare l'elenco degli scaffali degli utenti autenticati.
Recupero di un elenco di volumi nello scaffale in corso...
Puoi recuperare un elenco dei volumi nello scaffale dell'utente autenticato
inviando una richiesta HTTP GET
all'URI con il seguente formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
Sostituisci il parametro del percorso scaffale con l'ID dello scaffale. Consulta la sezione ID Google Libri per ulteriori informazioni sugli ID scaffale.
Richiesta
Ecco un esempio:
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey Authorization: /* auth token here */
Nota: per recuperare un elenco dei volumi di "La mia raccolta", l'utente deve essere autenticato. Devi quindi fornire l'intestazione HTTP Authorization
con la richiesta GET
.
Risposta
Se la richiesta ha esito positivo, il server risponde con il codice di stato HTTP 200 OK
e l'elenco di volumi scaffale:
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 }
Parametri di query facoltativi
Oltre ai parametri di query standard, puoi utilizzare il seguente parametro di query quando recuperi un elenco di volumi negli scaffali dell'utente autenticato.
Impaginazione
È possibile impaginare l'elenco dei volumi specificando due valori nei parametri per la richiesta:
startIndex
: la posizione nella raccolta da cui iniziare. L'indice del primo elemento è 0.maxResults
: il numero massimo di risultati da restituire. Il valore predefinito è 10.
Aggiunta di un volume allo scaffale
Per aggiungere un volume allo scaffale dell'utente autenticato, invia una richiesta HTTP POST
all'URI con il formato seguente:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume
Sostituisci il parametro del percorso scaffale con l'ID dello scaffale. Consulta la sezione ID Google Libri per ulteriori informazioni sugli ID scaffale.
La richiesta ha un singolo parametro di query obbligatorio:
volumeId
: l'ID del volume. Consulta la sezione ID Google Libri per ulteriori informazioni sugli ID volume.
Richiesta
Ecco un esempio per aggiungere "Fiori per Algeron" allo scaffale "Preferiti":
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
Nota: l'utente deve essere autenticato per poter apportare modifiche a uno scaffale, quindi devi fornire l'intestazione HTTP Authorization
con la richiesta POST
. Tuttavia, nessun dato è richiesto per questo POST
.
Risposta
Se la richiesta riesce, il server risponde con il codice di stato HTTP 204 No Content
.
Parametri di query facoltativi
Puoi utilizzare i parametri di query standard quando aggiungi un volume a uno degli scaffali degli utenti autenticati.
Rimuovere un volume dallo scaffale
Per rimuovere un volume dallo scaffale dell'utente autenticato, invia un POST
HTTP all'URI con il formato seguente:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume
Sostituisci il parametro del percorso scaffale con l'ID dello scaffale. Consulta la sezione ID Google Libri per ulteriori informazioni sugli ID scaffale.
La richiesta ha un singolo parametro di query obbligatorio:
volumeId
: l'ID del volume. Consulta la sezione ID di Google Libri per ulteriori informazioni sugli ID volume.
Richiesta
Ecco un esempio per rimuovere "Fiori per Algernon" dallo scaffale "Preferiti":
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
Nota: l'utente deve essere autenticato per poter apportare modifiche a uno scaffale, quindi devi fornire l'intestazione HTTP Authorization
con la richiesta POST
. Tuttavia, nessun dato è richiesto per questo POST
.
Risposta
Se la richiesta riesce, il server risponde con un codice di stato 204 No Content
.
Parametri di query facoltativi
Puoi utilizzare i parametri di query standard per rimuovere un volume da uno degli scaffali degli utenti autenticati.
Cancellazione di tutti i volumi dallo scaffale
Per rimuovere tutti i volumi dallo scaffale dell'utente autenticato, invia un
POST
HTTP all'URI con il formato seguente:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes
Sostituisci il parametro del percorso scaffale con l'ID dello scaffale. Consulta la sezione ID Google Libri per ulteriori informazioni sugli ID scaffale.
Richiesta
Ecco un esempio per cancellare lo scaffale "Preferiti":
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
Nota: l'utente deve essere autenticato per poter apportare modifiche a uno scaffale, quindi devi fornire l'intestazione HTTP Authorization
con la richiesta POST
. Tuttavia, nessun dato è richiesto per questo POST
.
Risposta
Se la richiesta riesce, il server risponde con un codice di stato 204 No Content
.
Parametri di query facoltativi
Puoi utilizzare i parametri di query standard per cancellare tutti i volumi da uno degli scaffali dell'utente autenticato.
Riferimento ai parametri di ricerca
I parametri di query che puoi utilizzare con l'API Books sono riassunti in questa sezione.Tutti i valori dei parametri devono essere codificati nell'URL.
Parametri di query standard
I parametri di query che si applicano a tutte le operazioni dell'API Books sono documentati in Parametri di sistema.
Parametri di query specifici dell'API
I parametri di richiesta che si applicano solo a operazioni specifiche nell'API Books sono riassunti nella seguente tabella.
Parametro | Significato | Note | Applicabilità |
---|---|---|---|
download |
Limita ai volumi in base alla disponibilità di download. |
|
|
filter |
Filtra i risultati di ricerca per tipo di volume e disponibilità. |
|
|
langRestrict |
Limita i volumi restituiti a quelli contrassegnati con la lingua specificata. |
|
|
maxResults |
Il numero massimo di elementi da restituire con questa richiesta. |
|
|
orderBy |
Ordine dei risultati di ricerca nel volume. |
|
|
printType |
Limita ai libri o alle riviste. |
|
|
projection |
Limita le informazioni sul volume restituite a un sottoinsieme di campi. |
|
|
q |
Stringa di query a testo intero. |
|
|
startIndex |
La posizione nella raccolta da cui iniziare l'elenco dei risultati. |
|
|
volumeId |
Identifica un volume associato alla richiesta. |
|