Nozioni di base sul protocollo

Avviso: questa pagina riguarda le API di Google più vecchie, le API di dati di Google; è pertinente solo per le API elencate nella directory delle API di dati di Google, molte delle quali sono state sostituite con API più recenti. Per informazioni su una nuova API specifica, consulta la documentazione della nuova API. Per informazioni sulle autorizzazioni per le richieste con un'API più recente, vedi Autenticazione e autorizzazione degli Account Google.

Questo documento descrive le nozioni di base del protocollo dati di Google utilizzato da molte API di Google, inclusi esempi di aspetto di una query, aspetto dei risultati e così via.

Per ulteriori informazioni sul protocollo dati di Google, consulta la pagina della panoramica della Guida per gli sviluppatori e la documentazione di riferimento.

Pubblico

Questo documento è destinato a chiunque voglia comprendere l'idea generale del formato e del protocollo XML utilizzati dalle API di dati di Google.

Anche se vuoi solo scrivere codice che utilizza le librerie client specifiche per i vari linguaggi, potresti leggere questo documento per comprendere cosa sta succedendo sotto il livello di astrazione della libreria client.

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: il tuo client può interagire con il server utilizzando qualsiasi linguaggio di programmazione che ti consente di inviare richieste HTTP e analizzare risposte basate su XML.

Se vuoi provare gli esempi in questo documento senza scrivere codice, potresti trovare utile le utilità a riga di comando cURL o Wget; per ulteriori informazioni, consulta le pagine manuali per tali utilità o il documento Utilizzo di cURL per interagire con i servizi che utilizzano il protocollo dati Google.

Esempi

I seguenti esempi mostrano le richieste HTTP che potresti inviare a un servizio generico utilizzando direttamente il protocollo API Google Data Protocol e i risultati che potresti ricevere. Per esempi su come inviare le richieste utilizzando vari linguaggi di programmazione, consulta gli esempi e le librerie client specifici dei vari linguaggi. Per informazioni sull'utilizzo del protocollo dati di Google con servizi Google specifici, consulta la documentazione specifica del servizio.

Richiedere un feed o altra risorsa

Supponiamo che ci sia un feed chiamato /myFeed e che il feed al momento non contenga voci. Per vederlo, invia la seguente richiesta HTTP al server:

GET /myFeed

Il server risponde:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Tieni presente che anche se il feed non contiene alcuna voce, contiene metadati, ad esempio un titolo e il nome di un autore. Contiene anche un identificatore della versione sotto forma di ETag HTTP.

Inserimento di una nuova voce

Per creare una nuova voce, invia una richiesta POST e fornisci la rappresentazione XML della nuova voce:

POST /myFeed

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Tieni presente che non fornisci gli elementi standard Atom <id>, <link> o <updated>; il server li crea in risposta alla tua richiesta POST. Tieni inoltre presente che l'autore di un feed non deve necessariamente essere lo stesso utente di una voce.

Il server risponde:

201 CREATED

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/1/'/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Ricerca di una stringa

Per eseguire una ricerca a testo intero per una determinata stringa, quando utilizzi un servizio che supporta le ricerche a testo intero, invia una richiesta GET con il parametro q. Per ulteriori informazioni sui parametri di ricerca, consulta Richieste di query nel documento di riferimento del protocollo.

GET /myFeed?q=This

Il server risponde con un feed contenente tutte le voci che corrispondono alla stringa di ricerca This. In questo caso ce n'è solo uno.

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"S0wCTlpIIip7ImA0X0QI"'>
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my entry</content>
  </entry>
</feed>

Aggiornamento di una voce

Per aggiornare una voce esistente, procedi nel seguente modo.

  1. Recupera la voce che vuoi aggiornare.
  2. Modificalo come preferisci.
  3. Invia una richiesta PUT, con la voce aggiornata nel corpo del messaggio, all'URI di modifica della voce. L'URI di modifica viene visualizzato nell'esempio precedente come attributo href dell'elemento <link rel='edit'>.

