Contenuti
Introduzione
Questo documento è destinato agli sviluppatori che vogliono scrivere applicazioni in grado di interagire con l'API Libri. La missione di Google Libri è digitalizzare i contenuti del libro in tutto il mondo e renderli più rilevabili sul Web. L'API Libri consente di cercare e accedere ai contenuti, nonché di creare e visualizzare la personalizzazione dei contenuti.
Se non hai familiarità con i concetti di Google Libri, leggi Come iniziare prima di iniziare la programmazione.
Autorizzazione delle richieste e identificazione della tua applicazione
Ogni richiesta che la tua applicazione invia all'API Libri deve identificarla. Esistono due modi per identificare la tua applicazione: utilizzare un token OAuth 2.0 (che autorizza anche la richiesta) e/o utilizzare la chiave API dell'applicazione. Ecco come stabilire quali di queste opzioni utilizzare:
- Se la richiesta richiede autorizzazione (ad esempio una richiesta di dati privati di un privato), l'applicazione deve fornire un token OAuth 2.0 alla richiesta. L'applicazione può anche fornire la chiave API, ma non deve necessariamente.
- Se la richiesta non richiede autorizzazione (come una richiesta di dati pubblici), l'applicazione deve fornire la chiave API, un token OAuth 2.0 o entrambi, qualunque sia l'opzione più comoda per te.
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 Accedi con Google, alcuni aspetti dell'autorizzazione vengono gestiti automaticamente.
Autorizzazione delle richieste con OAuth 2.0
Le richieste all'API Libri per i 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 Libri 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 sull'ambito OAuth 2.0 per l'API Libri:
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.
Acquisire e utilizzare una chiave API
Le richieste all'API Libri per i 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 utente privati, deve inviare un token OAuth 2.0 insieme alla richiesta. L'applicazione invia prima un ID client e, eventualmente, un client secret per ottenere un token. Puoi generare le credenziali OAuth 2.0 per applicazioni web, account di servizio o applicazioni installate.
Per scoprire di più, 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, quota e rapporti API.
L'API supporta diversi tipi di restrizioni sulle chiavi API. Se la chiave API di cui hai bisogno non esiste già, crea una chiave API 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 creato una chiave API, l'applicazione può aggiungere il parametro di ricerca key=yourAPIKey a tutti gli URL della richiesta.
La chiave API è sicura per l'incorporamento negli URL; non ha bisogno di codifica.
ID Google Libri
Devi specificare i campi degli ID con determinate chiamate di metodo API. Esistono tre tipi di ID utilizzati in Google Libri:
- ID volume: stringhe univoche fornite per ogni volume di cui Google Libri
è a conoscenza. 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 relativo campoid. - ID libreria: 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
- Lettura in corso: 3
- Letti: 4
- Esaminata: 5
- Visualizzati di recente: 6
- I miei ebook: 7
- Libri per te: 8 Se non abbiamo consigli per l'utente, questo scaffale non esiste.
id. - ID utente: valori numerici univoci assegnati a ciascun utente. Questi valori non sono necessariamente lo stesso ID utilizzato in altri servizi Google. Attualmente, l'unico modo per recuperare lo User-ID è estrarlo dal link personale in una risorsa Bookshelf recuperata con una richiesta autenticata. Gli utenti possono ottenere il proprio ID utente anche sul sito di Libri. Un utente non può ottenere lo User-ID per un altro utente tramite l'API o il sito di Libri; l'altro utente deve condividere esplicitamente tali informazioni via email, ad esempio.
ID sul sito di Google Libri
Gli ID che utilizzi con l'API Libri sono gli stessi utilizzati nel 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 libreria
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 tua 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 posizione utente
Google Libri rispetta le norme sul copyright, sul contratto e su altre limitazioni legali associate alla località dell'utente finale. Di conseguenza, alcuni utenti potrebbero non essere in grado di accedere ai contenuti dei libri di determinati paesi. Ad esempio, alcuni libri sono "visualizzabili in anteprima" solo negli Stati Uniti; abbiamo omesso i link di anteprima per gli utenti in altri paesi. Di conseguenza, i risultati dell'API sono limitati in base all'indirizzo IP del server o dell'applicazione client.
Utilizzo dei volumi
Eseguire una ricerca
Puoi eseguire una ricerca dei volumi inviando una richiesta HTTP GET 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 termini speciali che puoi specificare nei termini di ricerca per eseguire la ricerca in particolari campi, ad esempio:intitle:Restituisce i risultati in cui il testo che segue questa parola chiave si trova nel titolo.inauthor:Restituisce i risultati in cui il testo che segue questa parola chiave viene trovato nell'autore.inpublisher:restituisce i risultati in cui il testo che segue questa parola chiave si trova nell'editore.subject:Restituisce i risultati in cui il testo che segue questa parola chiave è presente nell'elenco delle categorie del volume.isbn:Restituisce i risultati in cui il testo che segue questa parola chiave è il numero ISBN.lccn:restituisce i risultati in cui il testo che segue questa parola chiave è"numero della Biblioteca del Congresso".oclc:restituisce i risultati in cui il testo che segue questa parola chiave è il numero del Centro computer online.
Risorse richieste:
Ecco un esempio di ricerca di Daniel Keyes' "Flowers for Algernon":
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 è necessario fornire l'intestazione HTTP Authorization con la richiesta GET. Tuttavia, se la chiamata viene effettuata con l'autenticazione, ogni volume includerà informazioni specifiche sull'utente, come lo stato acquistato.
Risposta
Se la richiesta riesce, il server risponde con un codice di stato HTTP 200 OK e con il risultato 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 ricerca facoltativi
Oltre ai parametri di ricerca standard, puoi utilizzare i seguenti parametri di ricerca quando esegui una ricerca sui volumi.
Formato download
Puoi utilizzare il parametro download per limitare i risultati restituiti ai volumi che hanno un formato di download disponibile pari a epub impostando il valore sul valore epub.
Il seguente esempio cerca libri con un download epub disponibile:
GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
Filtri
Puoi utilizzare il parametro filter per limitare ulteriormente i risultati restituiti impostandolo su uno dei seguenti valori:
partial: restituisce risultati in cui almeno una parte del testo è visualizzabile in anteprima.full: restituisce solo i risultati in cui tutto il testo è visibile.free-ebooks: restituisce solo risultati che sono ebook di Google senza costi.paid-ebooks: restituisce solo i risultati che sono Google eBook con un prezzo.ebooks: restituisce solo i risultati che sono ebook di Google, a pagamento o senza costi. Esempi di contenuti non ebook potrebbero essere i contenuti dell'editore, disponibili in anteprima limitata e non in vendita, o 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
Puoi impaginare l'elenco dei volumi specificando due valori nei parametri della 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 e il valore massimo consentito è 40.
Tipo di stampa
Puoi utilizzare il parametro printType per limitare i risultati restituiti a un tipo di pubblicazione o stampa specifico impostandolo su uno dei seguenti valori:
all: non prevede limitazioni per tipo di stampa (impostazione predefinita).books: restituisce solo risultati che sono libri.magazines: restituisce i risultati che sono riviste.
L'esempio seguente limita 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 Volume.lite: restituisce solo determinati campi. Per scoprire quali campi sono inclusi, consulta le descrizioni dei campi contrassegnate da due asterischi nella sezione Riferimento volume.
L'esempio seguente restituisce i risultati di ricerca con informazioni limitate sul volume:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
Ordinamento
Per impostazione predefinita, una richiesta di ricerca dei volumi restituisce maxResults risultati,
dove maxResults è il parametro utilizzato nell'impaginazione (sopra),
ordinato per pertinenza in base ai termini di ricerca.
Puoi modificare l'ordinamento impostando il parametro orderBy su uno dei seguenti valori:
relevance: restituisce i risultati in ordine di pertinenza dei termini di ricerca (impostazione predefinita).newest: restituisce i risultati in ordine decrescente.
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 relative a un volume specifico inviando una richiesta HTTP
GET all'URI della risorsa 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.
Risorse richieste:
Di seguito è riportato un esempio di richiesta GET che riceve 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 autenticazione, il volume includerà informazioni specifiche sull'utente, come lo stato acquistato.
Risposta
Se la richiesta ha esito positivo, il server risponde con il codice di stato HTTP 200 OK e con 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 per determinare
quali funzionalità sono disponibili per un ebook. Un epub è un ebook in formato di testo adattabile, la sezione epub avrà una proprietà isAvailable che indica se questo tipo di ebook è disponibile.
Verrà visualizzato un link di download se è presente un'anteprima del libro o se l'utente può leggere il libro perché è stato acquistato o perché è di dominio pubblico nella località dell'utente. Un pdf per Google Libri indica una versione delle pagine scansionate dell'ebook con dettagli simili, ad esempio se è disponibile e un link di download. Google consiglia file epub per eReader e smartphone, poiché le pagine digitalizzate potrebbero essere difficili da leggere su questi dispositivi.
Se non è presente una sezione accessInfo, il volume non è disponibile come
ebook Google.
Parametri di ricerca facoltativi
Oltre ai parametri di ricerca standard, puoi utilizzare 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 Volume.lite: restituisce solo determinati campi. Per scoprire quali campi sono inclusi, consulta le descrizioni dei campi contrassegnate da due asterischi nella sezione Riferimento volume.
L'esempio seguente restituisce informazioni sul volume limitato per un singolo volume:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey
Lavorare con gli 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 del percorso userId con l'ID dell'utente di cui vuoi recuperare gli scaffali. Consulta la sezione ID Google Libri per ulteriori informazioni sugli ID utente.
Risorse richieste:
Ecco un esempio:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey
Poiché un utente non deve essere autenticato per recuperare le informazioni sugli scaffali pubblici, non devi fornire l'intestazione HTTP Authorization con la richiesta GET.
Risposta
Se la richiesta va a buon fine, il server risponde con il codice di stato HTTP 200 OK e con l'elenco degli 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 ricerca facoltativi
Puoi utilizzare i parametri di query standard quando recuperi l'elenco delle librerie pubbliche di un utente.
Recupero di uno scaffale pubblico specifico
Puoi recuperare uno scaffale pubblico specifico inviando una richiesta HTTP
GET all'URI con il seguente formato:
https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf
Sostituisci i parametri del percorso userId e shelf con gli ID che specificano l'utente e lo scaffale che vuoi recuperare. Per ulteriori informazioni, consulta la sezione ID Google Libri.
Risorse richieste:
Ecco un esempio:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey
Poiché un utente non deve essere autenticato per recuperare le informazioni sugli scaffali pubblici, non devi 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 con la risorsa libreria:
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 ricerca facoltativi
Puoi usare i parametri di ricerca standard quando recupera uno scaffale pubblico specifico.
Recupero di un elenco di volumi su uno scaffale pubblico
Puoi recuperare un elenco di volumi nella libreria pubblica di un utente inviando una richiesta HTTP
GET all'URI con il seguente formato:
https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes
Risorse richieste:
Ecco un esempio:
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey
Sostituisci i parametri del percorso userId e shelf con gli ID che specificano l'utente e lo scaffale che vuoi recuperare. Per ulteriori informazioni, consulta la sezione ID Google Libri.
Poiché un utente non deve essere autenticato per recuperare le informazioni sugli scaffali pubblici, non devi 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 nell'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 ricerca facoltativi
Oltre ai parametri di ricerca standard, puoi utilizzare il seguente parametro di ricerca quando recuperi un elenco di volumi su uno scaffale pubblico.
Impaginazione
Puoi impaginare l'elenco dei volumi specificando due valori nei parametri della 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 e il valore massimo consentito è 40.
Lavorare con gli scaffali in "La mia biblioteca".
Tutte le "Le mie raccolte" si applicano ai dati dell’utente autenticato.
Recupero di un elenco dei miei scaffali
Puoi recuperare un elenco di tutti gli scaffali degli utenti autenticati inviando una richiesta HTTP GET all'URI con il seguente formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves
Risorse richieste:
Ecco un esempio:
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey Authorization: /* auth token here */
Nota: l'utente deve essere autenticato per recuperare una scheda della libreria "La mia biblioteca". 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 con l'elenco di tutti gli scaffali per l'utente autenticato corrente:
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 ricerca facoltativi
Puoi utilizzare i parametri di query standard durante il recupero dell'elenco degli scaffali degli utenti autenticati.
Recupero di un elenco di volumi nel mio scaffale
Puoi recuperare un elenco dei volumi nella libreria 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 shelf con l'ID dello scaffale. Per ulteriori informazioni sugli ID libreria, consulta la sezione ID Google Libri.
Risorse richieste:
Ecco un esempio:
GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey Authorization: /* auth token here */
Nota: l'utente deve essere autenticato per recuperare un elenco di volumi della funzionalità "La mia raccolta". 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 con l'elenco dei volumi degli scaffali:
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 ricerca facoltativi
Oltre ai parametri di query standard, puoi utilizzare il seguente parametro di ricerca quando recuperi un elenco di volumi in una libreria degli utenti autenticati.
Impaginazione
Puoi impaginare l'elenco dei volumi specificando due valori nei parametri della 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.
Aggiungere un volume allo scaffale
Per aggiungere un volume allo scaffale dell'utente autenticato, invia una richiesta HTTP POST all'URI con il seguente formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume
Sostituisci il parametro del percorso shelf con l'ID dello scaffale. Per ulteriori informazioni sugli ID libreria, consulta la sezione ID Google Libri.
La richiesta ha un singolo parametro di ricerca obbligatorio:
volumeId: l'ID del volume. Consulta la sezione ID Google Libri per ulteriori informazioni sugli ID volume.
Risorse richieste:
Ecco un esempio per aggiungere "Fiori per Algernon"; 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 apportare modifiche a uno scaffale, quindi devi fornire l'intestazione HTTP Authorization con la richiesta POST. Tuttavia, non sono richiesti dati con questo
POST.
Risposta
Se la richiesta ha esito positivo, il server risponde con il codice di stato HTTP 204 No Content.
Parametri di ricerca facoltativi
Puoi utilizzare i parametri di ricerca standard quando aggiungi un volume a una delle librerie autenticate degli utenti.
Rimuovere un volume dal mio scaffale
Per rimuovere un volume dallo scaffale dell'utente autenticato, invia un POST HTTP all'URI con il seguente formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume
Sostituisci il parametro del percorso shelf con l'ID dello scaffale. Per ulteriori informazioni sugli ID libreria, consulta la sezione ID Google Libri.
La richiesta ha un singolo parametro di ricerca obbligatorio:
volumeId: l'ID del volume. Consulta la sezione ID Google Libri per ulteriori informazioni sugli ID volume.
Risorse richieste:
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 apportare modifiche a uno scaffale, quindi devi fornire l'intestazione HTTP Authorization con la richiesta POST. Tuttavia, non sono richiesti dati con questo
POST.
Risposta
Se la richiesta ha esito positivo, il server risponde con un codice di stato 204 No Content.
Parametri di ricerca facoltativi
Puoi utilizzare i parametri di query standard quando rimuovi un volume da una delle librerie autenticate degli utenti.
Cancellazione di tutti i volumi dal mio scaffale
Per rimuovere tutti i volumi dallo scaffale dell'utente autenticato, invia un POST HTTP all'URI con il seguente formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes
Sostituisci il parametro del percorso shelf con l'ID dello scaffale. Per ulteriori informazioni sugli ID libreria, consulta la sezione ID Google Libri.
Risorse richieste:
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 apportare modifiche a uno scaffale, quindi devi fornire l'intestazione HTTP Authorization con la richiesta POST. Tuttavia, non sono richiesti dati con questo
POST.
Risposta
Se la richiesta ha esito positivo, il server risponde con un codice di stato 204 No Content.
Parametri di ricerca facoltativi
Puoi utilizzare i parametri di query standard per cancellare tutti i volumi da una delle librerie autenticate degli utenti.
Riferimento per i parametri di ricerca
I parametri di ricerca che puoi utilizzare con l'API Libri sono riassunti in questa sezione.Tutti i valori dei parametri devono essere codificati nell'URL.
Parametri di query standard
I parametri di ricerca che si applicano a tutte le operazioni dell'API Libri sono documentati in Parametri di sistema.
Parametri di ricerca API specifici
I parametri di richiesta che si applicano solo a operazioni specifiche nell'API Libri sono riassunti nella tabella seguente.
| Parametro | Significato | Note | Applicabilità |
|---|---|---|---|
download |
Limita ai volumi in base alla disponibilità di download. |
|
|
filter |
Filtra i risultati di ricerca per tipo e volume. |
|
|
langRestrict |
Consente di limitare i volumi restituiti a quelli taggati con la lingua specificata. |
|
|
maxResults |
Il numero massimo di elementi da restituire con questa richiesta. |
|
|
orderBy |
Ordine dei risultati di ricerca del volume. |
|
|
printType |
Limita a libri o 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 in cui iniziare l'elenco dei risultati. |
|
|
volumeId |
Identifica un volume associato alla richiesta. |
|