Utilizzo dell'API

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:

1. 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.
2. Attiva l'API Books nella console API di Google. (Se l'API non è elencata nella console API, salta questo passaggio.)
3. Quando la tua applicazione vuole accedere ai dati dell'utente, chiede a Google un particolare ambito di accesso.
4. Google mostra una schermata di consenso all'utente, chiedendo di autorizzare l'applicazione a richiedere dei dati.
5. Se l'utente approva, Google fornisce alla tua applicazione un token di accesso di breve durata.
6. L'applicazione richiede i dati utente, allegando il token di accesso alla richiesta.
7. 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:

1. Apri la pagina Credenziali nella console API.
2. 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 campo id.
• 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.
  Gli scaffali personalizzati hanno ID maggiori di 1000. Un ID scaffale è univoco per un utente, ad esempio due utenti possono avere uno scaffale con lo stesso ID che fa riferimento a scaffali diversi. Puoi utilizzare l'API per ottenere l'ID scaffale effettuando una richiesta che restituisce una risorsa BookSheet; puoi trovare l'ID scaffale nel campo 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.