Questa pagina è stata tradotta dall'API Cloud Translation.

Riferimento 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 il protocollo dati di Google utilizzato da molte API di Google, incluse le informazioni sull'aspetto di una query, sui risultati e così via.

Per ulteriori informazioni sul protocollo dati di Google, consulta la pagina della panoramica della Guida per gli sviluppatori e il documento Protocollo di base.

Pubblico

Questo documento è destinato a chiunque voglia comprendere i dettagli del formato XML e del protocollo utilizzati dalle API che implementano il protocollo dati di Google.

Se vuoi semplicemente scrivere codice che utilizza una di queste API, non è necessario conoscere questi dettagli, ma puoi utilizzare le librerie client specifiche per ogni linguaggio.

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 Google Data Protocol
programmazione mediante il protocollo senza utilizzare le librerie client 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 Google Data Protocol utilizzando qualsiasi linguaggio di programmazione che ti consenta di inviare richieste HTTP e analizzare risposte basate su XML.

Dettagli protocollo

Questa sezione descrive il formato dei documenti e la sintassi delle query di Google Data Protocol.

Formato del documento

Google Data Protocol e Atom condividono 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.

Atom è il formato predefinito per il protocollo Google Data Protocol. Per richiedere una risposta in un altro formato, utilizza il parametro di ricerca alt. Per saperne di più, consulta Richieste di query.

Nota: la maggior parte dei feed di Google Data Protocol in formato Atom utilizza lo spazio dei nomi Atom come spazio dei nomi predefinito specificando un attributo xmlns nell'elemento del feed, come mostrato negli esempi forniti in Nozioni di base sul protocollo. Pertanto, negli esempi in questo documento non è specificato atom: per gli elementi in un feed in formato Atom.

Le seguenti tabelle mostrano la rappresentazione Atom degli elementi dello schema. Tutti i dati non menzionati in queste tabelle sono trattati come XML semplice. Se non diversamente indicato, gli elementi XML in una determinata colonna si trovano nello spazio dei nomi Atom.

Nota: 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 Google Data Protocol:

Elemento schema feed	Rappresentazione atomica
Titolo feed	`/feed/title`
ID feed	`/feed/id`
Link HTML del feed	`/feed/link[@rel="alternate"]`\ `[@type="text/html"]/@href`
Descrizione feed	`/feed/subtitle`
Lingua del feed	`/feed/@xml:lang`
Copyright del feed	`/feed/rights`
Autore feed	`/feed/author/name` `/feed/author/email` (Obbligatorio in alcuni casi; vedi la specifica Atom).
Data ultimo aggiornamento del feed	`/feed/updated` (formato RFC 3339)
Categoria feed	`/feed/category/@term`
Schema categoria feed	`/feed/category/@scheme`
Generatore feed	`/feed/generator` `/feed/generator/@uri`
Icona Feed	`/feed/icon`
Logo del feed	`/feed/logo`

La tabella seguente mostra gli elementi di un feed di risultati di ricerca di Google Data Protocol. Tieni presente che il protocollo 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
Numero di risultati di ricerca	`/feed/openSearch:totalResults`
Indice iniziale del risultato di ricerca	`/feed/openSearch:startIndex`
Numero di risultati di ricerca per pagina	`/feed/openSearch:itemsPerPage`

La tabella seguente mostra gli elementi di una voce del protocollo Google Data:

