Utilizzo dell'API

Sommario

Introduzione

Questo documento è rivolto agli sviluppatori che vogliono scrivere applicazioni che possono interagire con l'API di Google Libri. La missione di Google Libri è digitalizzare i contenuti dei libri di tutto il mondo e renderli più rilevabili sul web. L'API Libri è un modo per cercare e accedere a questi contenuti, nonché per creare e visualizzare la personalizzazione in base a questi contenuti.

Se non hai familiarità con i concetti di Google Libri, ti consigliamo di leggere Guida introduttiva prima di iniziare a scrivere codice.

Autorizzazione delle richieste e identificazione dell'applicazione

Ogni richiesta che la tua applicazione invia all'API Books deve identificare la tua applicazione per Google. Esistono due modi per identificare l'applicazione: utilizzando un token OAuth 2.0 (che autorizza anche la richiesta) e/o utilizzando la chiave API dell'applicazione. Ecco come determinare quale di queste opzioni utilizzare:

• Se la richiesta richiede l'autorizzazione (ad esempio una richiesta di dati privati di un privato), l'applicazione deve fornire un token OAuth 2.0 con la richiesta. L'applicazione può anche 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 o un token OAuth 2.0 oppure entrambe, a seconda dell'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 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 Libri 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 del protocollo 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 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:

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 la tua applicazione richiede dati utente privati, deve inviare un token OAuth 2.0 insieme alla richiesta. La tua applicazione invia innanzitutto un ID client e, eventualmente, 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 di 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 all'API, quota e report.

     L'API supporta diversi tipi di restrizioni per le chiavi API. Se la chiave API di cui hai bisogno non esiste già, creala 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.

Una volta ottenuta una chiave API, la tua applicazione può aggiungere il parametro di querykey=yourAPIKey a tutti gli URL di richiesta.

La chiave API è sicura per l'inserimento negli URL e non richiede alcuna codifica.

ID di Google Libri

Devi specificare i campi ID con determinate chiamate ai metodi dell'API. In Google Libri vengono utilizzati tre tipi di ID:

• ID volume: stringhe univoche assegnate a ogni volume conosciuto da Google Libri. Un esempio di ID volume è _LettPDhwR0C. Puoi utilizzare l'API per recuperare l'ID volume inviando una richiesta che restituisce una risorsa Volume. Puoi trovare l'ID volume nel relativo campo id.
• ID sezioni: valori numerici assegnati a una sezione nella biblioteca di un utente. Google fornisce alcune sezioni predefinite per ogni utente con i seguenti ID:
  • Preferiti: 0
  • Acquistato: 1
  • Da leggere: 2
  • In lettura: 3
  • Letti: 4
  • Data esame: 5
  • Visualizzati di recente: 6
  • I miei eBook: 7
  • Libri per te: 8 Se non abbiamo consigli per l'utente, questa sezione non esiste.
  Le sezioni personalizzate hanno ID superiori a 1000. L'ID libreria è univoco per un determinato utente, ovvero due utenti possono avere una libreria con lo stesso ID che rimanda a librerie diverse. Puoi utilizzare l'API per recuperare l'ID libreria inviando una richiesta che restituisce una risorsa libreria. Puoi trovare l'ID libreria nel relativo campo id.
• ID utente: valori numerici univoci assegnati a ogni utente. Questi valori non sono necessariamente gli stessi valori ID utilizzati in altri servizi Google. Al momento, l'unico modo per recuperare l'ID utente è estrarlo dal valore selfLink di una risorsa Raccolta recuperata con una richiesta autenticata. Gli utenti possono anche ottenere il proprio ID utente dal sito di Libri. Un utente non può ottenere l'ID utente di un altro utente tramite l'API o il sito di Libri; l'altro utente deve condividere queste informazioni esplicitamente, 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 libreria
  

  Quando visualizzi una determinata sezione sul sito, puoi trovare l'ID della sezione 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 l'ID utente nel parametro URL uid. Ecco un esempio:

  https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list

Impostazione della posizione dell'utente

