Questa pagina è stata tradotta dall'API Cloud Translation.

Per iniziare

In questo documento vengono descritte le conoscenze di base necessarie per utilizzare l'API Google Libri.

Introduzione
Prima di iniziare
Background dell'API Books
Stile di chiamata
1. RESTO
Formato dei dati
1. JSON

Introduzione

Questo documento è rivolto agli sviluppatori che desiderano scrivere applicazioni in grado di interagire con l'API Google Books. Google Libri ha in mente di digitalizzare i libri di tutto il mondo. Puoi utilizzare l'API Google Libri per cercare contenuti, organizzare la raccolta personale di un utente autenticato e modificarla.

Prima di iniziare

Ottieni un Account Google

Per i test è necessario un Account Google. Se hai già un account di prova, non devi fare altro. Puoi visitare l'interfaccia utente di Google Libri per impostare, modificare o visualizzare i tuoi dati di test.

Familiarizza con Libri

Se non hai dimestichezza con i concetti di Google Libri, leggi questo documento e prova l'interfaccia utente prima di iniziare a programmare. In questo documento si presuppone che tu abbia familiarità con i concetti di programmazione web e i formati di dati web.

Scopri di più su come autorizzare le richieste e identificare la tua applicazione

Quando la tua applicazione richiede dati privati, la richiesta deve essere autorizzata da un utente autenticato che ha accesso a tali dati.

In particolare, tutte le operazioni nella sezione "La mia biblioteca" dell'API Google Libri sono considerate private e richiedono autenticazione e autorizzazione. Inoltre, qualsiasi operazione che modifichi i dati di Google Libri può essere eseguita solo dall'utente proprietario di tali dati.

Quando la tua applicazione richiede dati pubblici, la richiesta non deve essere autorizzata, ma deve essere accompagnata da un identificatore, ad esempio una chiave API.

Per informazioni su come autorizzare le richieste e utilizzare le chiavi API, consulta Autorizzazione delle richieste e identificazione dell'applicazione nel documento Utilizzo dell'API.

Background dell'API Books

Concetti sui libri

Google Libri si basa su quattro concetti di base:

Volume: un volume rappresenta i dati ospitati da Google Libri su un libro o una rivista. È la risorsa principale dell'API Books. Tutte le altre risorse in questa API contengono o annotano un volume.
Bookshelf: uno scaffale è un insieme di volumi. Google Libri fornisce un insieme di scaffali predefiniti per ogni utente, alcuni dei quali sono completamente gestiti dall'utente, alcuni vengono compilati automaticamente in base all'attività dell'utente e altri vengono misti. Gli utenti possono creare, modificare o eliminare altri scaffali, che sono sempre riempiti di volumi manualmente. Gli scaffali possono essere resi privati o pubblici dall'utente.
Nota. Al momento, la creazione e l'eliminazione degli scaffali e la modifica delle impostazioni di privacy sugli scaffali sono possibili solo tramite il sito Google Libri.
Recensione: la recensione di un volume è una combinazione di valutazione a stelle e/o testo. Un utente può inviare una recensione per volume. Le recensioni sono disponibili anche da fonti esterne e vengono attribuite correttamente.
Posizione di lettura: una posizione di lettura indica l'ultima posizione di lettura in un volume per un utente. Un utente può avere una sola posizione di lettura per volume. Se l'utente non ha mai aperto quel volume in precedenza, il punto di lettura non esiste. Il punto di lettura può memorizzare informazioni dettagliate sulla posizione fino alla risoluzione di una parola. Queste informazioni sono sempre private per l'utente.

Modello dei dati dell'API Books

Una risorsa è una singola entità di dati con un identificatore univoco. L'API Libri utilizza due tipi di risorse, basati sui concetti descritti sopra:

Risorsa di volume: rappresenta un volume.
Risorsa scaffale: rappresenta un singolo scaffale per un determinato utente.

Il modello dei dati dell'API Books si basa su gruppi di risorse, denominati raccolte:

Raccolta di volumi: La raccolta di volumi è una raccolta di ogni risorsa di volume gestita da Google Libri. Di conseguenza, non puoi elencare tutte le risorse di volume, ma puoi elencare tutti i volumi che corrispondono a un insieme di termini di ricerca.
Raccolta di scaffali: Una raccolta di scaffali è composta da tutte le risorse per scaffali gestite da Google Libri. È necessario fare sempre riferimento agli scaffali nel contesto della biblioteca di un utente specifico. Gli scaffali possono contenere zero o più volumi.

Operazioni dell'API Books

Puoi richiamare cinque metodi diversi su raccolte e risorse nell'API Books, come descritto nella tabella seguente.

Operazione	Descrizione	Mappature REST HTTP
list	Elenca un sottoinsieme specificato di risorse all'interno di una raccolta.	`GET` su un URI della raccolta.
inserisci	Inserisce una nuova risorsa in una raccolta (creando una nuova risorsa).	`POST` su un URI della raccolta, in cui trasmetti i dati per una nuova risorsa.
trova	Recupera una risorsa specifica.	`GET` sull'URI della risorsa.
aggiorna	Aggiorna una risorsa specifica.	`PUT` sull'URI della risorsa, dove passi i dati per la risorsa aggiornata.
elimina	Elimina una risorsa specifica.	`DELETE` sull'URI della risorsa, in cui passi i dati per l'eliminazione della risorsa.

