API di Blogger: guida introduttiva

Questo documento spiega come iniziare a utilizzare l'API di Blogger.

Prima di iniziare

Crea un account Google

Assicurati di avere configurato un Account Google. Per proteggerti dalla perdita accidentale di dati, ti consigliamo di utilizzare un Account Google separato a scopo di sviluppo e test. Se disponi già di un account di prova, è tutto pronto; puoi visitare l'interfaccia utente di Blogger per impostare, modificare o visualizzare i tuoi dati di test.

Familiarizza con Blogger

Se non hai dimestichezza con i concetti di Blogger, leggi questo documento e sperimenta l'interfaccia utente prima di iniziare a programmare. In questo documento si presuppone che tu abbia familiarità con Blogger, con i concetti di programmazione web e con 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.

Quando l'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.

Sfondo API Blogger

Concetti di Blogger

Blogger si basa su cinque concetti di base:

  • Blog: il concetto alla base dell'API. Un blog contiene post e pagine. Questo è il contenitore delle meta informazioni del blog come il nome e la descrizione.
  • Post: un post del blog è l'elemento pubblicabile creato dall'autore del blog. Queste informazioni devono essere tempestive, rispecchiare ciò che gli autori vogliono pubblicare al mondo in questo momento. Con il passare del tempo, i contenuti dei blog invecchiano e diventano meno importanti.
  • Commenti: un commento è il punto in cui persone diverse dall'autore del post del blog reagiscono a ciò che ha scritto. Di tutto, dai mattoni ai bouquet.
  • Pagine: una pagina è uno spazio in cui vengono inseriti contenuti statici, ad esempio informazioni biografiche o modi per contattare l'utente. In genere si tratta di informazioni senza tempo che non cambiano molto spesso.
  • Utenti: un utente è una persona che interagisce con Blogger, che agisca come autore, amministratore o semplicemente lettore. Per i blog pubblici, i lettori possono essere anonimi, mentre nei blog privati un lettore deve essere identificato da Blogger.

Modello dei dati dell'API di Blogger

Una risorsa è una singola entità di dati con un identificatore univoco. L'API JSON di Blogger funziona su cinque tipi di risorse:

  • Risorsa blog: rappresenta un blog.
  • Risorsa post: rappresenta un post. Ogni risorsa post è secondaria di una risorsa blog.
  • Risorsa commenti: rappresenta un commento su un post specifico; ogni risorsa di commenti è secondaria di una risorsa Post.
  • Risorsa pagine: rappresenta una pagina statica; ogni risorsa pagina è figlio di una risorsa blog.
  • Risorsa utenti: rappresenta un utente non anonimo. Viene utilizzato per identificare l'autore di una pagina, un post o un commento.
La risorsa blog ha due tipi di risorse secondarie: pagine e post.
          Una risorsa Post può avere risorse per i commenti figlio.
Panoramica delle relazioni tra le risorse

Il modello dei dati dell'API di Blogger è basato su gruppi di risorse, denominati raccolte:

Raccolta blog
Una <span="apicollection">raccolta di blog è composta da tutti i blog a cui un utente dispone dei diritti di accesso. Puoi elencare i blog per utente o recuperare un singolo blog per ID.</span="apicollection">
Raccolta di post
Una raccolta di post è composta da tutte le risorse per i post all'interno di una specifica risorsa di blog.
Raccolta commenti
Una raccolta di commenti è composta da tutte le risorse per i commenti all'interno di una risorsa post specifica.
Raccolta di pagine
Una raccolta di pagine è composta da tutte le risorse di pagine all'interno di una specifica risorsa di blog.
Raccolta utenti
Una raccolta utenti è composta da tutte le risorse utente su Blogger e, pertanto, non può essere elencata. Un utente può recuperare la propria risorsa utente (ma nessun altro) in base all'ID o utilizzando l'identificatore self.

Operazioni dell'API di Blogger

Puoi richiamare diversi metodi su raccolte e risorse nell'API Blogger, come illustrato nella tabella seguente.

Operazione Descrizione Mappature REST HTTP
list Elenca tutte le risorse all'interno di una raccolta. GET su un URI della raccolta.
trova Recupera una risorsa specifica. GET su un URI della risorsa.
getByUrl Recupera una risorsa che cerca in base all'URL. GET con l'URL trasmesso come parametro.
getByPath Recupera una risorsa cercandola in base al percorso. GET con il percorso trasmesso come parametro.
listByUser Elenca le risorse di proprietà di un utente. GET su una raccolta di proprietà dell'utente.
search Cerca le risorse in base a un parametro di query. GET su un URL di ricerca, con la query trasmessa come parametro.
inserisci Creare una risorsa in una raccolta. POST su un URI della raccolta.
elimina Elimina una risorsa. DELETE su un URI della risorsa.
patch Aggiorna una risorsa utilizzando la semantica delle patch. PATCH su un URI della risorsa.
aggiorna Aggiorna una risorsa. PUT su un URI della risorsa.

La tabella seguente mostra i metodi supportati da ciascun tipo di risorsa. Tutte le operazioni list e get sui blog privati richiedono l'autenticazione.

Tipo di risorsa
Metodi supportati
elenco get getByUrl getByPath listByUser ricerca inserisci elimina patch aggiorna
Blog no no no no no no no
Post no no
Commenti no no no no no no no no
Pagine no no no no no no no no
Utenti no no no no no no no no no

Stili di chiamata

Esistono diversi modi per richiamare l'API:

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 Blogger

Le operazioni di Blogger supportate mappano direttamente ai verbi HTTP REST, come descritto nelle operazioni dell'API Blogger.

Il formato specifico degli URI dell'API di Blogger è:

https://www.googleapis.com/blogger/v3/users/userId
https://www.googleapis.com/blogger/v3/users/self
https://www.googleapis.com/blogger/v3/users/userId/blogs
https://www.googleapis.com/blogger/v3/users/self/blogs
https://www.googleapis.com/blogger/v3/blogs/blogId
https://www.googleapis.com/blogger/v3/blogs/byurl
https://www.googleapis.com/blogger/v3/blogs/blogId/posts
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/bypath
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/search
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments/commentId
https://www.googleapis.com/blogger/v3/blogs/blogId/pages
https://www.googleapis.com/blogger/v3/blogs/blogId/pages/pageId

La spiegazione completa degli URI utilizzati e i risultati di ciascuna operazione supportata nell'API sono riassunti nel documento di riferimento dell'API di Blogger.

Esempi

Elenca i blog per i quali l'utente autenticato dispone dei diritti di accesso:

GET https://www.googleapis.com/blogger/v3/users/self/blogs?key=YOUR-API-KEY

Scarica i post sul blog code.blogger.com, che ha l'ID blog 3213900:

GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY

REST da JavaScript

Puoi richiamare l'API Blogger da JavaScript, utilizzando il parametro di query callback e fornendo una funzione di callback. Quando il browser carica lo script, viene eseguita la funzione di callback e la risposta viene fornita alla funzione di callback. Questo approccio ti consente di scrivere applicazioni avanzate che visualizzano i dati di Blogger senza richiedere codice lato server.

L'esempio seguente recupera un post dal blog code.blogger.com, dopo che hai sostituito YOUR-API-KEY con la chiave API.

<html>
  <head>
    <title>Blogger API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
        document.getElementById("content").innerHTML += "<h1>" + response.title + "</h1>" + response.content;
      }
    </script>
    <script
    src="https://www.googleapis.com/blogger/v3/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></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.