Google Libri rispetta il copyright, i contratti e altre limitazioni 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 possono essere "visualizzati in anteprima" solo negli Stati Uniti. Pertanto, ometteremo questi link di anteprima per gli utenti di altri paesi. Pertanto, 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 solo 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 campi particolari, ad esempio:
  • intitle: Restituisce i risultati in cui il testo che segue questa parola chiave è presente 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 viene trovato nel publisher.
  • subject: Restituisce i risultati in cui il testo che segue questa parola chiave è elencato 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 è il numero di controllo della Biblioteca del Congresso.
  • oclc: Restituisce i risultati in cui il testo che segue questa keyword è il numero dell'Online Computer Library Center.

Richiesta

Ecco un esempio di ricerca del libro "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, pertanto non devi fornire l'intestazione HTTP Authorization con la richiesta GET. Tuttavia, se la chiamata viene effettuata con autenticazione, ogni volume includerà informazioni specifiche per l'utente, ad esempio lo stato di 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 per eseguire una ricerca nei volumi.

Formato di download

Utilizza il parametro download per limitare i risultati restituiti ai volumi con un formato di download disponibile di epub impostando sul valore epub.

Il seguente esempio cerca i libri con un download in formato 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 i risultati in cui almeno alcune parti del testo sono visualizzabili in anteprima.
• full: restituisce solo i risultati in cui tutto il testo è visibile.
• free-ebooks: restituisce solo risultati che sono eBook Google senza costi.
• paid-ebooks: restituisce solo risultati che sono eBook Google con un prezzo.
• ebooks: restituisce solo risultati che sono eBook Google, a pagamento o senza costi. Alcuni esempi di contenuti non in formato eBook sono i contenuti dei publisher disponibili in anteprima limitata e non in vendita o le riviste.

Il seguente esempio 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 paginare 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 vengono applicati limiti in base al tipo di stampa (impostazione predefinita).
• books: restituisce solo risultati che sono libri.
• magazines: restituisce risultati che sono riviste.

Il seguente esempio 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. Consulta le descrizioni dei campi contrassegnate da due asterischi nel Riferimento del volume per scoprire quali campi sono inclusi.

L'esempio seguente restituisce risultati di ricerca con informazioni sul volume limitate:

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), ordinati in base alla pertinenza 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 (impostazione predefinita).
• newest: restituisce i risultati in ordine dalla pubblicazione più recente a quella meno recente.

L'esempio seguente elenca i risultati in base alla 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 HTTPGET 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. Per ulteriori informazioni sugli ID volume, consulta la sezione ID di Google Libri.

Richiesta

Ecco un esempio di richiesta GET che restituisce 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, pertanto non devi fornire l'intestazione HTTP Authorization con la richiesta GET. Tuttavia, se la chiamata viene effettuata con autenticazione, il volume includerà informazioni specifiche dell'utente, come lo stato di acquisto.

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 per determinare le funzionalità disponibili per un eBook. Un epub è un ebook in formato testo scorrevole. La sezione epub avrà una proprietà isAvailable che indica se questo tipo di ebook è disponibile. Sarà presente un link per il download se è disponibile un sample del libro o se l'utente può leggere il libro perché lo ha acquistato o perché è di dominio pubblico nella località in cui si trova. Un pdf per Google Libri indica una versione delle pagine scansionate dell'ebook 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 la sezione accessInfo, il volume non è disponibile come ebook Google.

Parametri di query facoltativi

Oltre ai parametri di query standard, puoi utilizzare il seguente parametro di query per recuperare 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. Consulta le descrizioni dei campi contrassegnate da due asterischi nel Riferimento del volume per scoprire quali campi sono inclusi.

L'esempio seguente restituisce informazioni limitate sul volume per un singolo volume:

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey

Utilizzare le sezioni

Recupero di un elenco delle sezioni pubbliche di un utente

Puoi recuperare un elenco delle sezioni pubbliche di un utente inviando una richiesta HTTPGET 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 le sezioni. Per ulteriori informazioni sugli ID utente, consulta la sezione ID Google Libri.

Richiesta

Ecco un esempio:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey

Poiché un utente non deve essere autenticato per recuperare informazioni sulle sezioni di libri pubbliche, non devi 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 delle sezioni:

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 delle sezioni pubbliche di un utente.

Recupero di una libreria pubblica specifica

Puoi recuperare una libreria pubblica specifica inviando una richiesta HTTPGET all'URI con il seguente formato:

https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf

Sostituisci i parametri di percorso userId e shelf con gli ID che specificano l'utente e la sezione che vuoi recuperare. Per ulteriori informazioni, consulta la sezione ID di Google Libri.

