Guida per gli sviluppatori: JavaScript

L'API di dati di Blogger consente alle applicazioni client di visualizzare e aggiornare i contenuti di Blogger sotto forma di feed di API di dati di Google.

La tua applicazione client può utilizzare l'API di dati di Blogger per creare nuovi post del blog, modificare o eliminare post di blog esistenti ed eseguire query per i post dei blog che corrispondono a determinati criteri.

Oltre a fornire alcune informazioni sulle funzionalità dell'API di dati di Blogger, questo documento fornisce esempi di interazioni di base dell'API di dati utilizzando la libreria client JavaScript. Se vuoi saperne di più sul protocollo sottostante utilizzato dalla libreria, consulta la sezione Protocollo di questa guida per gli sviluppatori.

Contenuti

Pubblico

Questo documento è destinato ai programmatori che desiderano scrivere applicazioni client JavaScript in grado di interagire con Blogger. Fornisce una serie di esempi di interazioni di base dell'API Data mediante l'uso della libreria client JavaScript.

Per informazioni di riferimento sull'API di dati di Blogger, consulta la Guida di riferimento del protocollo. In questo documento si presume che tu abbia compreso le idee generali alla base del protocollo delle API di dati di Google, nonché del modello dei dati e del flusso di controllo utilizzati dalla libreria client JavaScript. Inoltre, presuppone che tu sappia come programmare in JavaScript.

Per informazioni di riferimento sulle classi e sui metodi forniti dalla libreria client, consulta il riferimento per l'API della libreria client JavaScript.

Questo documento è stato progettato per essere letto in ordine; ogni esempio si basa su esempi precedenti.

Termini e condizioni d'uso

Quando utilizzi la libreria client JavaScript, accetti di rispettare i Termini e condizioni d'uso della libreria client JavaScript di Google.

Informazioni sugli ambienti supportati

Al momento, supportiamo solo le applicazioni client JavaScript eseguite in una pagina web in un browser. I browser attualmente supportati sono Firefox 1.5 e versioni successive e Internet Explorer 6.0 e versioni successive.

La libreria client JavaScript gestisce tutte le comunicazioni con il server del servizio. Se sei uno sviluppatore JS esperto, ti potresti chiedere: "Ma cosa succede alla stessa norma di origine?" La libreria client JavaScript consente al client di inviare richieste API di dati di Google da qualsiasi dominio, pur rimanendo conforme al modello di sicurezza del browser.

Per iniziare

Prima di poter scrivere un'applicazione client JavaScript, dovrai effettuare alcune impostazioni per acquisire la libreria.

Creazione di un account Blogger

Ti consigliamo di registrare un account Blogger a scopo di test. Blogger utilizza Account Google, quindi se disponi già di un account Google, non devi fare altro.

Acquisizione della biblioteca

Prima che il client possa utilizzare la libreria client, il client deve richiedere il codice della libreria client al server.

Inizia utilizzando un tag <script> nella sezione <head> del documento HTML per recuperare il caricatore API Google AJAX:

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

Per acquisire la libreria client dell'API di dati di Google dopo aver recuperato il caricatore, utilizza la seguente riga nel codice di configurazione JavaScript, che deve essere richiamata dalla sezione <head> del documento HTML (o da un file JavaScript incluso utilizzando un tag <script> nella sezione <head> del documento HTML):

google.load("gdata", "1.x");

Il secondo parametro di google.load() è il numero di versione richiesto della libreria client JavaScript.Il nostro schema di numerazione delle versioni è modellato in base a quello utilizzato dall'API di Google Maps. Ecco i possibili numeri di versione e il loro significato:

"1"
La penultima e l'ultima revisione della versione principale 1.
"1.x"
L'ultima revisione della versione principale 1.
"1.s"
L'ultima revisione stabile della versione principale 1. A volte dichiariamo "stabile" una determinata versione della libreria client in base al feedback che riceviamo dagli sviluppatori. Tuttavia, quella versione potrebbe non avere le funzionalità più recenti.
"1.0", "1.1" e così via
Una versione specifica della libreria con un numero di revisione maggiore e minore specificato.

Dopo aver chiamato google.load(), devi dire al caricatore di attendere il termine del caricamento della pagina e chiamare il codice:

google.setOnLoadCallback(getMyBlogFeed);

dove getMyBlogFeed() è una funzione che definiremo in una sezione successiva del documento. Utilizza questo approccio anziché avere un gestore onload collegato all'elemento <body>.

Autenticazione nel servizio Blogger

Puoi accedere a feed pubblici e privati utilizzando l'API di dati di Blogger. I feed pubblici non richiedono alcuna autenticazione, ma sono di sola lettura. Se vuoi modificare i blog, il client deve eseguire l'autenticazione prima di richiedere feed privati.

La libreria client JavaScript utilizza il sistema di autenticazione AuthSub. Per ulteriori informazioni sull'autenticazione con le API di dati di Google in generale, consulta la documentazione sull'autenticazione.

Autenticazione proxy AuthSub