Devi inoltre specificare l'ETag della voce originale, per assicurarti di non sovrascrivere le modifiche di nessun altro.

Nell'esempio seguente, il testo della voce verrà sostituito dal valore precedente ("Questa è la mia voce") con un nuovo valore ("Questa è la mia prima voce"):

PUT /myFeed/1/1/

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

Il server risponde:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

Tieni presente che l'ETag è cambiato. Per saperne di più sulle versioni delle risorse, consulta la sezione Controllo delle versioni delle risorse (ETag) del documento di riferimento del protocollo.

Per visualizzare la nuova voce nel contesto, richiedi di nuovo l'intera risorsa:

GET /myFeed

Il server risponde:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D08FQn8-eil7ImA9WxZbFEw."'>
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my first entry.</content>
  </entry>
</feed>

Nota:se il firewall non consente PUT, esegui un POST HTTP e imposta l'intestazione di override del metodo nel seguente modo:

X-HTTP-Method-Override: PUT

Eliminare una voce

Per eliminare una voce esistente, invia una richiesta DELETE utilizzando l'URI di modifica della voce (fornito dal server nell'esempio precedente).

Se il firewall non consente DELETE, esegui un POST HTTP e imposta l'intestazione di override del metodo nel seguente modo:

X-HTTP-Method-Override: DELETE

Quando elimini una voce, puoi scegliere se eseguire un'eliminazione condizionale (solo se la voce non è stata modificata dall'ultima volta che l'hai recuperata) o un'eliminazione incondizionata. Per saperne di più, consulta la sezione Controllo delle versioni delle risorse (ETag) del documento di riferimento del protocollo. Per eseguire un'eliminazione incondizionata, imposta la seguente intestazione HTTP:

If-Match: *

L'esempio seguente elimina una voce (se le intestazioni sono impostate correttamente):

DELETE /myFeed/1/

Il server risponde:

200 OK

Esegui un'altra GET per verificare che ora il feed non contenga voci:

GET /myFeed

Il server risponde con un feed che non contiene altro che metadati:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Se l'eliminazione non riesce, il server risponde con un codice di errore. Per ulteriori informazioni, consulta Codici di stato HTTP nel documento di riferimento del protocollo.

Richiesta di feed parziali o voci (sperimentali)

A differenza del semplice feed di esempio mostrato in questo documento, in pratica, i feed possono essere molto complessi. Con alcune API puoi richiedere solo gli elementi o gli attributi di interesse, anziché la rappresentazione completa delle risorse. Evitare di recuperare e analizzare i dati non necessari può migliorare notevolmente l'efficienza della sua applicazione client.

Per richiedere una risposta parziale, utilizza il parametro di ricerca fields per specificare quali elementi o attributi vuoi restituire. Per ulteriori informazioni, consulta la sezione Risposta parziale nel documento di riferimento del protocollo.

L'esempio seguente richiede solo l'ID feed, nonché l'autore e il titolo di ogni voce.

GET /myFeed?fields=id,entry(author)

Il server risponde:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.example.com/myFeed</id>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
  </entry>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 2</title>
  </entry>
</feed>

Puoi utilizzare il parametro fields con qualsiasi tipo di richiesta che restituisce dati. Oltre a GET, sono inclusi POST e PUT (oltre a PATCH, che viene utilizzato per effettuare richieste di aggiornamento parziale).

Nota: il parametro di ricerca fields controlla solo i dati inviati in risposta a una richiesta; non influisce sui dati che devi fornire nel corpo di una richiesta PUT, POST o PATCH.

Di seguito sono riportati esempi di POST e PUT.

  • Quando effettui una richiesta POST per una risposta parziale, devi comunque fornire gli stessi dati descritti nella sezione Inserire una nuova voce. L'esempio seguente richiede una risposta parziale contenente solo il titolo della voce appena creata: 
    POST /myFeed?fields=title
      
