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 solo quando un libro è nel nostro indice, oppure di visualizzare link che indicano agli utenti se un libro può essere visualizzato in anteprima 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à in precedenza era nota come API Book Visibility.
La Procedura guidata di anteprima è uno strumento basato su Dynamic Links che rende ancora più facile il collegamento alle anteprime dei libri dal sito copiando solo poche righe di codice. Questo documento è rivolto agli sviluppatori più avanzati che vogliono personalizzare la modalità di collegamento a Ricerca Libri.
Contenuti
- Pubblico
- Terminologia della ricerca Libri
- Introduzione
- Linee guida per il branding
- L'API lato client
- Modalità sincrona e asincrona
- Domande frequenti
- Esempi di codice
Pubblico
La documentazione sui link dinamici è destinata ai programmatori che desiderano scrivere applicazioni web che rimandino a libri in Google Libri. In questa documentazione si presuppone che tu abbia familiarità con il protocollo HTTP e con JavaScript di base.
Terminologia della ricerca Libri
Google Libri rispetta le limitazioni relative al 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à è suddivisa nelle seguenti classi:
- Visualizzazione completa
- È possibile visualizzare tutto il libro. 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 dalla 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. Il libro non è stato scansionato o è protetto da copyright. Google Libri non ha ricevuto l'autorizzazione a mostrare più di alcuni "snippet" correlati al termine di ricerca dell'utente.
Introduzione
La documentazione relativa ai link statici descrive un modo molto semplice per generare URL che rimandano alla pagina di un determinato libro su Google Libri. Purtroppo, può capitare che un determinato libro non sia presente nell'indice di Google Libri o che gli utenti di una determinata posizione geografica non abbiano a disposizione un'anteprima. Poiché i link statici sono "non vedenti", a volte non producono l'effetto previsto.
Dynamic Links offre un metodo lato client alternativo e programmatico per eseguire query sulla visibilità di un libro utilizzando JavaScript. In questo modo puoi includere link più affidabili e prevedibili a Google Ricerca Libri, garantendo agli utenti un'esperienza più coerente. Poiché la visibilità varia in base alla posizione dell'utente finale, l'interfaccia del link dinamico non è progettata per le query lato server o offline.
Per avere un'idea di cosa può fare Dynamic Links, 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 collegamenti a Google Libri.
- Per il collegamento alle anteprime su Google Libri devi utilizzare solo il pulsante Anteprima Google approvato.
- Qualsiasi link di testo, pulsante, documentazione o testo descrittivo deve rispettare le convenzioni di denominazione approvate. Ad esempio, non utilizzare i verbi "scaricare" o "leggere" per creare link ad anteprime di Google Libri, dato che solo le opere di dominio pubblico possono essere scaricate nella loro interezza.
Esempio di branding
La sezione degli esempi alla fine del documento fornisce ulteriori esempi conformi alle attuali linee guida per il branding.
API lato client
L'elemento fondamentale del link dinamico lato client è un formato URL che consente agli sviluppatori di creare URL di richiesta di 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 i link ai libri, ma il campo ID libro può contenere più ID libro separati da virgole e sono presenti parametri aggiuntivi "jscmd" e "callback". Facoltativamente, possono essere presenti argomenti aggiuntivi per controllare i filtri di visibilità.
Dynamic Links supporta diversi metodi per identificare i libri: ISBN, numeri OCLC e chiavi LCCN. L'API consente query in batch di dimensioni massime pari a quelle massime di una richiesta GET.
- ISBN
&bibkeys=ISBN:0451526538(l'API supporta sia ISBN 10 che 13).- OCLC
&bibkeys=OCLC:36792831- LCCN
&bibkeys=LCCN:96072233
Formato dei risultati JSON
La risposta a questa chiamata sarà informazioni sui libri richiesti 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_key
- L'identificatore utilizzato per eseguire query su questo libro.
- info_url
- Un URL a una pagina di Google Libri contenente informazioni sul libro (la pagina Informazioni su questo libro).
- preview_url
- Un URL che rimanda all'anteprima del libro, che indirizza l'utente direttamente alla copertina del libro. Se per una richiesta è disponibile soltanto la Visualizzazione snippet o Nessun libro in anteprima, non verrà restituito alcun URL di anteprima.
- thumbnail_url
- Un URL a una miniatura della copertina del libro.
- anteprima
- Un valore che indica lo stato di visibilità del libro:
full(per i libri in Visualizzazione completa),partial(per i libri in anteprima limitata) onoview(per i libri con snippet snippet o Senza 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 passiamo il ritorno.
- D: È necessaria una chiave API o un'altra autorizzazione per utilizzare i link dinamici?
- R: Non sono necessarie chiavi API o altre autorizzazioni per utilizzare i link dinamici. Per iniziare, copia e incolla uno dei nostri esempi e inizia ad armeggiare.
- D: E per quanto riguarda i browser che non supportano JavaScript o lo hanno disattivato?
- R: Non c'è modo di 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 ricorda che non puoi sapere in anticipo se Google Libri contiene il libro a cui rimandi.
- D: Quanti libri posso cercare contemporaneamente?
- R: Il numero di libri che puoi cercare è limitato solo dalla lunghezza delle richieste GET. In Microsoft Internet Explorer, la lunghezza massima dell'URL (2.083 caratteri) limita la lunghezza delle richieste GET.
- D: Appena un attimo fa, Google Libri restituiva risultati per un libro. Perché ora non vengono restituiti risultati?
- R: Poiché gli sviluppatori emettono spesso una quantità atipica di richieste, potresti involontariamente lasciare una mancia sulle precauzioni di sicurezza presenti in Google Libri. Per verificare se ciò si verifica, visualizza ciò che viene restituito dall'API. Se si tratta di una richiesta di compilazione di un captcha, hai eseguito troppe query. Ti consigliamo di accedere a Google Libri e di riprovare.
- D: E la privacy?
- R: Nel rispondere alle domande sulla visibilità dei libri, Google riceve dati di log del server che non consentono l'identificazione personale. Prendiamo 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, comunica loro che il servizio invia anche query a Google tramite link dinamici.
- Pulsante Anteprima per la pagina di un libro
Se intendi utilizzare Dynamic Links per aggiungere pulsanti "Anteprima" a singole pagine dei libri sul tuo sito, questo è l'esempio che fa per te. Questa implementazione utilizza una chiamata sincrona a Google Libri. - Elenco di lettura del corso
Questo esempio mostra un tipico elenco di libri per un corso accademico. Utilizziamo un'unica chiamata sincrona per collegarti alle pagine dei libri su Google Libri, aggiungere immagini di copertina e indicare la disponibilità dell'anteprima. - Elenco di libri alternativi
Simile all'esempio precedente, in questo esempio vengono aggiunti link a Ricerca Libri utilizzando un callback dell'API asincrono. - AJAX interattivo
Ti potrebbe interessare utilizzare Dynamic Links in un'applicazione AJAX altamente interattiva. Questo esempio mostra come effettuare una serie di chiamate diverse senza aggiornare la pagina.
La risposta è un oggetto JSON con due campi, "libri", che ha il valore di una mappa di oggetti libro e "opzioni", che contiene un elenco delle opzioni abilitate per quella richiesta. Se non è stata specificata alcuna opzione, il campo "opzioni" 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 loro pagine web in base ai risultati JSON recuperati dal server GBS. Al momento, GBS non fornisce librerie per la modifica del DOM a questo scopo.
Parametri e campi aggiuntivi
Modalità sincrona e asincrona
Modalità asincrona
In modalità asincrona, lo sviluppatore inserisce il tag <script> nella sezione <head> del documento e crea l'URL con tutti gli identificatori necessari per il rendering della 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 sono immediatamente accessibili nel codice HTML e in 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 vederlo in azione. Per vedere il codice sottostante, apri il codice sorgente del tuo browser.