L'autenticazione proxy AuthSub viene utilizzata dalle applicazioni web che devono autenticare i propri utenti tramite Account Google. L'operatore del sito web e il codice client non hanno accesso al nome utente e alla password dell'utente di Blogger; il client riceve invece speciali token AuthSub che consentono al client di agire per conto di un determinato utente.

Ecco una breve panoramica di ciò che accade durante il processo di autenticazione per un client JavaScript basato sul web:

  1. L'applicazione client chiama il metodo google.accounts.user.login() fornito dalla libreria client, passando un valore "scope" che indica quale servizio Google utilizzare. Per Blogger, l'ambito è "http://www.blogger.com/feeds/".
  2. La libreria client invia il browser alla pagina "Richiesta di accesso " di Google, dove l'utente può inserire le proprie credenziali per accedere al servizio.
  3. Se l'utente esegue l'accesso, il sistema AuthSub restituisce il browser all'URL del client web, trasmettendo il token di autenticazione.
  4. La libreria client JavaScript archivia il token in un cookie e restituisce il controllo alla funzione dell'applicazione client che ha chiamato google.accounts.user.login().
  5. Quando l'applicazione client chiama in seguito metodi della libreria client che interagiscono con Blogger, la libreria client collega automaticamente il token a tutte le richieste.

Nota: affinché la libreria client JavaScript possa effettuare richieste autenticate di Blogger in un browser web, la pagina deve contenere un'immagine ospitata nello stesso dominio della pagina. Può essere qualsiasi immagine, anche un'immagine trasparente di un solo pixel, ma deve esserci un'immagine nella pagina. Se vuoi che l'immagine non venga visualizzata sulla tua pagina, puoi utilizzare l'attributo style del tag <img> per posizionare l'immagine al di fuori dell'area di rendering. Ad esempio: style="position:absolute; top: -1000px;"

Ecco il codice applicazione client che gestisce l'accesso. Chiameremo la funzione setupMyService() da un altro codice più tardi.

function logMeIn() {
  scope = "http://www.blogger.com/feeds/";
  var token = google.accounts.user.login(scope);
}

function setupMyService() {
  var myService =
    new google.gdata.blogger.BloggerService('exampleCo-exampleApp-1');
  logMeIn();
  return myService;
}

Suggerimento: ti consigliamo vivamente di fornire un pulsante di accesso o un altro meccanismo di immissione da parte dell'utente per richiedere all'utente di avviare manualmente la procedura di accesso. Se, invece, chiami google.accounts.user.login() subito dopo il caricamento, senza attendere l'interazione dell'utente, la prima cosa che l'utente vede all'arrivo sulla tua pagina è una pagina di accesso di Google. Se l'utente decide di non eseguire l'accesso, Google non lo reindirizza alla tua pagina; pertanto, dal punto di vista dell'utente, ha tentato di visitare la tua pagina ma è stata rimandata alla pagina precedente e non l'ha mai rimandata indietro. Questo scenario potrebbe essere complicato e frustrante per gli utenti. Nel codice di esempio di questo documento chiameremo google.accounts.user.login() subito dopo il caricamento, per semplificare l'esempio, ma sconsigliamo questo approccio per le applicazioni client reali.

Tieni presente che non devi fare nulla con la variabile denominata token; la libreria client tiene traccia del token, così non devi fare nulla.

Nota: quando crei un nuovo oggetto BloggerService, la libreria client chiama un metodo con nome google.gdata.client.init(), che verifica che il browser su cui è in esecuzione il client sia supportato. In caso di errore, la libreria client mostra un messaggio di errore all'utente. Per gestire personalmente questo tipo di errore, puoi chiamare esplicitamente google.gdata.client.init(handleInitError) prima di creare il servizio, dove handleInitError() è la funzione. Se si verifica un errore di inizializzazione, la funzione riceve un oggetto Error standard; puoi fare ciò che vuoi con quell'oggetto.

Il token rimane valido finché non lo revochi richiamando google.accounts.user.logout():

function logMeOut() {
  google.accounts.user.logout();
}

Se non chiami logout(), il cookie che memorizza il token dura due anni, a meno che l'utente non lo elimini. Il cookie viene conservato in tutte le sessioni del browser, in modo che l'utente possa chiudere e riaprire il browser, tornare al client e mantenere l'accesso.

Tuttavia, esistono alcune circostanze insolite in cui un token può non essere più valido durante una sessione. Se Blogger rifiuta un token, il client dovrebbe gestire la condizione di errore chiamando logout() per rimuovere il cookie contenente il token attuale, quindi chiamando di nuovo login() per acquisire un nuovo token valido.

Esistono altri due metodi AuthSub che potresti trovare utili in vari contesti:

  • google.accounts.user.checkLogin(scope) indica se il browser dispone o meno di un token di autenticazione per l'ambito specificato.
  • google.accounts.user.getInfo() fornisce informazioni dettagliate sul token corrente, per l'uso per il debug.

Per maggiori dettagli sull'utilizzo di JavaScript per interagire con AuthSub, incluse informazioni sulla gestione dei token e su checkLogin() e getInfo(), consulta il documento sull'utilizzo dell'autenticazione "AuthSub" con la libreria client JavaScript.

Torna all'inizio