...data...

    Il server risponde:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
  • Quando invii una richiesta PUT per una risposta parziale, devi comunque fornire una versione modificata della rappresentazione completa della risorsa, come descritto nella sezione Aggiornare una voce. L'esempio seguente richiede una risposta parziale contenente solo il nuovo valore ETag della voce modificata: 
    PUT /myFeed/1/1?fields=@gd:etag
  
...data...

    Il server risponde:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
  gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>

Aggiornamento di campi specifici (sperimentale)

Se l'API che stai utilizzando supporta una risposta parziale e contiene campi modificabili, puoi inoltre evitare di inviare dati non necessari quando modifichi una voce. L'aggiornamento parziale ti consente di inviare i dati solo per i campi da modificare.

Per utilizzare l'aggiornamento parziale, invia una richiesta PATCH allo stesso URI di modifica che utilizzi con PUT. I dati che invii con l'PATCH devono rispettare determinate convenzioni. Tuttavia, la semantica è abbastanza flessibile da consentirti di sostituire i dati nella risorsa di destinazione, aggiungervi informazioni o persino eliminarli da una singola richiesta.

Nota:come per PUT, devi specificare l'ETag della voce originale, per assicurarti di non sovraccaricare le modifiche di nessun altro.

Per maggiori informazioni su PATCH e sulla sua semantica, consulta l'articolo Aggiornamento parziale nel documento di riferimento del protocollo.

Questo esempio mostra una richiesta di aggiornamento parziale che modifica il titolo della voce:

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag="EksPTg1Bfyp7IWA6WhJT"
    gd:fields='title'>
  <title>New Title</title>
</entry>

Quando il server riceve una richiesta PATCH, prima rimuove i campi specificati dall'attributo gd:fields della voce (se presente), quindi unisce i dati forniti nel corpo della richiesta alla risorsa di destinazione. In questo esempio, l'elemento title viene prima rimosso dalla risorsa di destinazione, quindi il nuovo valore del titolo viene unito. Di fatto, questa richiesta sostituisce il titolo precedente con quello nuovo.

Tieni presente, tuttavia, che la semantica di PATCH deve unire la rappresentazione parziale nella risorsa esistente. Non è sempre necessario rimuovere un campo per aggiornarne il valore.

  • Se il campo può esistere solo una volta nella voce di destinazione, al momento dell'unione il campo nella rappresentazione parziale sovrascrive il campo corrispondente nella voce di destinazione.
  • Se il campo può esistere più di una volta nella voce di destinazione, al momento dell'unione viene aggiunto il campo parziale.

La differenza tra il modo in cui i campi si ripetono e quelli che non si ripetono viene mostrata dall'esempio successivo, che aggiunge un nuovo titolo e un nuovo autore alla voce senza utilizzare prima l'attributo gd:fields per rimuoverli.

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:edtag="EksPTg1Bfyp7IWA6WhJT">
  <title>A new title</title>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>darcy@gmail.com</email>
  </author>
</entry>

Poiché la rappresentazione parziale della voce non ha un attributo gd:fields, i campi non vengono rimossi. Tuttavia, i nuovi valori per gli elementi <title> e <author> vengono uniti alla risorsa di destinazione.

  • Poiché Atom consente un solo titolo per voce, il nuovo titolo sovrascrive il valore esistente. 
  • Poiché Atom consente più autori per voce, il nuovo autore viene aggiunto all'elenco di elementi dell'autore già presenti nella risorsa di destinazione.

    Nota: non tutte le API sono conformi allo standard Atom. Ad esempio, alcune API consentono un solo elemento <author> per voce; altre ereditano l'autore della voce dal livello del feed, rendendo il campo di sola lettura.

Dopo aver elaborato una richiesta PATCH valida, il server restituisce un codice di stato HTTP 200 e una copia della rappresentazione completa della voce aggiornata.

Se preferisci che il server restituisca solo determinati elementi o attributi, puoi utilizzare il parametro di ricerca fields con PATCH per richiedere una risposta parziale.

Risorse aggiuntive

Potrebbero esserti utili i seguenti documenti di terze parti:

Torna all'inizio