Nozioni di base sul protocollo API di dati di Google

Questo documento descrive le nozioni di base del protocollo utilizzato dalle API di dati di Google, inclusi esempi di come viene visualizzata una query, come vengono visualizzati i 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 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.

Esempi

I seguenti esempi mostrano le semplici richieste del protocollo API Data che potresti inviare a un servizio generico 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 delle API di 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 visualizzarla, invia la seguente richiesta al server:

GET /myFeed

Il server risponde:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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.

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"?>
<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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <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 tutte le voci che corrispondono alla stringa di ricerca This. In questo caso ce n'è solo uno.

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <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>
</feed>

Aggiornamento di una voce

Per aggiornare una voce esistente, utilizza PUT, con l'URI di modifica della voce (fornito dal server nell'esempio precedente, nell'elemento <link rel="edit">).

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

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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <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'URI di modifica è cambiato; ora termina con "/2/" invece di "/1/". Il numero finale nell'URI di modifica è un numero di versione. Per ulteriori informazioni sulle versioni, consulta la sezione Contemporaneità ottimistica 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"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <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>

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

Nell'esempio seguente viene eliminata una voce:

DELETE /myFeed/1/2/

Il server risponde:

200 OK

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

GET /myFeed

Il server risponde:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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.

Risorse aggiuntive

Potrebbero esserti utili i seguenti documenti di terze parti:

Torna all'inizio