Questa pagina è stata tradotta dall'API Cloud Translation.

Per iniziare

Questo documento descrive nel dettaglio le conoscenze necessarie per utilizzare l'API Google Libri.

Introduzione
Prima di iniziare
Background API Libri
Stile di chiamata
1. RIPOSO
Formato dei dati
1. JSON

Introduzione

Questo documento è destinato agli sviluppatori che desiderano scrivere applicazioni che possano interagire con l'API Google Libri. Google Libri ha un'idea di digitalizzare i libri di tutto il mondo. Puoi utilizzare l'API Google Libri per cercare i contenuti, organizzare la biblioteca personale di un utente autenticato e modificarla.

Prima di iniziare

Crea un Account Google

Devi avere un Account Google a scopo di test. Se hai già un account di prova, il gioco è fatto. Puoi visitare l'interfaccia utente di Google Libri per configurare, modificare o visualizzare i dati del test.

Acquisisci familiarità con Libri

Se non conosci i concetti di Google Libri, prima di iniziare la programmazione dovresti leggere questo documento e sperimentare l'interfaccia utente. Questo documento presuppone che tu conosca i concetti di programmazione del Web e i formati dei dati web.

Scopri di più sull'autorizzazione delle richieste e sull'identificazione della 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 previste nella sezione "La mia raccolta" 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, questa 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, vedi Autorizzazione di richieste e identificazione dell'applicazione nel documento Utilizzo del API.

Sfondo dell'API Libri

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 nell'API Libri. Tutte le altre risorse in questa API contengono o annotano un volume.
Libreria: una libreria è una raccolta di volumi. Google Libri fornisce una serie 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 combinati. Gli utenti possono creare, modificare o eliminare altri scaffali, che vengono sempre riempiti manualmente con volumi. Gli scaffali possono essere resi privati o pubblici dall'utente.
Nota: attualmente, la creazione e l'eliminazione di scaffali di libri e la modifica delle relative impostazioni della privacy possono essere effettuate esclusivamente tramite il sito Google Libri.
Recensione: una 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 in modo appropriato.
Posizione di lettura: una posizione di lettura indica l'ultima posizione di lettura di un volume in un utente. Un utente può avere una sola posizione di lettura per volume. Se l'utente non ha mai aperto questo volume, la posizione di lettura non esiste. La posizione di lettura può memorizzare informazioni dettagliate sulla posizione fino alla risoluzione di una parola. Queste informazioni sono sempre private.

Modello di dati dell'API Libri

Una risorsa è una singola entità dati con un identificatore univoco. L'API Books utilizza due tipi di risorse, in base ai concetti descritti sopra:

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

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

Raccolta dei volumi: La raccolta dei volumi è una raccolta di ogni risorsa del volume gestita da Google Libri. Pertanto, 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 librerie: Una raccolta dello scaffale è composta da tutte le risorse dello scaffale gestite da Google Libri. Gli scaffali devono sempre essere indicati nel contesto della biblioteca di un utente specifico. Gli scaffali possono contenere zero o più volumi.

Operazioni dell'API Libri

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

Operazione	Descrizione	Mappature HTTP REST
list	Elenca un sottoinsieme di risorse specificato all'interno di una raccolta.	`GET` su un URI della raccolta.
inserire	Inserisce una nuova risorsa in una raccolta (creando una nuova risorsa).	`POST` su un URI della raccolta, in cui trasmetti i dati di una nuova risorsa.
ricevi	Riceve una risorsa specifica.	`GET` sull'URI della risorsa.
Aggiorna	Aggiorna una risorsa specifica.	`PUT` sull'URI della risorsa, in cui trasmetti i dati per la risorsa aggiornata.
elimina	Elimina una risorsa specifica.	`DELETE` sull'URI della risorsa, in cui trasmetti i dati della risorsa da eliminare.

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

Tipo di risorsa	Operazioni supportate
	elenco	inserisci	scarica	aggiorna	elimina
Volumi	Sì*		sì
Scaffali	Sì*	sì, AUTENTICA	Sì*	sì, AUTENTICA	sì, AUTENTICA
Posizione di lettura		sì, AUTENTICA	sì, AUTENTICA	sì, AUTENTICA	sì, AUTENTICA

*Sono disponibili entrambe le versioni AUTHENTICATED e non autenticate di queste operazioni, in cui le richieste autenticate vengono eseguite sui dati "La mia raccolta" privati dell'utente, mentre le richieste non autenticate funzionano solo sui dati pubblici.

Stili di chiamata

Esistono diversi modi per richiamare l'API:

Utilizzo diretto di REST
Utilizzo di REST da JavaScript (non è richiesto 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 univoco a livello globale nel 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.

Potresti trovare utili le definizioni dei metodi nella documentazione degli standard HTTP 1.1, in cui sono incluse le specifiche per GET, POST, PUT e DELETE.

REST nell'API Books

Le operazioni di Libri supportate vengono mappate direttamente ai verbi HTTP REST, come descritto nelle operazioni dell'API Books.

Il formato specifico per gli URI dell'API Libri sono:

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

dove resourceID è l'identificatore di una risorsa relativa a volume o scaffali e parameters sono parametri da applicare alla query. Per ulteriori dettagli, consulta la sezione Riferimento per i parametri di ricerca.

Il formato delle estensioni del percorso resourceID consente di identificare la risorsa in uso, 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 è riepilogato nel documento Books API Reference.

Di seguito sono riportati alcuni esempi di come funziona questa operazione nell'API Libri.

Effettua una ricerca per trapuntatura:

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

Scopri di più 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 ricerca callback e una funzione di callback. Ciò consente di scrivere applicazioni avanzate che mostrano dati dei libri senza scrivere alcun codice lato server.

Nota: puoi chiamare i metodi autenticati passando un token OAuth 2.0 utilizzando 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 le credenziali OAuth 2.0 durante l'acquisizione del token.

L'esempio seguente utilizza questo approccio per mostrare i risultati di ricerca per "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 dati comune indipendente dal linguaggio che fornisce una semplice rappresentazione testuale delle strutture dati arbitrarie. Per ulteriori informazioni, visita il sito json.org.