Questo documento descrive il protocollo utilizzato dalle API di dati di Google, incluse le informazioni sull'aspetto di una query, sui risultati e così via.
Per ulteriori informazioni sulle API di dati di Google, consulta il documento della Guida per gli sviluppatori di dati di Google e la Guida ai protocolli.
Pubblico
Questo documento è destinato a chiunque voglia comprendere i dettagli del formato XML e del protocollo utilizzati dalle API di dati di Google.
Se vuoi semplicemente scrivere codice che utilizzi le API client di dati di Google, non hai bisogno di conoscere questi dettagli; puoi usare le librerie client specifiche per i vari linguaggi.
Tuttavia, se vuoi comprendere il protocollo, leggi questo documento. Ad esempio, potresti voler leggere questo documento per svolgere le seguenti attività:
- la valutazione dell'architettura dei dati di Google
- programmazione mediante il protocollo senza utilizzare le librerie client dei dati di Google fornite
- scrittura di una libreria client in una nuova lingua
Questo documento presuppone che tu abbia una comprensione delle nozioni di base di XML, spazi dei nomi, feed distribuiti in syndication e delle richieste GET, POST, PUT e DELETE in HTTP, nonché del concetto di HTTP "risorsa". Per ulteriori informazioni in merito, consulta la sezione Risorse aggiuntive di questo documento.
Questo documento non si basa su alcun linguaggio di programmazione: puoi inviare e ricevere messaggi di dati di Google utilizzando qualsiasi linguaggio di programmazione che ti consente di inviare richieste HTTP e analizzare risposte basate su XML.
Dettagli protocollo
Questa sezione descrive il formato del documento di dati di Google e la sintassi delle query.
Formato del documento
Dati Google, Atom e RSS 2.0 condividono tutti lo stesso modello di dati di base: un container che contiene sia dati globali che qualsiasi numero di voci. Per ogni protocollo, il formato è definito da uno schema di base, ma può essere esteso utilizzando gli spazi dei nomi stranieri.
Le API di dati di Google possono utilizzare il formato di syndication Atom (sia per le operazioni di lettura che per scrittura) o il formato RSS (solo per le letture).
Atom è il formato predefinito dei dati di Google. Per richiedere una risposta in formato RSS, utilizza il parametro /alt=rss/; per ulteriori informazioni, consulta la sezione Richieste di query.
Quando richiedi dati in formato RSS, Google Data fornisce un feed (o un'altra rappresentazione della risorsa) in formato RSS. Se per una determinata proprietà dei dati di Google non esiste una proprietà RSS equivalente, questa utilizza la proprietà Atom, etichettandola con uno spazio dei nomi appropriato per indicare che si tratta di un'estensione di RSS.
Nota: la maggior parte dei feed di dati di Google in formato Atom utilizza lo spazio dei nomi Atom come spazio dei nomi predefinito specificando un attributo xmlns nell'elemento feed. Per alcuni esempi, consulta la sezione degli esempi. Pertanto, negli esempi in questo documento non è specificato atom: per gli elementi in un feed in formato Atom.
Le seguenti tabelle mostrano le rappresentazioni Atom e RSS degli elementi dello schema. Tutti i dati non menzionati in queste tabelle vengono considerati come XML normale e vengono visualizzati allo stesso modo in entrambe le rappresentazioni. Salvo diversamente indicato, gli elementi XML in una determinata colonna si trovano nello spazio dei nomi corrispondente alla colonna. Questo riepilogo utilizza la notazione XPath standard: in particolare, le barre mostrano la gerarchia degli elementi, mentre il segno @ indica un attributo di un elemento.
In ciascuna delle seguenti tabelle, gli elementi evidenziati sono obbligatori.
La tabella seguente mostra gli elementi di un feed di dati di Google:
| Elemento schema feed | Rappresentazione atomica | Rappresentazione RSS |
|---|---|---|
| Titolo feed | /feed/title |
/rss/channel/title |
| ID feed | /feed/id |
/rss/channel/atom:id |
| Link HTML del feed | /feed/link[@rel="alternate"]\[@type="text/html"]/@href |
/rss/channel/link |
| Descrizione feed | /feed/subtitle |
/rss/channel/description |
| Lingua del feed | /feed/@xml:lang |
/rss/channel/language |
| Copyright del feed | /feed/rights |
/rss/channel/copyright |
| Autore feed |
(Obbligatorio in alcuni casi; vedi la specifica Atom). |
/rss/channel/managingEditor |
| Data ultimo aggiornamento del feed | /feed/updated(formato RFC 3339) |
/rss/channel/lastBuildDate(formato RFC 822) |
| Categoria feed | /feed/category/@term |
/rss/channel/category |
| Schema categoria feed | /feed/category/@scheme |
/rss/channel/category/@domain |
| Generatore feed | /feed/generator/feed/generator/@uri |
/rss/channel/generator |
| Icona Feed | /feed/icon |
/rss/channel/image/url (a meno che non sia presente anche un logo, nel qual caso l'icona non è inclusa nel feed) |
| Logo del feed | /feed/logo |
/rss/channel/image/url |
La tabella seguente mostra gli elementi di un feed dei risultati di ricerca di dati di Google. Tieni presente che Google Data espone alcuni degli elementi di risposta di OpenSearch 1.1 nei feed dei risultati di ricerca.
| Elemento dello schema del feed dei risultati di ricerca | Rappresentazione atomica | Rappresentazione RSS/OpenSearch |
|---|---|---|
| Numero di risultati di ricerca | /feed/openSearch:totalResults |
/rss/channel/openSearch:totalResults |
| Indice iniziale del risultato di ricerca | /feed/openSearch:startIndex |
/rss/channel/openSearch:startIndex |
| Numero di risultati di ricerca per pagina | /feed/openSearch:itemsPerPage |
/rss/channel/openSearch:itemsPerPage |
La tabella seguente mostra gli elementi di una voce di dati di Google:
| Elemento schema voce | Rappresentazione atomica | Rappresentazione RSS |
|---|---|---|
| ID voce | /feed/entry/id |
/rss/channel/item/guid |
| ID versione voce | Facoltativamente, è incorporato in EditURI (consulta la sezione Contemporaneità ottimistica di questo documento). | — |
| Titolo della voce | /feed/entry/title |
/rss/channel/item/title |
| Link voce | /feed/entry/link |
/rss/channel/item/link/rss/channel/item/enclosure/rss/channel/item/comments |
| Riepilogo voce |
(Obbligatorio in alcuni casi; vedi la specifica Atom). |
/rss/channel/item/atom:summary |
| Contenuti della voce |
Se non è presente alcun elemento dei contenuti, la voce deve contenere almeno un elemento |
/rss/channel/item/description |
| Autore voce |
(Obbligatorio in alcuni casi; vedi la specifica Atom). |
/rss/channel/item/author |
| Categoria voce | /feed/entry/category/@term |
/rss/channel/item/category |
| Schema categoria di voci | /feed/entry/category/@scheme |
/rss/channel/item/category/@domain |
| Data di pubblicazione dell'ingresso | /feed/entry/published(RFC 3339) |
/rss/channel/item/pubDate(RFC 822) |
| Data di aggiornamento voce | /feed/entry/updated(RFC 3339) |
/rss/channel/item/atom:updated(RFC 3339) |
Query
Questa sezione descrive come utilizzare il sistema di query.
Query sui design di modello di query
Il modello di query è intenzionalmente molto semplice. I principi base sono:
- Le query sono espresse come URI HTTP, anziché come intestazioni HTTP o come parte del payload. Uno dei vantaggi di questo approccio è che puoi collegarti a una query.
- I predicati hanno come ambito un singolo elemento. Non c'è modo di inviare una query di correlazione, ad esempio "trova tutte le email delle persone che mi hanno inviato almeno dieci email oggi".
- L'insieme di proprietà su cui le query possono eseguire la predisposizione è molto limitato; la maggior parte di queste sono semplicemente query di ricerca a testo intero.
- L'ordine dei risultati dipende dall'implementazione.
- Il protocollo è estensibile naturalmente. Se vuoi esporre ulteriori predicati o ordinamenti nel tuo servizio, puoi farlo facilmente grazie all'introduzione di nuovi parametri.
Richieste di query
Un client interroga un servizio dati Google inviando una richiesta HTTP GET. L'URI della query è costituito dall'URI della risorsa (chiamato FeedURI in Atom) seguito dai parametri di ricerca: La maggior parte dei parametri di ricerca è rappresentata come parametri URL ?name=value[&...] tradizionali. I parametri delle categorie vengono gestiti in modo diverso (vedi di seguito).
Ad esempio, se il valore URI del feed è http://www.example.com/feeds/jo, potresti inviare una query con il seguente URI:
http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z
I servizi dati di Google supportano il GET HTTP condizionale. Hanno impostato l'intestazione Risposta finale modificata in base al valore dell'elemento <atom:updated> nel feed o nella voce restituita. Un client può restituire questo valore come valore dell'intestazione della richiesta If-Modified- since per evitare di recuperare di nuovo i contenuti se non sono cambiati. Se i contenuti non hanno subito modifiche dopo l'evento If-Modified-After, il servizio dati di Google restituisce una risposta HTTP 304 (Not Modified).
Un servizio dati Google deve supportare le query per categorie e alt; il supporto per altri parametri è facoltativo. Il passaggio di un parametro standard non compreso da un determinato servizio genera una risposta 403 Forbidden. Il passaggio di un parametro non standard non supportato genera una risposta 400 Bad Request. Per informazioni sugli altri codici di stato, consulta la sezione Codici di stato HTTP di questo documento.
I parametri di ricerca standard sono riepilogati nella tabella seguente. Tutti i valori dei parametri devono essere codificati nell'URL.
| Parametro | Significato | Note |
|---|---|---|
q |
Stringa di query a testo intero |
|
/-/category |
Filtro categoria |
|
category |
Filtro categoria |
|
author |
Autore voce |
|
alt |
Tipo di rappresentazione alternativo |
|
updated-min, updated-max |
Limiti applicati alla data di aggiornamento della voce |
|
published-min, published-max |
Limiti alla data di pubblicazione della voce |
|
start-index |
Indice basato su 1 del primo risultato da recuperare |
|
max-results |
Numero massimo di risultati da recuperare | Per qualsiasi servizio con un valore max-results predefinito (per limitare le dimensioni predefinite dei feed), puoi specificare un numero molto elevato se vuoi ricevere l'intero feed. |
| ID articolo | ID di una voce specifica da recuperare |
|
Informazioni sulle query per categoria
Abbiamo deciso di specificare un formato leggermente insolito per le query di categoria. Invece di una query come la seguente:
http://example.com/jo?category=Fritz&category=2006
utilizziamo:
http://example.com/jo/-/Fritz/2006
Questo approccio identifica una risorsa senza utilizzare parametri di ricerca e produce URI più puliti. Abbiamo scelto questo approccio per le categorie perché riteniamo che saranno le query più comuni.
Lo svantaggio di questo approccio è che chiediamo di utilizzare /-/ nelle query per categoria, in modo che i servizi dati di Google possano distinguere le query correlate a categorie da altri URI delle risorse, ad esempio http://example.com/jo/MyPost/comments.
Risposte a query
Le query restituiscono un feed Atom, una voce Atom o un feed RSS, a seconda dei parametri della richiesta.
I risultati della query contengono i seguenti elementi OpenSearch direttamente sotto l'elemento <feed> o <channel> (a seconda che i risultati siano Atom o RSS):
openSearch:totalResults- Il numero totale di risultati di ricerca per la query (non necessariamente tutti presenti nel feed dei risultati).
openSearch:startIndex- L'indice in base 1 del primo risultato.
openSearch:itemsPerPage- Il numero massimo di elementi che compaiono su una pagina. Ciò consente ai clienti di generare link diretti a qualsiasi insieme di pagine successive. Tuttavia, per un possibile problema nell'utilizzo di questo numero, consulta la nota relativa a
start-indexnella tabella della sezione Richieste di query.
Il feed e le voci di risposta Atom possono includere anche i seguenti elementi di dati Atom e Google (nonché altri elencati nella specifica Atom):
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>- Specifica l'URI da cui è possibile recuperare il feed Atom completo.
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>- Specifica il PostURI del feed Atom (dove possono essere pubblicate nuove voci).
<link rel="self" type="..." href="..."/>- Contiene l'URI di questa risorsa. Il valore dell'attributo
typedipende dal formato richiesto. Se nel frattempo non vengono modificati dati, l'invio di un altro GET a questo URI restituisce la stessa risposta. <link rel="previous" type="application/atom+xml" href="..."/>- Specifica l'URI del blocco precedente di questo set di risultati di query, se suddiviso.
<link rel="next" type="application/atom+xml" href="..."/>- Specifica l'URI del blocco successivo di questo set di risultati di query, se suddiviso.
<link rel="edit" type="application/atom+xml" href="..."/>- Specifica il valore URI URI della voce Atom (a cui invii una voce aggiornata).
Di seguito è riportato un corpo di risposta di esempio in risposta a una query di ricerca:
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
<id>http://www.example.com/feed/1234.1/posts/full</id>
<updated>2005-09-16T00:42:06Z</updated>
<title type="text">Books and Romance with Jo and Liz</title>
<link rel="alternate" type="text/html" href="http://www.example.net/"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="http://schemas.google.com/g/2005#post"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="self" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<generator version="1.0"
uri="http://www.example.com">Example Generator Engine</generator>
<openSearch:totalResults>2</openSearch:totalResults>
<openSearch:startIndex>0</openSearch:startIndex>
<entry>
<id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id>
<published>2005-01-09T08:00:00Z</published>
<updated>2005-01-09T08:00:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1009</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
<entry>
<id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id>
<published>2005-01-07T08:00:00Z</published>
<updated>2005-01-07T08:02:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1007</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
</feed>
Se il feed richiesto è in formato Atom, se non sono specificati parametri di ricerca e se il risultato non contiene tutte le voci, viene inserito il seguente elemento nel feed di primo livello: <link rel="next" type="application/atom+xml" href="..."/>. Rimanda a un feed contenente l'insieme di voci successivo. I set successivi contengono un elemento <link rel="previous" type="application/atom+xml" href="..."/> corrispondente. Seguendo tutti i link successivi, un client può recuperare tutte le voci di un feed.
Codici di stato HTTP
La tabella seguente descrive il significato dei vari codici di stato HTTP nel contesto dei servizi dati Google.
| Codice | Spiegazione |
|---|---|
| 200 OK | Nessun errore. |
| 201 CREATA | Creazione di una risorsa riuscita. |
| 304 NON MODIFICATO | La risorsa non è stata modificata dal momento specificato nell'intestazione If-Modified-From della richiesta. |
| RICHIESTA 400 | URI o intestazione della richiesta non valido o parametro non standard non supportato. |
| 401 NON AUTORIZZATO | Autorizzazione richiesta. |
| 403 VIETATO | Parametro standard non supportato oppure autenticazione o autorizzazione non riuscite. |
| 404: NON TROVATO | Risorsa (ad esempio un feed o una voce) non trovata. |
| CONFLITTO 409 | Il numero di versione specificato non corrisponde a quello più recente della risorsa. |
| 500 ERRORE SERVER INTERNO | Errore interno. Questo è il codice predefinito utilizzato per tutti gli errori non riconosciuti. |
Contemporaneità ottimista (controllo delle versioni)
A volte è importante assicurarsi che più client non sovrascrivano inavvertitamente le modifiche l'uno dell'altro. Questa operazione può essere eseguita facilmente assicurandosi che la versione corrente di una voce modificata da un client coincida con la versione su cui si basa il client. Se il secondo client esegue un aggiornamento prima che il primo client lo faccia, l'aggiornamento del primo client viene negato, in quanto il primo client non è più basato sulle modifiche dell'ultima versione.
Nei feed di dati di Google che supportano il controllo delle versioni, possiamo ottenere questa semantica aggiungendo un ID versione alla voce EditURI di ogni voce. Tieni presente che è interessato solo l'elemento EditURI, non l'ID voce. In questo schema, ogni aggiornamento cambia il valore EditURI della voce, garantendo così che i successivi aggiornamenti basati sulla versione originale non vadano a buon fine. Ovviamente, le eliminazioni sono identiche agli aggiornamenti di questa funzionalità. Se invii un'eliminazione con un numero di versione precedente, l'eliminazione non avrà esito positivo.
Non tutti i feed di dati di Google supportano la contemporaneità ottimistica. Se il server rileva un conflitto di versione su PUT o DELETE in un feed che lo supporta, risponde con 409 Conflict. Il corpo della risposta contiene lo stato attuale della voce (un documento di voce Atom). Si consiglia al cliente di risolvere il conflitto e inviare nuovamente la richiesta, utilizzando EditURI della risposta 409.
Motivazione e note di design
Questo approccio alla contemporaneità ottimistica ci consente di implementare la semantica che vogliamo senza richiedere un nuovo markup per gli ID versione, il che rende le risposte dei dati di Google compatibili con gli endpoint di Google Data Atom.
Invece di specificare gli ID versione, avremmo potuto scegliere di esaminare il timestamp di aggiornamento per ogni voce (/atom:entry/atom:updated). Tuttavia, ci sono due problemi nell'utilizzo del timestamp di aggiornamento:
- Funziona solo per gli aggiornamenti e non per le eliminazioni.
- Impone alle applicazioni di utilizzare valori di data/ora come ID versione, il che renderebbe più difficile l'adattamento dei dati di Google a molti datastore esistenti.
Autenticazione
Quando un client tenta di accedere a un servizio, potrebbe essere necessario fornire le sue credenziali al servizio per dimostrare che quest'ultimo è autorizzato a eseguire l'azione in questione.
L'approccio che un client dovrebbe utilizzare per l'autenticazione dipende dal tipo di client:
- Un'applicazione desktop deve utilizzare un sistema di autenticazione specifico di Google chiamato Autenticazione account per le applicazioni installate (noto anche come "ClientLogin"). I clienti basati sul Web non devono utilizzare questo sistema.
- Un client basato sul Web, ad esempio un front-end di terze parti a un servizio dati Google, deve utilizzare un sistema di autenticazione specifico di Google denominato Account Authentication Proxy for Web-Based Applications (noto anche come "AuthSub").
Nel sistema ClientLogin, il client desktop chiede all'utente le proprie credenziali, quindi le invia al sistema di autenticazione di Google.
Se l'autenticazione ha esito positivo, il sistema di autenticazione restituisce un token che il client utilizza successivamente (in un'intestazione HTTP Authorization) quando invia le richieste di dati di Google.
Se l'autenticazione non riesce, il server restituisce un codice di stato 403 Forbidden e un'intestazione WWW-Authenticate contenente una verifica applicabile all'autenticazione.
Il sistema AuthSub funziona in modo simile, ma invece di chiedere le credenziali all'utente, lo connette a un servizio Google che richiede le credenziali. Il servizio restituisce quindi un token che l'applicazione web può utilizzare; il vantaggio di questo approccio è che Google (anziché il front-end web) gestisce e archivia in modo sicuro le credenziali dell'utente.
Per informazioni dettagliate su questi sistemi di autenticazione, consulta la documentazione Panoramica dell'autenticazione dei dati di Google o la documentazione relativa all'autenticazione dell'Account Google.
Stato della sessione
Molte implementazioni che richiedono l'applicazione della logica di business richiedono il tempo di sessione, ovvero il monitoraggio dello stato della sessione di un utente.
Google monitora lo stato della sessione in due modi: tramite i cookie e con un token che può essere inviato come parametro di ricerca. Entrambi i metodi ottengono lo stesso effetto. Consigliamo ai clienti di supportare uno di questi metodi di monitoraggio dello stato della sessione (uno dei due è sufficiente). Se un cliente non supporta nessuno di questi metodi, continuerà a utilizzare i servizi di dati di Google, ma le prestazioni potrebbero risentirne rispetto a quelle dei client che supportano questi metodi. Nello specifico, se un client non supporta questi metodi, ogni richiesta genera un reindirizzamento e quindi ogni richiesta (ed eventuali dati associati) viene inviata al server due volte, il che influisce sulle prestazioni del client e del server.
Poiché le librerie client di Google gestiscono lo stato della sessione per tuo conto, se utilizzi le nostre librerie non devi fare nulla per ottenere il supporto dello stato della sessione.
Risorse aggiuntive
Potrebbero esserti utili i seguenti documenti di terze parti:
- Confronto tra Atom e RSS da intertwing
- Panoramica di Atom da IBM
- Estensioni RSS a Dublin Core per RSS
- Definizioni dei metodi HTTP 1.1; specifica per
GET,POST,PUTeDELETE - Definizioni dei codici di stato HTTP 1.1
- Come creare un protocollo REST
- Creare servizi web in un ambiente REST
- Introduzione tecnica a XML
- Spazi dei nomi XML per esempio