Elemento schema voce	Rappresentazione atomica
ID voce	`/feed/entry/id`
Titolo della voce	`/feed/entry/title`
Link voce	`/feed/entry/link`
Riepilogo voce	`/feed/entry/summary` (Obbligatorio in alcuni casi; vedi la specifica Atom).
Contenuti della voce	`/feed/entry/content` Se non è presente alcun elemento dei contenuti, la voce deve contenere almeno un elemento `<link rel="alternate">`.
Autore voce	`/feed/entry/author/name` `/feed/entry/author/email` (Obbligatorio in alcuni casi; vedi la specifica Atom).
Categoria voce	`/feed/entry/category/@term`
Schema categoria di voci	`/feed/entry/category/@scheme`
Data di pubblicazione dell'ingresso	`/feed/entry/published` (RFC 3339)
Data di aggiornamento voce	`/feed/entry/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 esegue una query su un servizio 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

Protocollo dati di Google supporta il GET HTTP condizionale. Le API che implementano il protocollo impostano l'intestazione della risposta Last-Modified in base al valore dell'elemento <atom:updated> nel feed o nella voce restituiti. 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 dal momento dell'eventuale modifica dell'evento, il servizio restituisce una risposta HTTP 304 (non modificata).

Le API che implementano il protocollo Google Data devono supportare le query 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
`alt`	Tipo di rappresentazione alternativo	Se non specifichi un parametro `alt`, il servizio restituisce un feed Atom. Equivale a `alt=atom`. `alt=rss` restituisce un feed di risultati RSS 2.0 (solo lettura). Quando richiedi dati a un servizio in formato RSS, questo fornisce un feed (o un'altra rappresentazione della risorsa) in formato RSS. Se non esiste una proprietà RSS equivalente per una determinata proprietà dell'API di dati, il servizio utilizza la proprietà Atom, etichettandola con uno spazio dei nomi appropriato per indicare che si tratta di un'estensione di RSS. `alt=json` restituisce una rappresentazione JSON del feed. Scopri di più `alt=json-in-script` richiede una risposta che aggrega il codice JSON in un tag script. Scopri di più `alt=atom-in-script` richiede una risposta Atom che include una stringa XML in un tag script. `alt=rss-in-script` richiede una risposta RSS che aggrega una stringa XML in un tag script. `alt=atom-service` richiede un documento di servizio Atom che descrive il feed.
`author`	Autore voce	Il servizio restituisce le voci in cui il nome dell'autore e/o l'indirizzo email corrispondono alla stringa di query.
`category`	Filtro query per categoria	Un modo alternativo per applicare un filtro di categoria. I due metodi sono equivalenti. Per inserire `OR` tra i termini, utilizza una barra verticale (\|), codificata come `%7C`. Ad esempio, `http://www.example.com/feeds?category=Fritz%7CLaurie` restituisce le voci che corrispondono a una delle categorie. Per inserire `AND` tra i termini, utilizza una virgola (,). Ad esempio: `http://www.example.com/feeds?category=Fritz,Laurie` restituisce le voci che corrispondono a entrambe le categorie.
`/-/category`	Filtro query per categoria	Elenca ogni categoria come se facesse parte dell'URI della risorsa, nel formato `/categoryname/`: si tratta di un'eccezione al consueto modulo `name=value`. Elenca tutte le categorie prima di eventuali altri parametri di ricerca. Aggiungi in anticipo la prima categoria con `/-/` per chiarire che si tratta di una categoria. Ad esempio, se il feed di Jo ha una categoria per le voci su Fritz, potresti richiedere queste voci in questo modo: `http://www.example.com/feeds/jo/-/Fritz`. Ciò consente all'implementazione di distinguere gli URI di query con priorità per le categorie da quelli delle risorse. Puoi eseguire query su più categorie elencando più parametri di categoria, separati da barre. Il servizio restituisce tutte le voci che corrispondono a tutte le categorie (ad esempio l'uso di `AND` tra i termini). Ad esempio: `http://www.example.com/feeds/jo/-/Fritz/Laurie` restituisce voci che corrispondono a entrambe le categorie. Per inserire `OR` tra i termini, utilizza una barra verticale (`\|`), codificata come `%7C`. Ad esempio, `http://www.example.com/feeds/jo/-/Fritz%7CLaurie` restituisce le voci che corrispondono a una delle categorie. Una voce corrisponde a una categoria specificata se la voce appartiene a una categoria con un termine o un'etichetta corrispondente, come definito nella specifica Atom. indicativamente, "termine" è la stringa interna utilizzata dal software per identificare la categoria, mentre "etichetta" è la stringa leggibile per l'utente presentata in un'interfaccia utente. Per escludere le voci che corrispondono a una determinata categoria, utilizza il modulo `/-categoryname/`. Per eseguire una query per una categoria che ha uno schema, ad esempio `<category scheme="urn:google.com" term="public"/>`, devi inserire lo schema tra parentesi graffe prima del nome della categoria. Ad esempio: `/{urn:google.com}public`. Se lo schema contiene una barra (`/`), la codifica dell'URL deve essere `%2F`. Per trovare una categoria senza schema, utilizza un paio di parentesi graffe vuote. Se non specifichi parentesi graffe, le categorie in qualsiasi schema corrisponderanno. Le funzioni precedenti possono essere combinate. Ad esempio: `/A%7C-{urn:google.com}B/-C` significa `(A OR (NOT B)) AND (NOT C)`.
ID articolo	ID di una voce specifica da recuperare	Se specifichi un ID voce, non puoi specificare altri parametri. La forma dell'ID voce è determinata dal servizio. A differenza della maggior parte degli altri parametri di ricerca, l'ID voce viene specificato come parte dell'URI, non come coppia nome=valore. Esempio: `http://www.example.com/feeds/jo/entry1`.
`fields`	Filtro risposta	Restituisce solo i campi richiesti, anziché la rappresentazione completa della risorsa. Ad esempio: http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit'])) Quando riceve questa richiesta, il server restituisce una risposta che contiene solo elementi di link e voci per il feed. Inoltre, gli elementi restituiti sono voci parziali che contengono solo relazioni ETag, ID, aggiornate e link. Il valore dei campi deve essere codificato nell'URL, come in tutti i valori dei parametri di ricerca. Per ulteriori informazioni, consulta la sezione Risposta parziale. Al momento, questo parametro è una funzionalità sperimentale.
`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.
`prettyprint`	Restituisce una risposta XML con imitazioni e interruzioni di riga	Se `prettyprint=true`, il codice XML restituito dal server sarà leggibile (valido). URL predefinito: `prettyprint=false`
`published-min`, `published-max`	Limiti alla data di pubblicazione della voce	Utilizza il formato timestamp RFC 3339. Ad esempio: `2005-08-09T10:57:00-08:00`. Il limite inferiore è incluso, mentre il limite superiore è esclusivo.
`q`	Stringa di query a testo intero	Quando crei una query, elenca i termini di ricerca separati da spazi nel formato `q=term1 term2 term3`. Come per tutti i valori dei parametri di ricerca, gli spazi devono essere codificati nell'URL. Il servizio restituisce tutte le voci che corrispondono a tutti i termini di ricerca (ad esempio l'utilizzo di `AND` tra i termini). Come la ricerca web di Google, un servizio cerca le parole complete (e le parole correlate con la stessa radice), non le sottostringhe. Per cercare una frase esatta, racchiudila tra virgolette: `q="exact phrase".` Per escludere le voci che corrispondono a un determinato termine, utilizza il modulo `q=-term`. La ricerca non è sensibile alle maiuscole. Esempio: per cercare tutte le voci che contengono la frase esatta "Elizabeth Bennet" e la parola "Darcy", ma non contengono la parola "Austen", utilizza la seguente query: `?q="Elizabeth Bennet" Darcy -Austen`
`start-index`	Indice basato su 1 del primo risultato da recuperare	Tieni presente che questo non è un meccanismo di cursore generale. Se invii prima una query con `?start-index=1&max-results=10` e poi ne invii un'altra con `?start-index=11&max-results=10`, il servizio non può garantire che i risultati siano equivalenti a `?start-index=1&max-results=20`, in quanto le operazioni di inserimento ed eliminazione potrebbero essere avvenute tra le due query.
`strict`	Controllo preciso dei parametri di ricerca	Imposta `strict=true` per verificare che tutti i parametri di ricerca siano riconosciuti dal servizio. Se non viene riconosciuto un parametro, verrà restituito un errore. URL predefinito: `strict=false`
`updated-min`, `updated-max`	Limiti applicati alla data di aggiornamento della voce	Utilizza il formato timestamp RFC 3339. Ad esempio: `2005-08-09T10:57:00-08:00`. Il limite inferiore è incluso, mentre il limite superiore è esclusivo. In alcuni casi, ad esempio utilizzando la versione 2.1 o una versione successiva dell'API Calendar Data, se viene specificato un valore di `updated-min` troppo lontano verrà restituito uno stato HTTP 410 (non più disponibile).

Informazioni sulle query per categoria

Abbiamo deciso di fornire un formato leggermente insolito per le query di categoria. Anziché richiedere una query simile alla seguente:

http://example.com/jo?category=Fritz&category=2006

abbiamo reso possibile l'utilizzo di:

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 le query per categoria siano tra le più comuni.

Lo svantaggio di questo approccio è che richiediamo di utilizzare /-/ in questo tipo di query di categoria, in modo che i servizi possano distinguere le query di categoria da altri URI della risorsa, come 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-index nella tabella della sezione Richieste di query.

Il feed e le voci della risposta Atom possono includere anche i seguenti elementi dell'API Atom e Data, nonché altri elementi 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 type dipende 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="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <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 gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'>
    <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 gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'>
    <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 delle API di dati.

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.
410 GONE	La cronologia delle modifiche richieste non è più disponibile sul server. Per ulteriori dettagli, consulta la documentazione specifica dei servizi.
500 ERRORE SERVER INTERNO	Errore interno. Questo è il codice predefinito utilizzato per tutti gli errori del server non riconosciuti.

Controllo delle versioni delle risorse (ETag)

A volte è necessario poter fare riferimento a una versione specifica di una determinata voce.

Ciò è importante in due casi, in particolare:

Eseguire un "recupero condizionale" in cui il client richiede una voce e il server la invia solo se è stata modificata dall'ultima volta che il client l'ha richiesta.
Assicurarsi che più client non sovrascrivano inavvertitamente le modifiche l'uno dell'altro. A questo scopo, le API di dati effettuano aggiornamenti ed eliminazioni non riuscite se il client specifica un identificatore della versione precedente per la voce.

Le API di dati di Google gestiscono entrambi i casi utilizzando ETag, una parte standard di HTTP.

Un ETag è un identificatore che specifica una determinata versione di una determinata voce. Il server allega un ETag agli elementi della voce e del feed che invia ai client. Quando cambia una voce o un feed, cambia anche il suo ETag.

Le API di dati di Google forniscono ETag in due posizioni: in un'intestazione HTTP ETag e in un attributo gd:etag di elementi <feed> e <entry>.

Nelle API di dati di Google, un ETag è in genere una stringa di lettere e numeri, che a volte include anche trattini e punti; in genere è racchiusa tra virgolette. Le virgolette fanno parte dell'ETag. Ad esempio, ecco un ETag di una voce dell'API di dati: "S0wCTlpIIip7ImA0X0QI".

Esistono due tipi di tag ETag: efficaci e deboli. Gli ETag efficaci identificano una versione specifica di una voce specifica e possono essere utilizzati per evitare di sovrascrivere le modifiche di altri client. Nel contesto delle API di dati di Google, i tag Eak deboli vengono utilizzati solo per il recupero condizionale. Un ETag debole inizia sempre con W/. Ad esempio: W/"D08FQn8-eil7ImA9WxZbFEw.".

Non tutte le API di dati di Google supportano ETag efficaci. In tal caso, i tag ETag efficaci vengono utilizzati solo per le voci; i tag ETag sui feed sono sempre deboli.

Ecco un esempio di feed (incluse alcune intestazioni HTTP) recuperato da un servizio che supporta i tag ETag efficaci:

GData-Version: 2.0
ETag: W/"C0QBRXcycSp7ImA9WxRVFUk."
...
<?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."'>
  ...
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    ...
  </entry>
</feed>

Le librerie client che supportano la versione 2 delle API di dati gestiscono gli ETag per te, in modo trasparente. Le informazioni che seguono riguardano i client che non utilizzano librerie client e per i lettori interessati a come viene gestito il controllo delle versioni a livello di protocollo.

Nota: per informazioni sul sistema di controllo delle versioni delle risorse utilizzato nella versione 1.0 delle API di dati, consulta la guida di riferimento 1.0.

Recupero condizionale

Se vuoi recuperare una voce recuperata in precedenza, puoi migliorare la tua efficienza comunicando al server di inviare la voce solo se è cambiata dall'ultima volta che l'hai recuperata.

Per eseguire questa operazione di recupero condizionale, invia una richiesta HTTP GET che includa un'intestazione HTTP If-None-Match. Nell'intestazione, specifica l'ETag della voce.

Ecco un esempio di intestazione If-None-Match:

If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."

Quando il server riceve questa richiesta, controlla se la voce richiesta ha lo stesso ETag dell'ETag specificato. Se i tag ETag corrispondono, la voce non è cambiata e il server restituisce un codice di stato HTTP 304 Not Modified.

Se gli ETag non corrispondono, la voce è stata modificata dall'ultima richiesta e il server restituisce la voce.

Aggiornamento delle voci

Il modo più semplice per evitare la sovrascrittura delle modifiche di un altro client è che il server verifichi che, quando il client invia una voce aggiornata, la versione della voce con cui il client ha iniziato sia la stessa versione attualmente archiviata dal server. Se un secondo client esegue un aggiornamento prima che il client esegua l'aggiornamento, quest'ultimo viene negato perché il client non basa più le modifiche sull'ultima versione.

Quando il tuo client recupera i dati da un servizio che supporta i tag ETag efficaci, ogni voce ha un ETag che funge da identificatore di versione univoco per la versione di quella voce.

Nota: l'aggiornamento tramite ETag funziona solo con ETag efficaci. Per i servizi che forniscono ETag deboli, tutti gli aggiornamenti hanno esito positivo, indipendentemente dal fatto che un altro utente abbia aggiornato la voce da quando l'hai recuperata; l'ultimo aggiornamento sovrascrive sempre qualsiasi altro aggiornamento precedente. Pertanto, non inviare ETag deboli durante l'aggiornamento o l'eliminazione, altrimenti riceverai un messaggio di errore.

Quindi, quando il tuo client invia un aggiornamento a un servizio strong-ETag, deve specificare la versione della voce che si sta aggiornando. Puoi farlo in due modi:

Utilizza un'intestazione HTTP If-Match.
Utilizza l'attributo gd:etag nell'elemento <atom:entry>.

Se possibile, consigliamo l'approccio If-Match.

Per aggiornare una voce utilizzando If-Match, inizia acquisendo la voce che stai aggiornando. Apporta le modifiche alla voce che preferisci, quindi crea una nuova richiesta PUT contenente la voce modificata. Per informazioni dettagliate sugli URL da utilizzare, consulta la documentazione specifica del servizio.

Prima di inviare l'PUT, aggiungi un'intestazione HTTP If-Match contenente l'ETag della voce originale:

If-Match: "S0wCTlpIIip7ImA0X0QI"

Quindi, invia la richiesta PUT.

Se l'aggiornamento va a buon fine, il server restituisce un codice di stato HTTP 200 OK e una copia della voce aggiornata.

Se l'aggiornamento non va a buon fine perché l'ETag specificato non corrisponde all'attuale ETag della voce (il che implica che la voce è stata modificata sul server dall'ultima volta che l'hai recuperata), il server restituisce un codice di stato HTTP 412 Precondition Failed.

Se non riesci a scrivere facilmente le intestazioni HTTP o hai qualche altro motivo per evitare di utilizzare l'intestazione If-Match, puoi utilizzare l'attributo gd:etag.

Se non invii un'intestazione If-Match, il server utilizza il valore dell'attributo gd:etag della voce aggiornata come valore If-Match implicito.

Per eseguire l'override del sistema di controllo delle versioni e aggiornare la voce indipendentemente dal fatto che un altro utente l'abbia aggiornata dopo il recupero, utilizza If-Match: * invece di specificare l'ETag nell'intestazione.

Per informazioni sui servizi che supportano i tag ETag efficaci, consulta la Guida alla migrazione.

Eliminazione di voci

Eliminare le voci che utilizzano ETag efficaci funziona in modo molto simile all'aggiornamento.

Per eliminare una voce con un ETag elevato, devi prima recuperare la voce che vuoi eliminare e poi inviare una richiesta DELETE all'URL di modifica della voce.

Se vuoi assicurarti di non eliminare una voce modificata da un altro client da quando l'hai recuperata, includi un'intestazione HTTP If-Match contenente il valore ETag della voce originale.

Se vuoi eseguire l'override del sistema di controllo delle versioni ed eliminare la voce indipendentemente dal fatto che un altro utente l'abbia aggiornata dopo il recupero, utilizza If-Match: * invece di specificare l'ETag nell'intestazione.

Se una voce non ha un ETag elevato, una richiesta DELETE ha sempre esito positivo.

Risposta parziale (sperimentale)

Per impostazione predefinita, il server restituisce la rappresentazione completa della risorsa di destinazione dopo l'elaborazione delle richieste. Risposta parziale ti consente di richiedere solo gli elementi o gli attributi di interesse, anziché la rappresentazione completa delle risorse. Ciò consente all'applicazione client di evitare trasferimenti, analisi e archiviazione di campi non necessari, in modo da poter utilizzare le risorse di rete, CPU e memoria in modo più efficiente.

Per sapere se è disponibile una risposta parziale per il prodotto che stai utilizzando, consulta la relativa documentazione dell'API.

Per richiedere una risposta parziale, utilizza il parametro di ricerca fields per specificare gli elementi o gli attributi da restituire. Ad esempio:

http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))

La risposta del server contiene solo elementi di link e voci per il feed; gli elementi di input contengono solo informazioni su ETag, ID, aggiornati e link. La sintassi dei parametri di ricerca di fields viene trattata nelle seguenti sezioni. Per maggiori dettagli sulla risposta, consulta l'articolo Gestire le risposte parziali.

Nota: puoi utilizzare il parametro di ricerca fields con qualsiasi richiesta che restituisca dati. Oltre a GET, sono inclusi POST e PUT (oltre a PATCH, che viene utilizzato per eseguire aggiornamenti parziali). Tuttavia, il parametro di ricerca fields influisce solo sui dati di risposta, non sui dati che devi fornire o su quali campi vengono aggiornati o creati.

Riepilogo della sintassi del parametro Campi

Il formato del valore del parametro di ricerca fields si basa sulla sintassi XPath, ma supporta solo un sottoinsieme di espressioni XPath valide. La sintassi supportata è riepilogata di seguito. Ulteriori esempi sono riportati nella sezione seguente.

Utilizza un elenco separato da virgole per selezionare più campi.
Utilizza a/b per selezionare un elemento b nidificato all'interno dell'elemento a; utilizza a/b/c per selezionare un elemento c nidificato all'interno di b.
Utilizza il prefisso '@' per identificare un attributo con il nome specificato; ometti il prefisso '@' per fare riferimento a un elemento.
Applica le condizioni dei campi per selezionare gli elementi che corrispondono a determinati criteri, inserendo le espressioni tra parentesi "[ ]" dopo l'elemento che vuoi limitare.
Ad esempio, fields=entry[author/name='Elizabeth'] restituisce solo le voci del feed di cui Elisabetta è l'autore.
Specifica i selettori dei campi per richiedere solo attributi o elementi secondari specifici, inserendo le espressioni tra parentesi "( )" dopo ogni elemento selezionato.
Ad esempio, fields=entry(id,author/email) restituisce solo l'ID e l'indirizzo email dell'autore per ogni voce del feed.
Puoi limitare le stringhe utilizzando virgolette doppie o singole.

Per uscire da una citazione doppia o singola, ripeti la citazione. Ad esempio, """Hello,"" he said" produce la stringa "Hello," he said, mentre '''Hello,'' he said' produce la stringa 'Hello,' he said.
Puoi utilizzare i caratteri jolly nelle selezioni dei campi.
Ad esempio, entry/gd:* seleziona tutti gli elementi secondari della voce nello spazio dei nomi gd, mentre entry/@gd:* seleziona gli attributi degli elementi secondari nello stesso spazio dei nomi.

Il parametro di ricerca fields funge da filtro di output. Ciò significa che la risposta parziale viene calcolata solo dopo l'elaborazione del resto della query. Ad esempio, se specifichi anche un parametro di ricerca max-results per indicare che vuoi 20 risultati per pagina, vengono generati i primi 20 risultati e da questa viene calcolata la risposta parziale. Se la specifica fields non corrisponde a nessuna delle prime 20 voci selezionate dalla query, viene restituito un feed vuoto e non vengono restituite le prime 20 voci corrispondenti.

Nota: non tentare di utilizzare le condizioni dei campi come selettori di query. Vale a dire che non tentare di recuperare un feed completo e applicare le condizioni dei campi per filtrare gli elementi di interesse da un set di dati molto grande. Quando possibile, utilizza altri parametri di ricerca, come start-index e max-results, per ridurre i risultati di ogni query in una dimensione gestibile. In caso contrario, gli aumenti delle prestazioni possibili con una risposta parziale potrebbero essere compensati dal grave degrado delle prestazioni causato da un uso improprio.

Formattare il valore dei campi dei campi

Le seguenti linee guida spiegano come creare il valore del parametro di ricerca fields. Ogni linea guida include esempi e fornisce descrizioni di come il valore del parametro influisce sulla risposta.

Nota: come per tutti i valori dei parametri di ricerca, il valore del parametro fields deve essere codificato tramite URL. Per una migliore leggibilità, negli esempi riportati di seguito viene omessa la codifica.

Identifica i campi da restituire o selezionali.

Il valore del parametro di ricerca fields è un elenco di elementi o attributi separati da virgole (collettivamente chiamati campi) e ogni campo viene specificato rispetto all'elemento principale della rappresentazione della risorsa. Pertanto, se recuperi un feed, i campi vengono specificati rispetto all'elemento <feed>, mentre se recuperi una singola voce, i campi vengono specificati in base all'elemento <entry>. Se l'elemento selezionato è (o fa parte) un elemento ricorrente nel feed, il servizio restituisce tutte le istanze di quell'elemento.

Ecco alcuni esempi a livello di feed:

Esempi	Effetto
`entry`	Restituisce tutti gli elementi `<entry>` e tutti gli elementi secondari di queste voci, ma non altri elementi secondari di `<feed>`.
`id,entry`	Restituisce sia il feed `<id>` che tutti gli elementi `<entry>`.
`entry/title`	Restituisce l'elemento `<title>` per tutte le voci del feed. Ogni volta che viene restituito un elemento nidificato, la risposta include i tag che racchiudono eventuali elementi principali . I tag principali non includono altri elementi o attributi secondari, a meno che non siano selezionati esplicitamente.
`entry/author/uri`	Restituisce solo l'elemento secondario `<uri>` dell'elemento `<author>` per tutte le voci del feed.
`entry/*:rating`	Restituisce solo gli elementi secondari con nome locale `rating` in qualsiasi spazio dei nomi per tutte le voci del feed.

Ecco alcuni esempi di offerte di lavoro:

Esempi	Effetto
`author`	Restituisce l'elemento secondario `<author>` della voce di destinazione.
`@gd:etag`	Restituisce l'attributo `etag` della voce di destinazione.
`author/uri`	Restituisce l'elemento secondario `<uri>` dell'elemento `<author>` per la voce di destinazione.
`media:group/media:*`	Restituisce tutti i sottocampi di `<media:group>` nello spazio dei nomi `media` per la voce di destinazione.

Limita la risposta ai campi selezionati che corrispondono a determinati criteri oppure utilizza le condizioni dei campi.

Per impostazione predefinita, se la richiesta specifica un elemento che si verifica più di una volta, la risposta parziale includerà tutte le istanze di quell'elemento. Tuttavia, puoi anche specificare che la risposta deve includere solo elementi con un determinato valore di attributo o elementi che soddisfano altre condizioni utilizzando la sintassi "[ ]", come mostrato negli esempi seguenti. Per ulteriori dettagli, consulta la sezione Sintassi delle condizioni dei campi.

Esempi	Effetto
`entry[link/@rel='edit']`	Restituisce tutte le voci del feed che contengono un elemento `<link>` con un valore di attributo `rel` di `'edit'`.
`entry/title[text()='Today']`	Restituisce tutti gli elementi `<title>` che si verificano nelle voci del feed se il contenuto è `'Today'`.
`entry/author[name='Jo']`	Restituisce tutti gli elementi `<author>` che si verificano nelle voci del feed se hanno un elemento secondario `<name>` con contenuti `'Jo'`.
`author[name='Jo']`	Restituisce l'elemento `<author>` nella voce di destinazione se ha un elemento secondario `<name>` con contenuti `'Jo'`.

Richiedi solo parti degli elementi selezionati o utilizza le selezioni secondarie campo.

Per impostazione predefinita, se la tua richiesta specifica elementi particolari, il servizio restituisce gli elementi nella loro interezza. Puoi specificare che la risposta debba includere solo determinati elementi secondari all'interno degli elementi selezionati. Per farlo, utilizza la sintassi di selezione secondaria "( )", come negli esempi riportati di seguito.

Esempi	Effetto
`entry/author(uri)`	Restituisce solo l'elemento secondario `<uri>` per gli autori nelle voci del feed.
`entry/author[name='Jo'](uri)`	Restituisce solo l'elemento secondario `<uri>` di `<author>` per qualsiasi voce il cui nome dell'autore è `'Jo'`.
`entry(link(@rel,@href))`	Restituisce solo i valori degli attributi `rel` e `href` per ogni elemento `<link>` nelle voci del feed.
`entry(title,link[@rel='edit'])`	Restituisce solo elementi `<title>` e `<link>` con attributi di modifica `rel` per ogni voce del feed.
`entry(title,author(uri)`	Restituisce entrambi gli elementi `<title>` e l'autore `<uri>` per ogni voce del feed.

Scopri di più sulla sintassi delle condizioni dei campi

Puoi utilizzare le condizioni dei campi con campi o sottocampi. Per poter essere inclusa nei risultati, la condizione deve restituire true.Se non è presente alcuna condizione, vengono inclusi tutti i campi del tipo selezionato.

Il valore di testo del campo selezionato viene utilizzato per i confronti. In questo contesto, se il campo è un elemento, il valore di testo è il suo contenuto; se il campo è un attributo, il valore di testo è il valore dell'attributo. Se il campo non ha un valore di testo, il confronto non riesce e il campo non viene incluso nei risultati.

La seguente tabella mostra gli operatori XPath supportati per le condizioni dei campi e fornisce alcuni esempi.

Operatore	Sintassi	Esempi
Confronto stringhe	`=` o `eq` `!=` o `ne`	Restituisce l'intera voce se contiene un elemento `<link>` con un attributo `rel` impostato su "`self'`": `entry[link/@rel='self']` Restituisce l'intera voce se contiene un elemento `<title>` con contenuti uguali alla stringa `'unknown'`: `entry[title eq 'unknown']` Restituisce l'intero elemento `<title>` se il contenuto non è `'unknown'`: `title[text() != 'unknown']`
Confronto logico	`and or not`	Restituisce qualsiasi link con un attributo `rel` impostato su `'self'` o `'edit'`: `link[@rel='self' or @rel='edit']` Restituisce ogni link che ha un attributo `rel` impostato su `'self'` e un attributo `type` impostato su `'application/atom+xml'`: `link[@rel='self' and @type='application/atom+xml']` Restituisce qualsiasi link che non ha un attributo `rel` con valore `'self'`: `link[not(@rel='self')]` Tieni presente che, come in XPath, `not` sembra una chiamata funzione.
Confronto numerico	`=` o `eq` `!=` o `ne` `>` o `gt` `>`= o `ge` `<` o `lt` `<=` o `le`	Restituisce qualsiasi elemento `<gd:rating>` con un attributo `value` che può essere trasformato nel numero intero 5: `gd:rating[@value=5]` Restituisce qualsiasi elemento `<gd:rating>` con un attributo `average` che può essere trasformato in un numero in virgola mobile maggiore di 4,3 : `gd:rating[@average gt 4.3]`
Confronto date	Utilizza gli operatori di confronto numerico, come mostrato negli esempi.	Per fare confronti tra date o date/ora, puoi trasmettere elementi, attributi o valori letterali di stringa in `xs:date` o `xs:dateTime`. Per `xs:dateTime`, il fuso orario predefinito è UTC, ma è meglio specificare un fuso orario in modo esplicito. Restituisce qualsiasi elemento `<yt:recorded>` che contiene una data dal 1° gennaio 2005: `yt:recorded[xs:date(text())>=xs:date('2005-01-01')]` Restituisce le voci che sono state aggiornate dopo l'orario specificato, specificato nel fuso orario UTC: `entry[xs:dateTime(updated)>xs:dateTime('2008-07-25T08:19:37.549Z')]`
Esistenza	Utilizza il nome dell'elemento o dell'attributo, come mostrato negli esempi.	Restituisce tutte le voci che contengono un link con l'attributo `rel`: `entry[link/@rel]` Restituisce tutti gli elementi `<gd:rating>` che hanno un attributo chiamato `value`: `entry/gd:rating[@value]`
Booleano	`true()false()`	I booleani possono essere utili durante il test per forzare l'applicazione delle condizioni dei campi in uno stato vero o falso. Restituisce tutti gli elementi `<link>`: `link[true()]`

Gestione delle risposte parziali

Dopo che un server che supporta la risposta parziale elabora una richiesta valida che include il parametro di ricerca fields, restituisce un codice di stato HTTP 200 OK insieme agli attributi o agli elementi richiesti. Se il parametro di ricerca fields contiene un errore o non è valido, il server restituisce un codice di stato HTTP 400 Bad Request.

L'elemento principale della risposta è <feed> o <entry>, a seconda dell'URI di destinazione. Il contenuto dell'elemento principale include solo i campi selezionati per quel feed o voce, insieme ai tag che racchiudono eventuali elementi principali.

Il valore del fields parametro di ricerca della richiesta può essere riportato anche in due modi:

L'elemento principale ha un attributo gd:fields che mostra il valore del parametro di ricerca fields specificato nella richiesta.
Se l'URI di destinazione è un feed, ogni voce modificabile ha un attributo gd:fields che mostra la porzione di selezione fields applicabile.

Nota: per vedere questi valori di attributo gd:fields nella risposta parziale, devi includerli nella specifica del parametro di ricerca fields. Puoi farlo in modo esplicito utilizzando @gd:fields o utilizzando la @gd:* più generale, che include anche informazioni sull'ETag.

La seguente query di esempio chiede al server di restituire un documento che contiene solo gli attributi nello spazio dei nomi gd (sia a livello di feed che a livello di voce), nonché l'ID, il titolo e il link di modifica di ogni voce del feed:

http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])

Il server restituisce la seguente risposta parziale e un codice di stato HTTP 200 Successful:

<?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/"DEAEQH47eCp7IWA9WxBVGUo."'
    gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
  <id>http://example.com/myFeed</id>
  <entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <title>This year</title>
  </entry>
  <entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/2/'/>
    <title>Last year</title>
  </entry>
  <entry d:etag='"EksPQAxHeCp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/3/'/>
    <title>Today</title>
  </entry>
</feed>

Se i campi selezionati non corrispondono, il servizio restituisce comunque un codice di stato HTTP 200 Successful, ma la risposta parziale è un feed vuoto:

<?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/"DEAEQH47eCp7IWA9WxBVGUo."'
  gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
</feed>

Aggiornamento parziale (sperimentale)

I prodotti Google che supportano la risposta parziale e le risorse modificabili consentono anche di utilizzare l'aggiornamento parziale. Con l'aggiornamento parziale, invii solo i campi che vuoi aggiornare, anziché inviare una versione modificata della rappresentazione completa della risorsa. Ciò consente all'applicazione client di essere più efficiente durante gli aggiornamenti e l'utilizzo di una risposta parziale per recuperare i dati.

Invece di utilizzare PUT, tuttavia, devi utilizzare una richiesta PATCH quando esegui un aggiornamento parziale. La semantica di PATCH è abbastanza potente da consentirti di aggiungere, sostituire ed eliminare campi specifici per una determinata voce, tutti con un'unica richiesta.

Per sapere se è disponibile un aggiornamento parziale del prodotto che stai usando, fai riferimento alla documentazione specifica del prodotto.

Inviare una richiesta di aggiornamento parziale

Per inviare una richiesta di aggiornamento parziale, devi inviare una richiesta HTTP PATCH allo stesso URL che utilizzeresti normalmente con PUT per aggiornare la risorsa. Il corpo della richiesta PATCH è un elemento <entry> parziale che specifica i campi da aggiungere o modificare. L'attributo gd:fields della voce indica i campi che vuoi eliminare.

Il server elabora PATCH richieste in un ordine specifico:

Rimuove innanzitutto dalla rappresentazione delle risorse i campi specificati dall'attributo gd:fields.
La sintassi dell'attributo gd:fields è uguale a quella del parametro di ricerca fields utilizzato per richiedere una risposta parziale. Per ulteriori dettagli, consulta la pagina Sintassi supportata.
Viene quindi unito alla rappresentazione risorsa esistente dei dati forniti nel corpo della richiesta.
Per ulteriori dettagli su come i dati vengono uniti, consulta la sezione Aggiungere o aggiornare i campi di seguito.

Nota: poiché il corpo di una richiesta PATCH non è in genere conforme al formato di syndication Atom, il valore di Content-Type che utilizzi con una richiesta PATCH è application/xml.

Ecco un esempio di richiesta di aggiornamento parziale:

PATCH /myFeed/1/1/
Content-Type: application/xml

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

Questa richiesta PATCH apporta le seguenti modifiche alla rappresentazione della risorsa archiviata sul server per la voce dell'URI di destinazione:

Rimuove l'elemento <description>.
Aggiorna l'elemento <title>.

Semantica di una richiesta di aggiornamento parziale

Le istruzioni riportate di seguito spiegano come configurare la richiesta PATCH di eliminare, aggiungere o aggiornare campi specifici all'interno di una voce. Una singola richiesta PATCH può eseguire qualsiasi combinazione di queste operazioni.

Eliminazione dei campi in corso. Utilizza l'attributo gd:fields dell'elemento <entry> per identificare tutti i campi che vuoi eliminare dalla risorsa. La seguente richiesta di esempio elimina il titolo e il riepilogo associati a una voce. Tuttavia, la richiesta non aggiunge o aggiorna altri dati relativi alla voce.
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='title,summary'/>
```
Aggiunta o aggiornamento di campi. Utilizza il corpo dell'elemento <entry> per specificare i dati che vuoi aggiungere o aggiornare per una risorsa. Questi campi vengono uniti ai dati esistenti per la risorsa, dopo che sono state eliminate, in base alle seguenti regole:
- Sono stati aggiunti campi non già presenti. Se i dati della risorsa non specificano già un valore per un campo, il campo viene aggiunto ai dati esistenti. Ad esempio, se una voce non ha un titolo e la richiesta PATCH contiene un elemento <title>, il nuovo titolo viene aggiunto alla voce.
- I campi già presenti vengono sostituiti o aggiunti. Il comportamento specifico per l'unione di campi già specificati nei dati delle risorse dipende dalle caratteristiche del campo:
  - I campi che non si ripetono vengono sostituiti. Se i dati della risorsa specificano già un valore per un elemento non ricorrente, il valore specificato nella richiesta PATCH sostituisce il valore esistente per quell'elemento. Nell'esempio riportato di seguito, il nuovo titolo sostituisce il titolo esistente.
```
PATCH /myFeed/1/1/
Content-Type: application/xml

  <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <title>New Title</title>
</entry>
```
    Di seguito è riportato un esempio più complesso. Per questo esempio, supponiamo che la voce possa avere un solo autore e che la risorsa di destinazione abbia già valori per il nome e l'indirizzo email dell'autore. Anche se l'elemento <author> ha due campi secondari, nei dati forniti è presente solo l'elemento <name>. Di conseguenza, solo il valore di quel campo viene sovrascritto. Il valore dell'elemento <email>, non presente nei dati forniti, rimane invariato.
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <author>
    <name>New Name</name>
  </author>
</entry>
```
  - I campi ripetuti vengono aggiunti. Se i dati della risorsa specificano già un valore per un elemento ricorrente, il nuovo elemento che fornisci viene aggiunto all'insieme di valori esistente.
    
    A volte potresti voler fare qualcosa di diverso dall'aggiunta di una nuova istanza di un elemento ricorrente. Ad esempio, potresti voler eseguire una delle seguenti operazioni:
    - Sostituisci un intero elenco di elementi ricorrenti. Puoi eliminare tutti i campi ricorrenti utilizzando l'attributo gd:fields (ad esempio gd:fields='ns:accessControl') e fornire un insieme completo di campi sostitutivi. Poiché tutti gli elementi esistenti vengono eliminati per primi, l'insieme di campi specificati non è in conflitto con i valori esistenti quando vengono aggiunti.
    - Sostituisci un valore in un insieme di valori esistenti per un elemento ricorrente. In questo caso, rimuovi semplicemente il singolo elemento definendo il valore gd:fields in modo abbastanza limitato da evitare di eliminare gli altri valori che vuoi conservare. Ad esempio, per rimuovere solo un controllo dell'accesso con action su embed, puoi utilizzare gd:fields='ns:accessControl[@action="embed"]'. Successivamente, fornisci il singolo campo con cui vuoi sostituirlo nel corpo dell'elemento <entry>:
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='ns:accessControl[@action="embed"]>
  <ns:accessControl action="embed" permission="allowed" />
</entry>
```

Gestire la risposta a un aggiornamento parziale

Dopo aver elaborato una richiesta di aggiornamento parziale valida, l'API restituisce un codice di risposta HTTP 200 OK. Per impostazione predefinita, il corpo della risposta è la voce completa che hai aggiornato. Il server aggiorna i valori ETag quando elabora correttamente una richiesta PATCH, come avviene con PUT.

Se una richiesta PATCH restituisce un nuovo stato della risorsa sintatticamente o semanticamente non valido, il server restituisce un codice di stato HTTP HTTP 400 Bad Request o 422 Unprocessable Entity e lo stato della risorsa rimane invariato. Ad esempio, se tenti di eliminare un campo obbligatorio e non fornisci un campo sostitutivo, il server restituisce un errore.

Nota: è importante comprendere in che modo i diversi campi siano correlati tra loro. Potrebbe essere possibile mettere una risorsa in uno stato incoerente aggiornando solo una parte dei valori interdipendenti. Ad esempio, è possibile aggiornare l'ora di inizio a un valore successivo rispetto a un'ora di fine. Anche se l'API restituisce un codice di errore, ti consigliamo di testare appieno questi tipi di condizioni per garantire la coerenza.

notazione alternativa quando PATCH non è supportata

Se il firewall non consente PATCH, esegui una richiesta HTTP POST e imposta l'intestazione di override su PATCH, come mostrato di seguito:

POST /myfeed/1/1/ X-HTTP-Method-Override: PATCH Content-Type: application/xml ...

Utilizzo di una risposta parziale con un aggiornamento parziale

Puoi utilizzare una risposta parziale come base per una successiva richiesta di aggiornamento parziale. In questo caso, specifica un parametro di ricerca fields che includa i link di modifica, oltre a @gd:*. Questo garantisce che la risposta parziale includa informazioni quali i valori degli attributi ETag e gd:fields, che sono importanti per le richieste successive.

Ecco un esempio che restituisce una risposta parziale che potresti utilizzare come base per un futuro aggiornamento parziale:

http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who

Il server risponde:

<?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='"E0UKRAREeCp7IWA6WhJT"'
    gd:fields="@gd;*,link[@rel='edit'](@href),gd:who">
  <link href='http://example.com/myFeed/1/1/'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='jo@gmail.com'/>
  <gd:who email='jane@gmail.com'/>
</entry>

Supponiamo che tu voglia rimuovere l'utente con l'indirizzo email 'jane@gmail.com', aggiungere un utente con l'indirizzo email 'will@gmail.com' e modificare l'indirizzo email per l'utente attualmente indicato come 'jo@gmail.com' in 'josy@gmail.com'.

Puoi apportare queste modifiche semplicemente iniziando con i risultati della risposta precedente, modificando solo i campi diversi e inviando la voce parziale modificata come corpo della richiesta PATCH. Per questo esempio, le modifiche necessarie sono:

Elimina <gd:who email='jane'/> dall'elenco di elementi fornito.
Aggiungi <gd:who email='will@gmail.com'/> all'elenco di elementi fornito.
Sostituisci <gd:who email='jo@gmail.com'/> con <gd:who email='josy@gmail.com'/>.

Di seguito è riportata la richiesta PATCH in base alla pesante risposta parziale:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who"
    gd:etag="FE8LQQJJeSp7IWA6WhVa">
  <link href='http://example.com/myFeed/1/1'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='josy@gmail.com'/>
  <gd:who email='will@gmail.com'/>
</entry>

Nota: questo approccio si basa sugli attributi gd:fields e gd:etag (se supportati) inclusi nella risposta parziale alla voce. Il corpo della voce parziale deve conservare tutti i campi e gli attributi presenti nella risposta parziale, tranne quelli che vuoi rimuovere esplicitamente. Puoi aggiornare qualsiasi campo esistente nel corpo con nuovi valori e puoi includere nuovi campi da aggiungere.

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 Google, deve utilizzare un sistema di autenticazione specifico di Google chiamato 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 dell'API Data.

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 dettagli su questi sistemi di autenticazione, consulta la Panoramica sull'autenticazione delle API di dati di Google o la documentazione 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 client non supporta nessuno di questi metodi, continuerà a utilizzare le API di dati, 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, PUT e DELETE
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
Sezione relativa agli eTag della specifica HTTP

Torna all'inizio