Richiesta

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 informazioni sulle sezioni di libri pubbliche, non devi 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 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 query facoltativi

Puoi utilizzare i parametri di query standard per recuperare una libreria pubblica specifica.

Recupero di un elenco di volumi su una libreria pubblica

Puoi recuperare un elenco di volumi nella libreria pubblica di un utente inviando una richiesta HTTPGET a 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 di percorso userId e shelf con gli ID che specificano l'utente e la sezione che vuoi recuperare. Per ulteriori informazioni, consulta la sezione ID di Google Libri.

Poiché un utente non deve essere autenticato per recuperare informazioni sulle sezioni di libri pubbliche, non devi fornire l'intestazione HTTP Authorization con la richiesta GET.

Risposta

Se la richiesta riesce, il server risponde con un codice di stato HTTP 200 OK e l'elenco delle sezioni 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 per recuperare un elenco di volumi in una libreria pubblica.

Impaginazione

Puoi paginare 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.

Utilizzare le sezioni "Raccolta"

Tutte le richieste "La mia raccolta" si applicano ai dati dell'utente autenticato.

Recupero di un elenco delle mie sezioni

Puoi recuperare un elenco di tutte le sezioni di libri dell'utente autenticato inviando una richiesta HTTP GET 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: l'utente deve essere autenticato per recuperare un elenco delle sezioni "La mia raccolta". Pertanto, devi 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 tutte le sezioni 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 delle sezioni dell'utente autenticato.

Recupero di un elenco di volumi nella mia libreria

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 di percorso shelf con l'ID della libreria. Per ulteriori informazioni sugli ID libreria, consulta la sezione ID Google Libri.

Richiesta

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 dei volumi della "Mia raccolta". Pertanto, devi fornire l'intestazione HTTP Authorization insieme alla richiesta GET.

Risposta

Se la richiesta riesce, il server risponde con il codice di stato HTTP 200 OK e l'elenco dei volumi della sezione Letture:

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 per recuperare un elenco di volumi in una delle librerie dell'utente autenticato.

Impaginazione

Puoi paginare 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 alla mia raccolta

Per aggiungere un volume alla libreria dell'utente autenticato, invia una richiesta HTTPPOST all'URI con il seguente formato:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume

Sostituisci il parametro di percorso shelf con l'ID della libreria. Per ulteriori informazioni sugli ID libreria, consulta la sezione ID Google Libri.

La richiesta ha un unico parametro di query obbligatorio:

• volumeId: l'ID del volume. Per ulteriori informazioni sugli ID volume, consulta la sezione ID di Google Libri.

Richiesta

Ecco un esempio per aggiungere "Fiori per Algernon" alla sezione "Preferiti" della libreria:

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 una libreria, quindi devi fornire l'intestazione HTTP Authorization con la richiesta POST. Tuttavia, non sono richiesti dati 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 per aggiungere un volume a una delle librerie dell'utente autenticato.

Rimuovere un volume dalla mia libreria

Per rimuovere un volume dalla libreria dell'utente autenticato, invia un messaggio HTTPPOST all'URI con il seguente formato:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume

Sostituisci il parametro di percorso shelf con l'ID della libreria. Per ulteriori informazioni sugli ID libreria, consulta la sezione ID Google Libri.

La richiesta ha un unico parametro di query obbligatorio:

• volumeId: l'ID del volume. Per ulteriori informazioni sugli ID volume, consulta la sezione ID di Google Libri.

Richiesta

Ecco un esempio per rimuovere "Fiori per Algernon" dalla libreria "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 una libreria, quindi devi fornire l'intestazione HTTP Authorization con la richiesta POST. Tuttavia, non sono richiesti dati 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 una delle librerie dell'utente autenticato.

Cancellare tutti i volumi dalla mia libreria

Per rimuovere tutti i volumi dalla libreria 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 di percorso shelf con l'ID della libreria. Per ulteriori informazioni sugli ID libreria, consulta la sezione ID Google Libri.

Richiesta

Ecco un esempio per svuotare la sezione "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 una libreria, quindi devi fornire l'intestazione HTTP Authorization con la richiesta POST. Tuttavia, non sono richiesti dati 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 una delle librerie dell'utente autenticato.

Riferimento parametro di query

I parametri di query che puoi utilizzare con l'API Books sono riportati 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 descritti 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 riportati nella tabella seguente.