Le operazioni supportate per i vari tipi di risorse sono riassunte nella tabella seguente. Le operazioni che si applicano ai dati privati di un utente sono chiamate operazioni "La mia raccolta " e richiedono tutte l'autenticazione.

Tipo di risorsa	Operazioni supportate
	elenco	inserisci	get	aggiorna	elimina
Volumi	sì*		sì
Librerie	sì*	sì, AUTHENTICATED	sì*	sì, AUTHENTICATED	sì, AUTHENTICATED
Posizioni di lettura		sì, AUTHENTICATED	sì, AUTHENTICATED	sì, AUTHENTICATED	sì, AUTHENTICATED

*Sono disponibili entrambe le versioni AUTHENTICATED e non autenticate di queste operazioni, in cui le richieste autenticate operano sui dati privati dell'utente nella sezione La mia raccolta e le richieste non autenticate operano solo sui dati pubblici.

Stili di chiamata

Esistono diversi modi per richiamare l'API:

Usare direttamente REST
Utilizzo di REST da JavaScript (non è necessario codice lato server).

REST

REST è un tipo di architettura software che fornisce un approccio pratico e coerente per la richiesta e la modifica dei dati.

Il termine REST è l'acronimo di "REpresentational State Transfer". Nel contesto delle API di Google, si riferisce all'utilizzo dei verbi HTTP per recuperare e modificare le rappresentazioni dei dati archiviati da Google.

In un sistema RESTful, le risorse vengono archiviate in un datastore. Un client invia una richiesta affinché il server esegua una determinata azione (ad esempio la creazione, il recupero, l'aggiornamento o l'eliminazione di una risorsa) e il server esegue l'azione e invia una risposta, spesso sotto forma di rappresentazione della risorsa specificata.

Nelle API RESTful di Google, il client specifica un'azione utilizzando un verbo HTTP come POST, GET, PUT o DELETE. Specifica una risorsa mediante un URI globale univoco con il seguente formato:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Poiché tutte le risorse dell'API dispongono di URI univoci accessibili tramite HTTP, REST consente la memorizzazione dei dati nella cache ed è ottimizzato per operare con l'infrastruttura distribuita del Web.

Potrebbero esserti utili le definizioni dei metodi riportate nella documentazione degli standard HTTP 1.1, in quanto includono le specifiche per GET, POST, PUT e DELETE.

REST nell'API Books

Le operazioni di Books supportate mappano direttamente ai verbi HTTP REST, come descritto in Operazioni dell'API Books.

Il formato specifico degli URI dell'API Books è il seguente:

https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters

dove resourceID è l'identificatore di una risorsa volume o scaffale e parameters sono eventuali parametri da applicare alla query. Per informazioni dettagliate, consulta Riferimento per i parametri di query.

Il formato delle estensioni di percorso resourceID consente di identificare la risorsa su cui stai attualmente operando, ad esempio:

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

Tieni presente che le operazioni con mylibrary nell'URI si applicano solo ai dati della libreria privata dell'utente attualmente autenticato. Il set completo di URI utilizzati per ogni operazione supportata nell'API è riassunto nel documento di riferimento dell'API Books.

Ecco un paio di esempi di come funziona nell'API Books.

Esegui una ricerca di trapuntatura:

GET https://www.googleapis.com/books/v1/volumes?q=quilting

Per informazioni sul volume s1gVAAAAYAAJ:

GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ

REST da JavaScript

Puoi richiamare l'API Books utilizzando REST da JavaScript (chiamato anche JSON-P), utilizzando il parametro di query callback e una funzione di callback. Ciò ti consente di scrivere applicazioni avanzate che visualizzano dati di Libri senza scrivere alcun codice lato server.

Nota: puoi chiamare metodi autenticati passando un token OAuth 2.0 tramite il parametro access_token. Per ottenere un token OAuth 2.0 da utilizzare con JavaScript, segui le istruzioni descritte in OAuth 2.0 per le applicazioni web lato client. Nella scheda "Accesso API" della console API, assicurati di impostare un ID client per le applicazioni web e di utilizzare queste credenziali OAuth 2.0 quando ricevi il token.

L'esempio seguente utilizza questo approccio per visualizzare i risultati di ricerca relativi a "harry potter":

<html>
  <head>
    <title>Books API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // in production code, item.text should have the HTML entities escaped.
        document.getElementById("content").innerHTML += "<br>" + item.volumeInfo.title;
      }
    }
    </script>
    <script src="https://www.googleapis.com/books/v1/volumes?q=harry+potter&callback=handleResponse"></script>
  </body>
</html>

Formato dei dati

JSON

JSON (JavaScript Object Notation) è un formato di dati comune, indipendente dal linguaggio, che fornisce una semplice rappresentazione testuale di strutture di dati arbitrarie. Per ulteriori informazioni, visita il sito json.org.