La funzionalità Link dinamici di Google Libri ti consente di creare link più personalizzabili e affidabili a Google Libri dal tuo sito. Ad esempio, questo strumento ti consente di generare "link intelligenti" che vengono visualizzati soltanto quando un libro è presente nel nostro indice oppure di link che mostrano agli utenti se è possibile visualizzare l'anteprima di un libro su Google Libri. La funzionalità Link dinamici ti consente anche di includere un'immagine in miniatura nel link a Google Libri. Lo scopo di questo documento è consentirti di aggiungere rapidamente questa funzionalità al tuo sito.
Nota: questa funzionalità era in precedenza nota come API Visibilità libri.
La Procedura guidata di anteprima è uno strumento basato sui link dinamici che rende ancora più facile creare link a anteprime di libri del sito semplicemente copiando alcune righe di codice. Questo documento è rivolto a sviluppatori più esperti che vogliono personalizzare il loro collegamento alla Ricerca di libri.
Contenuti
- Pubblico
- Terminologia della ricerca di libri
- Introduzione
- Linee guida per il branding
- L'API lato client
- Modalità sincrone e asincrone
- Domande frequenti
- Esempi di codice
Pubblico
La documentazione sui link dinamici è rivolta ai programmatori che vogliono scrivere applicazioni web che rimandano a libri all'interno di Google Libri. Questa documentazione presuppone che tu abbia dimestichezza con il protocollo HTTP e con il codice JavaScript di base.
Terminologia della ricerca di libri
Google Libri rispetta le limitazioni di copyright locali dell'utente e, di conseguenza, le anteprime o le visualizzazioni complete di alcuni libri non sono disponibili in tutte le località. La visibilità è raggruppata nelle seguenti classi:
- Visualizzazione completa
- L'intero libro è visibile. Questi libri potrebbero essere di dominio pubblico.
- Anteprima limitata
- Una parte del libro è visibile. Questo libro è protetto da copyright e Google Libri ha ricevuto l'autorizzazione a rendere queste pagine accessibili agli utenti. Questi libri sono diversi dai libri che visualizzano la visualizzazione Frammento in quanto gli utenti possono visualizzare intere pagine.
- Visualizzazione snippet e nessuna anteprima
- Gli utenti vedono solo una pagina"Informazioni sul libro". Sono disponibili al massimo solo brevi estratti del libro. Questo libro non è stato digitalizzato o è protetto da copyright e Google Libri non ha ricevuto l'autorizzazione a esporre più di alcuni "snippet" correlati al termine di ricerca di un utente.
Introduzione
La documentazione sui link statici descrive un modo molto semplice per generare URL per una determinata pagina di un libro su Google Libri. Purtroppo, a volte può capitare che un libro specifico non sia nell'indice di Google Libri o che l'anteprima non sia disponibile per un utente in una determinata posizione geografica. Poiché i link statici sono "ciechi" e a volte non riescono ad ottenere l'effetto previsto.
I link dinamici forniscono un metodo programmatico e lato client alternativo per eseguire query sulla visibilità di un libro utilizzando JavaScript. Ciò ti consente di includere link più affidabili e prevedibili nella Ricerca di libri, offrendo così un'esperienza più coerente ai tuoi utenti. Poiché la visibilità varia in base alla località dell'utente finale, l'interfaccia dei link dinamici non è progettata per query lato server o offline.
Per avere un'idea di cosa possono fare i link dinamici, passa agli esempi di codice alla fine di questo documento.
Linee guida per il branding
Quando esegui il rendering di Dynamic Links, devi rispettare le linee guida per il branding che regolano la famiglia di API di Google Libri. In particolare:
- Devi mantenere l'attribuzione e i link a Google Libri.
- È necessario utilizzare solo il pulsante di anteprima di Google approvato per effettuare il collegamento a anteprime su Google Libri.
- Qualsiasi link di testo, pulsante, documentazione o testo descrittivo deve rispettare le convenzione di denominazione approvate. Ad esempio, non devi utilizzare verbi "download" o "lettura".
Esempio di branding
La sezione Esempi alla fine di questo documento fornisce esempi aggiuntivi conformi alle linee guida per il branding attuali.
API lato client
Al centro del link dinamico lato client c'è un formato di URL che consente agli sviluppatori di creare URL che richiedono informazioni su uno o più libri e di inviare le richieste a Google Libri utilizzando il tag <script>.
- Esempio di sintassi:
<script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback"></script>
Formato della richiesta
Il formato dell'URL è simile alla sintassi dell'URL utilizzata per collegarsi ai libri, ma il campo ID libro può contenere più ID libro separati da virgola e contiene parametri 'jscmd' e 'callback'. Facoltativamente, possono essere presenti argomenti aggiuntivi per controllare i filtri di visibilità.
Dynamic Links supporta diversi metodi di identificazione dei libri: ISBN, numeri OCLC e chiavi LCCN. L'API consente query in batch fino alla dimensione massima di una richiesta GET.
- ISBN
&bibkeys=ISBN:0451526538(l'API supporta sia i codici ISBN 10 che 13.)- OCLC
&bibkeys=OCLC:36792831- LCCN
&bibkeys=LCCN:96072233
Formato dei risultati JSON
La risposta a questa chiamata conterrà informazioni sui libri richiesti che sono stati restituiti come uno o più oggetti JSON. Gli oggetti JSON utilizzano la seguente struttura:
JsonSearchResult {
string bib_key;
string info_url;
string preview_url;
string thumbnail_url;
string preview;
};
Questi campi forniscono le seguenti informazioni:
- bib_chiave
- L'identificatore utilizzato per eseguire query sul libro.
- url_info
- Un URL che rimanda a una pagina in Google Libri con informazioni sul libro (la pagina relativa a questa pagina).
- url_anteprima
- Un URL per visualizzare l'anteprima del libro, che porta l'utente direttamente alla copertina. Se per una richiesta sono disponibili solo libri con visualizzazione Frammento o Nessuna anteprima, non viene restituito alcun URL di anteprima.
- miniatura_url
- Un URL che rimanda a una miniatura della copertina del libro.
- anteprima
- Un valore che indica lo stato di visibilità del libro:
full(per i libri con visualizzazione completa),partial(per i libri in anteprima limitata) onoview(per i libri con snippet o Nessuna anteprima). - incorporabile
- Questo valore booleano è
truese il libro può essere incorporato in pagine di terze parti utilizzando il visualizzatore incorporato di Ricerca libri. - jscmd
- La richiesta a Google Libri.
- callback
- Nome della funzione JavaScript a cui trasmettiamo il ritorno.
- D. Ho bisogno di una chiave API o di un'altra autorizzazione per utilizzare i link dinamici?
- R: Non sono necessarie chiavi API né altre autorizzazioni per utilizzare i link dinamici. Per iniziare, copia e incolla uno dei nostri esempi e inizia a modificare.
- D. Che cosa succede con i browser che non supportano JavaScript o l'hanno disattivato?
- R: Non è possibile verificare se Google Libri ha o meno un libro quando nel browser di un utente non è attivato JavaScript. Ti consigliamo di utilizzare la struttura dei link statici di Google Libri per i browser senza JavaScript, ma tieni presente che non è possibile sapere in anticipo se Google Libri contiene il libro a cui vengono indirizzati i libri.
- D. Quanti libri posso cercare contemporaneamente?
- R. Il numero di libri che puoi cercare è limitato soltanto dalla lunghezza delle richieste GET. In Microsoft Internet Explorer, la lunghezza massima dell'URL (2083 caratteri) limita la lunghezza delle richieste GET.
- D: Google Libri ha restituito risultati per un libro poco fa. Perché non restituisce i risultati ora?
- R. Dato che gli sviluppatori emettono spesso una quantità atipica di richieste, potresti accidentalmente invertire le misure di sicurezza adottate in Google Libri. Per verificare se ciò accade, controlla cosa viene restituito dall'API. Se si tratta di una richiesta per compilare un captcha, hai inviato troppe query. Ti consigliamo di accedere a Google Libri e riprovare.
- D: E la privacy?
- R. Per quanto riguarda le query relative alla visibilità dei libri, Google riceve dati di log del server che non consentono l'identificazione personale. Prendiamo molto sul serio la privacy degli utenti e trattiamo questi dati come descritto nelle nostre norme sulla privacy. Se fornisci agli utenti un servizio che include la visibilità dei libri, puoi informare gli utenti che il servizio invia anche query a Google tramite link dinamici.
- Pulsante di anteprima per una pagina del libro
Se intendi utilizzare i link dinamici per aggiungere pulsanti di anteprima a singole pagine del libro sul tuo sito, questo è l'esempio che fa per te. Questa implementazione utilizza una chiamata sincrona a Google Libri. - Elenco di lettura dei corsi
Questo esempio mostra un tipico elenco di libri per un corso accademico. Utilizziamo una singola chiamata sincrona per creare link a pagine di libri su Google Libri, aggiungere immagini di copertina e indicare la disponibilità dell'anteprima. - Elenco di libri alternativo
Come nell'esempio precedente, in questo esempio vengono aggiunti link alla Ricerca di libri usando un callback dell'API asincrono. - AJAX interattivo
Potrebbe interessarti l'uso di Dynamic Links in un'applicazione AJAX altamente interattiva. Questo esempio mostra come emettere una serie di chiamate diverse senza aggiornare la pagina.
La risposta è un oggetto JSON con due campi, "books" che ha un valore di una mappa di oggetti del libro e "options" che contiene un elenco delle opzioni abilitate per quella richiesta. Se non è stata specificata alcuna opzione, il campo "options" può essere omesso nella risposta. Ad esempio:
Request:
https://books.google.com/books?jscmd=viewapi&bibkeys=0596000278,00-invalid-isbn,ISBN0765304368,0439554934&callback=ProcessGBSBookInfo
Response:
ProcessGBSBookInfo({
"0596000278":{
"bib_key":"0596000278",
"info_url":"https://books.google.com/books?id=ezqe1hh91q4C&source=gbs_ViewAPI",
"preview_url":"https://books.google.com/books?id=ezqe1hh91q4C&printsec=frontcover&sig=zSQ5gwlX1NZl_24M86KS8Rbj33Q&source=gbs_ViewAPI",
"thumbnail_url":"https://books.google.com/books?id=ezqe1hh91q4C&pg=PR3&img=1&zoom=5&sig=bBmzIAIiCtMcM7Ii7TUHycqqEWg",
"preview":"partial"
},
"ISBN0765304368":{
"bib_key":"ISBN0765304368",
"info_url":"https://books.google.com/books?id=gfg13CM_kU8C&source=gbs_ViewAPI",
"preview_url":"https://books.google.com/books?id=gfg13CM_kU8C&printsec=frontcover&sig=jIrSb_SkcQRhy_VvtnKbTXjmvos&source=gbs_ViewAPI",
"thumbnail_url":"https://books.google.com/books?id=gfg13CM_kU8C&pg=PP1&img=1&zoom=5&sig=LsTwGVAsy_qWYMPM6HVDTPAMokg",
"preview":"full"
},
"0439554934":{
"bib_key":"0439554934",
"info_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI",
"preview_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI",
"thumbnail_url":"https://books.google.com/books?id=iwiYGwAACAAJ&printsec=frontcover&img=1&zoom=5&sig=_L6ySKDAs-8gNK28c3NyFdO22ZM",
"preview":"noview"}
});
Gli sviluppatori possono quindi modificare i contenuti e l'aspetto delle proprie pagine web in base ai risultati JSON recuperati dal server GBS. Al momento, GBS non fornisce librerie per modificare il DOM.
Parametri e campi aggiuntivi
Confronto tra modalità sincrona e asincrona
Modalità asincrona
In modalità asincrona, lo sviluppatore inserisce il tag <script> nella <head> del documento e crea l'URL con tutti gli identificatori necessari per visualizzare la pagina. I dati vengono ricevuti dalla chiamata in una variabile. In questo modo le informazioni del libro sono disponibili per il resto del documento e il codice è immediatamente accessibile nel codice HTML e JavaScript.
Modalità sincrona
In modalità sincrona, lo sviluppatore utilizza l'URL al centro del codice HTML <body>; la risposta viene gestita utilizzando un callback JavaScript.
Domande frequenti
Esempi di codice
Questa sezione fornisce esempi che illustrano diversi modi di utilizzare i link dinamici. Puoi fare clic su qualsiasi esempio per vedere come funziona. Per visualizzare il codice sottostante, "visualizza sorgente" dal browser.