Esta página foi traduzida pela API Cloud Translation.

Referência do protocolo

Aviso: esta página é sobre as APIs mais antigas do Google, as APIs de dados do Google. Relevante apenas para as APIs listadas no diretório das APIs de dados do Google, muitas delas foram substituídas por APIs mais recentes. Para mais informações sobre uma nova API específica, consulte a documentação da nova API. Para informações sobre autorização de solicitações com uma API mais recente, consulte Autenticação e autorização de Contas do Google.

Este documento descreve o protocolo de dados do Google usado por muitas APIs do Google, incluindo informações sobre como é uma consulta, como são os resultados e assim por diante.

Para mais informações sobre o protocolo de dados do Google, consulte a página de visão geral do guia para desenvolvedores e o documento Princípios básicos do protocolo.

Público-alvo

Este documento é destinado a qualquer pessoa que queira entender os detalhes do formato e protocolo XML usados pelas APIs que implementam o protocolo de dados do Google.

Se você quer apenas criar um código que use uma dessas APIs, não é necessário saber esses detalhes. Em vez disso, use as bibliotecas de cliente específicas da linguagem.

Mas, se você quiser entender o protocolo, leia este documento. Por exemplo, talvez você queira ler este documento para realizar as seguintes tarefas:

avaliar a arquitetura do protocolo de dados do Google;
programação usando o protocolo sem usar as bibliotecas de cliente fornecidas
escrever uma biblioteca de cliente em uma nova linguagem

Neste documento, pressupomos que você tenha noções básicas sobre XML, namespaces, feeds distribuídos e solicitações GET, POST, PUT e DELETE em HTTP, além do conceito de "recurso" HTTP. Para mais informações, consulte a seção Recursos adicionais deste documento.

Este documento não depende de nenhuma linguagem de programação específica. Você pode enviar e receber mensagens do Protocolo de dados do Google usando qualquer linguagem de programação que permita emitir solicitações HTTP e analisar respostas baseadas em XML.

Detalhes do protocolo

Esta seção descreve a sintaxe de consulta e o formato dos documentos do protocolo de dados do Google.

Formato do documento

O protocolo de dados do Google e o Atom compartilham o mesmo modelo de dados básico: um contêiner que contém alguns dados globais e qualquer número de entradas. Para cada protocolo, o formato é definido por um esquema base, mas pode ser estendido com namespaces estrangeiros.

O Atom é o formato padrão do protocolo de dados do Google. Para solicitar uma resposta em outro formato, use o parâmetro de consulta alt. Para mais informações, consulte Solicitações de consulta.

Observação: a maioria dos feeds do protocolo de dados do Google no formato Atom usa o namespace Atom como o padrão especificando um atributo xmlns no elemento do feed, conforme mostrado nos exemplos em Princípios básicos do protocolo. Portanto, os exemplos neste documento não especificam explicitamente atom: para elementos em um feed no formato Atom.

As tabelas a seguir mostram a representação Atom dos elementos do esquema. Todos os dados não mencionados nessas tabelas são tratados como XML simples. A menos que indicado de outra forma, os elementos XML em uma determinada coluna estão no namespace Atom.

Observação:este resumo usa a notação XPath padrão: em particular, as barras mostram a hierarquia do elemento, e um @ indica um atributo de um elemento.

Em cada uma das tabelas a seguir, os itens destacados são obrigatórios.

A tabela a seguir mostra os elementos de um feed do protocolo de dados do Google:

Item do esquema do feed	Representação do Atom
Título do feed	`/feed/title`
ID de feed	`/feed/id`
Link HTML do feed	`/feed/link[@rel="alternate"]`\ `[@type="text/html"]/@href`
Descrição do feed	`/feed/subtitle`
Idioma do feed	`/feed/@xml:lang`
Direitos autorais do feed	`/feed/rights`
Autor do feed	`/feed/author/name` `/feed/author/email` Obrigatório em alguns casos. Consulte a especificação Atom.
Data da última atualização do feed	`/feed/updated` (formato RFC 3339)
Categoria do feed	`/feed/category/@term`
Esquema de categoria do feed	`/feed/category/@scheme`
Gerador de feeds	`/feed/generator` `/feed/generator/@uri`
Ícone de feed	`/feed/icon`
Logotipo do feed	`/feed/logo`

A tabela a seguir mostra os elementos de um feed de resultados da pesquisa do protocolo de dados do Google. O protocolo expõe alguns dos elementos de resposta do OpenSearch 1.1 nos feeds de resultados da pesquisa.

Item de esquema do feed de resultados da pesquisa	Representação do Atom
Número de resultados da pesquisa	`/feed/openSearch:totalResults`
Índice inicial dos resultados da pesquisa	`/feed/openSearch:startIndex`
Número de resultados da pesquisa por página	`/feed/openSearch:itemsPerPage`

A tabela a seguir mostra os elementos de uma entrada do protocolo de dados do Google:

Item do esquema de entrada	Representação do Atom
ID da entrada	`/feed/entry/id`
Título da entrada	`/feed/entry/title`
Link de entrada	`/feed/entry/link`
Resumo da entrada	`/feed/entry/summary` Obrigatório em alguns casos. Consulte a especificação Atom.
Conteúdo da inscrição	`/feed/entry/content` Se não houver elemento de conteúdo, a entrada precisará conter pelo menos um elemento `<link rel="alternate">`.
Autor da entrada	`/feed/entry/author/name` `/feed/entry/author/email` Obrigatório em alguns casos. Consulte a especificação Atom.
Categoria da entrada	`/feed/entry/category/@term`
Esquema de categoria de entrada	`/feed/entry/category/@scheme`
Data de publicação da entrada	`/feed/entry/published` (RFC 3339)
Data de atualização da entrada	`/feed/entry/updated` (RFC 3339)

Consultas

Esta seção descreve como usar o sistema de consulta.

Princípios de design do modelo de consulta

O modelo de consulta é intencionalmente muito simples. Os princípios básicos são:

As consultas são expressas como URIs HTTP, não como cabeçalhos HTTP ou como parte da carga útil. Uma vantagem dessa abordagem é que ela pode ser vinculada a uma consulta.
Os predicados têm como escopo um único item. Portanto, não é possível enviar uma consulta de correlação, como "encontrar todos os e-mails de pessoas que me enviaram pelo menos 10 e-mails hoje".
O conjunto de propriedades que as consultas podem prever é muito limitado; a maioria das consultas são simplesmente consultas de pesquisa de texto completo.
A ordem dos resultados depende da implementação.
O protocolo é naturalmente extensível. Se você quiser expor outros predicados ou classificações no seu serviço, poderá fazer isso facilmente com a introdução de novos parâmetros.

Solicitações de consulta

Um cliente emite um serviço do Google emitindo uma solicitação HTTP GET. O URI de consulta consiste no URI do recurso (chamado FeedURI no Atom) seguido dos parâmetros de consulta. A maioria dos parâmetros de consulta é representada como parâmetros de URL ?name=value[&...] tradicionais. Os parâmetros de categoria são tratados de forma diferente. Veja abaixo.

Por exemplo, se o FeedURI for http://www.example.com/feeds/jo, será possível enviar uma consulta com o seguinte URI:

http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z

O protocolo de dados do Google é compatível com a HTTP condicional GET. As APIs que implementam o protocolo definem o cabeçalho de resposta Last-Modified com base no valor do elemento <atom:updated> no feed ou na entrada retornada. Um cliente pode enviar esse valor de volta como o valor do cabeçalho de solicitação If-Modified-Since para evitar recuperar o conteúdo novamente caso ele não tenha sido alterado. Se o conteúdo não tiver mudado desde o horário "If-Modified-Since", o serviço retornará uma resposta HTTP 304 (não modificado).

As APIs que implementam o protocolo de dados do Google precisam ser compatíveis com consultas alt. A compatibilidade com outros parâmetros é opcional. Transmitir um parâmetro padrão não compreendido por um determinado serviço resulta em uma resposta 403 Forbidden. Transmitir um parâmetro não padrão sem suporte resulta em uma resposta 400 Bad Request. Para informações sobre outros códigos de status, consulte a seção Códigos de status HTTP deste documento.

Os parâmetros de consulta padrão são resumidos na tabela a seguir. Todos os valores de parâmetros precisam ser codificados no URL.

Parâmetro	Significado	Observações
`alt`	Tipo de representação alternativo	Se você não especificar um parâmetro `alt`, o serviço retornará um feed do Atom. Isso equivale a `alt=atom`. `alt=rss` retorna um feed de resultados RSS 2.0 (somente para leitura). Quando você solicita dados de um serviço no formato RSS, o serviço fornece um feed (ou outra representação do recurso) nesse formato. Se não houver uma propriedade RSS equivalente para uma determinada propriedade da API Data, o serviço usará a propriedade Atom, rotulando-a com um namespace apropriado para indicar que é uma extensão do RSS. `alt=json` retorna uma representação JSON do feed. Mais informações `alt=json-in-script`: solicita uma resposta que envolve o JSON em uma tag de script. Mais informações `alt=atom-in-script` Solicita uma resposta do Atom que encapsula uma string XML em uma tag de script. `alt=rss-in-script`: solicita uma resposta RSS que envolve uma string XML em uma tag de script. `alt=atom-service` Solicita um documento de serviço do Atom que descreve o feed.
`author`	Autor da entrada	O serviço retorna entradas em que o nome do autor e/ou o endereço de e-mail correspondem à string de consulta.
`category`	Filtro de consulta de categoria	Uma forma alternativa de realizar um filtro de categoria. Os dois métodos são equivalentes. Para fazer uma `OR` entre termos, use uma barra vertical (\|), codificada em URL como `%7C`. Por exemplo: `http://www.example.com/feeds?category=Fritz%7CLaurie` retorna entradas que correspondem a qualquer uma das categorias. Para fazer uma `AND` entre termos, use uma vírgula (,). Por exemplo: `http://www.example.com/feeds?category=Fritz,Laurie` retorna entradas que correspondem às duas categorias.
`/-/category`	Filtro de consulta de categoria	Liste cada categoria como se ela fizesse parte do URI do recurso, no formato `/categoryname/`. Essa é uma exceção ao `name=value` usual. Liste todas as categorias antes de qualquer outro parâmetro de consulta. Anteceda a primeira categoria com `/-/` para deixar claro que se trata de uma categoria. Por exemplo, se o feed do João tem uma categoria para entradas sobre o Fritz, é possível solicitar essas entradas como: `http://www.example.com/feeds/jo/-/Fritz`. Isso permite que a implementação diferencie URIs de consultas predefinidas por categoria e URIs de recursos. É possível consultar várias categorias listando vários parâmetros de categoria, separados por barras. O serviço retorna todas as entradas que correspondem a todas as categorias, como o `AND` entre os termos. Por exemplo: `http://www.example.com/feeds/jo/-/Fritz/Laurie` retorna entradas que correspondem às duas categorias. Para fazer uma `OR` entre termos, use uma barra vertical (`\|`), codificada em URL como `%7C`. Por exemplo: `http://www.example.com/feeds/jo/-/Fritz%7CLaurie` retorna entradas que correspondem a qualquer uma das categorias. Uma entrada corresponde a uma categoria especificada se estiver em uma categoria que tem um termo ou rótulo correspondente, conforme definido na especificação Atom. Aproximadamente, o "termo" é a string interna usada pelo software para identificar a categoria, enquanto o "rótulo" é a string legível apresentada a um usuário em uma interface do usuário. Para excluir entradas que correspondam a uma determinada categoria, use o formulário `/-categoryname/`. Para consultar uma categoria que tenha um esquema, como `<category scheme="urn:google.com" term="public"/>`, coloque o esquema entre chaves antes do nome da categoria. Por exemplo, `/{urn:google.com}public`. Se o esquema contiver uma barra (`/`), ele precisará ser codificado para URL como `%2F`. Para corresponder a uma categoria que não tem esquema, use um par de chaves vazias. Se você não especificar chaves, as categorias de qualquer esquema serão correspondentes. Os recursos acima podem ser combinados. Por exemplo: `/A%7C-{urn:google.com}B/-C` significa `(A OR (NOT B)) AND (NOT C)`.
ID da entrada	ID de uma entrada específica a ser recuperada	Se você especificar um ID de entrada, não poderá especificar outros parâmetros. O formulário do ID de entrada é determinado pelo serviço. Diferentemente da maioria dos outros parâmetros de consulta, o ID de entrada é especificado como parte do URI, e não como um par nome=valor. Exemplo: `http://www.example.com/feeds/jo/entry1`.
`fields`	Filtro de respostas	Retorna apenas os campos solicitados, e não a representação completa do recurso. Por exemplo: http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit'])) Quando recebe essa solicitação, o servidor retorna uma resposta que contém apenas elementos de link e entrada para o feed. Além disso, os elementos de entrada retornados são entradas parciais que contêm apenas relações de ETag, ID, atualização e vinculação de links. O valor dos campos precisa ser codificado por URL, assim como todos os valores de parâmetro de consulta. Para mais informações, consulte a seção Resposta parcial. Este parâmetro é um recurso experimental.
`max-results`	Número máximo de resultados a serem recuperados	Para qualquer serviço que tenha um valor `max-results` padrão (para limitar o tamanho padrão do feed), você pode especificar um número muito grande se quiser receber o feed inteiro.
`prettyprint`	Retorna uma resposta XML com identificações e quebras de linha.	Se `prettyprint=true`, o XML retornado pelo servidor será legível (bem impresso). Padrão: `prettyprint=false`
`published-min`, `published-max`	Limites na data de publicação de entrada	Use o formato de carimbo de data/hora RFC 3339. Por exemplo, `2005-08-09T10:57:00-08:00`. O limite inferior é inclusivo, enquanto o limite superior é exclusivo.
`q`	String de consulta de texto completo	Ao criar uma consulta, liste os termos de pesquisa separados por espaços no formato `q=term1 term2 term3`. Assim como todos os valores de parâmetro de consulta, os espaços precisam ser codificados no URL. O serviço retorna todas as entradas que correspondem a todos os termos de pesquisa, por exemplo, usando `AND` entre os termos. Assim como a pesquisa na Web do Google, um serviço procura palavras completas (e palavras relacionadas com a mesma raiz), não substrings. Para pesquisar uma frase exata, coloque a frase entre aspas: `q="exact phrase".` Para excluir entradas que correspondam a um determinado termo, use o formulário `q=-term`. A pesquisa não diferencia maiúsculas de minúsculas. Exemplo: para pesquisar todas as entradas que contenham a frase exata "Elizabeth Bennet" e a palavra "Darcy", mas que não contém a palavra "Austen", use a seguinte consulta: `?q="Elizabeth Bennet" Darcy -Austen`
`start-index`	Índice com base em 1 do primeiro resultado a ser recuperado	Esse não é um mecanismo de cursor geral. Se você enviar uma consulta com `?start-index=1&max-results=10` e depois outra com `?start-index=11&max-results=10`, o serviço não vai poder garantir que os resultados sejam equivalentes a `?start-index=1&max-results=20`, porque as inserções e exclusões podem ter ocorrido entre as duas consultas.
`strict`	Verificação rigorosa de parâmetros de consulta	Defina `strict=true` para verificar se cada um dos seus parâmetros de consulta é reconhecido pelo serviço. Um erro será retornado se um parâmetro não for reconhecido. Padrão: `strict=false`
`updated-min`, `updated-max`	Limites na data de atualização da entrada	Use o formato de carimbo de data/hora RFC 3339. Por exemplo, `2005-08-09T10:57:00-08:00`. O limite inferior é inclusivo, enquanto o limite superior é exclusivo. Em alguns casos, como no uso da v2.1 ou mais recente da API Data Data, especificar um `updated-min` muito antigo fará com que um status HTTP 410 (desaparecido) seja retornado.

Sobre as consultas de categoria

Decidimos disponibilizar um formato um pouco incomum para consultas de categoria. Em vez de exigir uma consulta como esta:

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

agora é possível usar:

http://example.com/jo/-/Fritz/2006

Essa abordagem identifica um recurso sem usar parâmetros de consulta e produz URIs mais limpos. Escolhemos essa abordagem para as categorias porque acreditamos que as consultas de categoria estarão entre as consultas mais comuns.

A desvantagem dessa abordagem é que você precisa usar /-/ nesse tipo de consultas de categoria para que os serviços possam distinguir consultas de categoria de outros URIs de recurso, como http://example.com/jo/MyPost/comments.

Respostas da consulta

As consultas retornam um feed Atom, uma entrada Atom ou um feed RSS, dependendo dos parâmetros de solicitação.

Os resultados da consulta contêm os seguintes elementos do OpenSearch diretamente no elemento <feed> ou <channel> (dependendo se os resultados são Atom ou RSS):

openSearch:totalResults: O número total de resultados da pesquisa para a consulta (nem todos estão presentes no feed de resultados).
openSearch:startIndex: O índice com base em 1 do primeiro resultado.
openSearch:itemsPerPage: É o número máximo de itens que aparecem em uma página. Isso permite que os clientes gerem links diretos para qualquer conjunto de páginas subsequentes. No entanto, para ver possíveis armadilhas no uso desse número, consulte a observação sobre start-index na tabela, na seção Solicitações de consulta.

O feed de resposta e as entradas do Atom também podem incluir qualquer um dos seguintes elementos da Atom e da API Data (além de outros listados na especificação Atom):

<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>: Especifica o URI em que o feed Atom completo pode ser recuperado.
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>: Especifica o PostURI do feed Atom (em que novas entradas podem ser postadas).
<link rel="self" type="..." href="..."/>: Contém o URI desse recurso. O valor do atributo type depende do formato solicitado. Se nenhum dado mudar, enviar outro GET para esse URI vai retornar a mesma resposta.
<link rel="previous" type="application/atom+xml" href="..."/>: Especifica o URI da parte anterior desse conjunto de resultados da consulta, se ele for dividido.
<link rel="next" type="application/atom+xml" href="..."/>: Especifica o URI da próxima parte desse conjunto de resultados da consulta, se ele for fragmentado.
<link rel="edit" type="application/atom+xml" href="..."/>: Especifica o EditURI da entrada do Atom (para onde você envia uma entrada atualizada).

Veja um exemplo de corpo de resposta em resposta a uma consulta de pesquisa:

<?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 o feed solicitado estiver no formato Atom, se nenhum parâmetro de consulta for especificado e se o resultado não contiver todas as entradas, o seguinte elemento será inserido no feed de nível superior: <link rel="next" type="application/atom+xml" href="..."/>. Ela aponta para um feed que contém o próximo conjunto de entradas. Os conjuntos subsequentes contêm um elemento <link rel="previous" type="application/atom+xml" href="..."/> correspondente. Ao seguir todos os próximos links, um cliente pode recuperar todas as entradas de um feed.

Códigos de status HTTP

A tabela a seguir descreve o significado de vários códigos de status HTTP no contexto das APIs de dados.

Código	Explicação
200 OK	Sem erro.
201 CRIADO	O recurso foi criado.
304 NÃO MODIFICADO	O recurso não foi alterado desde o tempo especificado no cabeçalho "If-Modified-Since" da solicitação.
400 SOLICITAÇÃO RUIM	URI ou cabeçalho de solicitação inválido ou parâmetro não padrão não suportado.
401 NÃO AUTORIZADO	É necessária autorização.
403 PROIBIDO	Parâmetro padrão incompatível ou falha na autenticação ou autorização.
404 NÃO ENCONTRADO	Recurso (como um feed ou entrada) não encontrado.
409 CONFLITO	O número da versão especificada não corresponde ao número da versão mais recente do recurso.
410 CONCLUÍDO	O histórico de alterações solicitado não está mais disponível no servidor. Consulte a documentação específica do serviço para mais detalhes.
500 ERRO INTERNO DO SERVIDOR	Erro interno. Esse é o código padrão usado para todos os erros de servidor não reconhecidos.

Controle de versão de recurso (ETags)

Às vezes, você precisa consultar uma versão específica de uma entrada específica.

Isso é importante em dois casos específicos:

Fazer uma "recuperação condicional", em que o cliente solicita uma entrada e o servidor só a envia se ela tiver mudado desde a última vez que o cliente a solicitou.
Garantir que vários clientes não substituam acidentalmente as alterações uns dos outros. As APIs de dados fazem isso com atualizações e exclusões se o cliente especificar um identificador de versão antigo para a entrada.

As APIs de dados do Google tratam esses dois casos usando ETags, uma parte padrão do HTTP.

Uma ETag é um identificador que especifica uma versão específica de uma entrada específica. O servidor anexa uma ETag aos elementos de entrada e feed que envia aos clientes. Quando uma entrada ou um feed são alterados, a ETag também é alterada.

As APIs de dados do Google fornecem ETags em dois lugares: em um cabeçalho HTTP ETag e em um atributo gd:etag dos elementos <feed> e <entry>.

Nas APIs de dados do Google, uma ETag geralmente é uma string de letras e números que às vezes inclui hifens e pontos. A string geralmente está entre aspas. As aspas são parte da ETag. Por exemplo, veja uma ETag de uma entrada da API Data: "S0wCTlpIIip7ImA0X0QI".

Há dois tipos de ETags: fortes e fracas. ETags fortes identificam uma versão específica de uma entrada específica e podem ser usadas para evitar a substituição de alterações de outros clientes. ETags fracas, no contexto das APIs de dados do Google, são usadas apenas para recuperação condicional. Uma ETag fraca sempre começa com W/. Por exemplo: W/"D08FQn8-eil7ImA9WxZbFEw."

Nem todas as APIs de dados do Google são compatíveis com ETags fortes. Para aquelas que os utilizam, as ETags fortes são usadas somente para entradas. As ETags em feeds são sempre fracas.

Veja um exemplo de feed (incluindo alguns dos cabeçalhos HTTP) recuperado de um serviço compatível com ETags fortes:

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>

As bibliotecas de cliente compatíveis com a versão 2 das APIs de dados gerenciam ETags por você de maneira transparente. As informações a seguir são destinadas a clientes que não usam bibliotecas de cliente e aos leitores interessados em como o controle de versões é processado no nível do protocolo.

Observação: para saber mais sobre o sistema de controle de versão do recurso usado na versão 1.0 das APIs Data, consulte o guia de referência 1.0.

Recuperação condicional

Se você quiser recuperar uma entrada recuperada anteriormente, melhore a eficiência informando ao servidor para enviar a entrada somente se ela tiver sido alterada desde a última vez em que você a recuperou.

Para fazer esse tipo de recuperação condicional, envie uma solicitação GET HTTP que inclui um cabeçalho HTTP If-None-Match. No cabeçalho, especifique a ETag da entrada.

Veja um exemplo de cabeçalho If-None-Match:

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

Quando o servidor recebe essa solicitação, ele verifica se a entrada solicitada tem a mesma ETag que a especificada. Se as ETags corresponderem, a entrada não mudou, e o servidor retornará um código de status HTTP 304 Not Modified.

Se as ETags não corresponderem, a entrada foi modificada desde a última solicitação, e o servidor retornará a entrada.

Atualizando entradas

A maneira mais fácil de evitar a substituição de alterações de outro cliente é que o servidor verifique se, quando o cliente envia uma entrada atualizada, a versão da entrada iniciada pelo cliente é igual à versão atual armazenada pelo servidor. Se um segundo cliente fizer uma atualização antes da do seu cliente, a atualização do cliente será negada, porque o cliente não está mais se baseando nas modificações da versão mais recente.

Quando o cliente recupera dados de um serviço que oferece suporte a ETags fortes, cada entrada tem uma ETag que funciona como um identificador de versão exclusivo dessa versão da entrada.

Observação: a atualização usando ETags só funciona com ETags fortes. Para serviços que fornecem ETags fracas, todas as atualizações são bem-sucedidas, independentemente de outra pessoa ter atualizado a entrada desde que você a recuperou. A atualização mais recente sempre substitui outras atualizações anteriores. Portanto, não envie ETags fracas ao atualizar ou excluir. Uma mensagem de erro será exibida se isso acontecer.

Portanto, quando seu cliente enviar uma atualização para um serviço ETags forte, ele precisará especificar qual versão da entrada está atualizando. Há duas maneiras de fazer isso:

Use um cabeçalho HTTP If-Match.
Use o atributo gd:etag no elemento <atom:entry>.

Recomendamos a abordagem If-Match sempre que possível.

Para atualizar uma entrada usando If-Match, comece comprando a entrada que você está atualizando. Faça as mudanças na entrada e crie uma nova solicitação PUT com a entrada modificada. Veja mais detalhes sobre os URLs a serem usados na documentação específica do serviço.

Antes de enviar o PUT, adicione um cabeçalho HTTP If-Match contendo a ETag da entrada original:

If-Match: "S0wCTlpIIip7ImA0X0QI"

Em seguida, envie a solicitação PUT.

Se a atualização for bem-sucedida, o servidor retornará um código de status HTTP 200 OK e uma cópia da entrada atualizada.

Se a atualização falhar porque a ETag especificada não corresponde à ETag atual na entrada (o que implica que a entrada mudou no servidor desde a última recuperação), o servidor retornará um código de status HTTP 412 Precondition Failed.

Se você não conseguir escrever cabeçalhos HTTP com facilidade ou tiver algum outro motivo para evitar o uso do cabeçalho If-Match, use o atributo gd:etag.

Se você não enviar um cabeçalho If-Match, o servidor usará o valor do atributo gd:etag da entrada atualizada como um valor If-Match implícito.

Para substituir o sistema de controle de versões e atualizar a entrada independentemente de alguém tê-la atualizado desde a recuperação, use If-Match: * em vez de especificar a ETag no cabeçalho.

Para saber mais sobre os serviços compatíveis com ETags fortes, consulte o Guia de migração.

Excluindo entradas

Excluir entradas que usam ETags fortes funciona de maneira parecida com a atualização delas.

Para excluir uma entrada que tenha uma ETag forte, primeiro recupere a entrada que quer excluir e, em seguida, envie uma solicitação DELETE para o URL de edição da entrada.

Para não excluir uma entrada que foi alterada por outro cliente desde que você a recuperou, inclua um cabeçalho HTTP If-Match que contenha o valor de ETag da entrada original.

Se você quiser substituir o sistema de controle de versão e excluir a entrada independentemente de alguém tê-lo atualizado desde a recuperação, use If-Match: * em vez de especificar a ETag no cabeçalho.

Se uma entrada não tiver uma ETag forte, uma solicitação DELETE sempre será bem-sucedida.

Resposta parcial (experimental)

Por padrão, o servidor retorna a representação completa do recurso de destino depois de processar as solicitações. A resposta parcial permite que você solicite apenas os elementos ou atributos de interesse, em vez da representação completa do recurso. Isso permite que o aplicativo cliente evite transferir, analisar e armazenar campos desnecessários para que ele possa usar os recursos de rede, CPU e memória com mais eficiência.

Para descobrir se uma resposta parcial está disponível para o produto que você está usando, consulte a documentação da API.

Para solicitar uma resposta parcial, use o parâmetro de consulta fields para especificar os elementos ou atributos que você quer retornar. Veja um exemplo:

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

A resposta do servidor contém apenas elementos de link e entrada do feed, e os elementos de entrada contêm apenas informações sobre ETag, ID, atualização e link. A sintaxe do parâmetro de consulta fields é abordada nas seções a seguir. Para mais detalhes sobre a resposta, consulte Como lidar com respostas parciais.

Observação: é possível usar o parâmetro de consulta fields com qualquer solicitação que retorne dados. Além de GET, isso inclui POST e PUT, bem como PATCH, que é usado para fazer atualizações parciais. No entanto, o parâmetro de consulta fields afeta somente os dados de resposta, e não os dados que você precisa fornecer ou quais campos são atualizados ou criados.

Resumo da sintaxe do parâmetro "Campos"

O formato do valor do parâmetro de consulta fields é baseado na sintaxe XPath, mas ele aceita apenas um subconjunto de expressões XPath válidas. Veja abaixo um resumo da sintaxe compatível e outros exemplos.

Use uma lista separada por vírgulas para selecionar vários campos.
Use a/b para selecionar um elemento b aninhado no elemento a. Use a/b/c para selecionar um elemento c aninhado em b.
Use o prefixo '@' para identificar um atributo com o nome informado e omita o prefixo '@' para se referir a um elemento.
Aplique condições de campo para selecionar elementos que correspondam a determinados critérios, colocando as expressões entre colchetes "[ ]" depois do elemento que você quer restringir.
Por exemplo, fields=entry[author/name='Elizabeth'] retorna apenas entradas de feed em que Elizabeth é a autora.
Especifique os subseletores de campo para solicitar somente atributos ou subelementos específicos. Basta colocar expressões entre parênteses "( )" após qualquer elemento selecionado.
Por exemplo, fields=entry(id,author/email) retorna apenas o ID e o e-mail do autor para cada entrada do feed.
É possível delimitar strings usando aspas duplas ou simples.

Para fazer escape de uma aspa dupla ou simples, repita-a. Por exemplo, """Hello,"" he said" produz a string "Hello," he said, e '''Hello,'' he said' produz a string 'Hello,' he said.
Você pode usar caracteres curinga em seleções de campo.
Por exemplo, entry/gd:* seleciona todos os elementos filhos de entrada no namespace gd, e entry/@gd:* seleciona atributos de elementos filhos no mesmo namespace.

O parâmetro de consulta fields funciona como um filtro de saída. Isso significa que a resposta parcial é calculada somente após o processamento do restante da consulta. Por exemplo, se você também especificar um parâmetro de consulta max-results para indicar que quer 20 resultados por página, os primeiros 20 resultados serão gerados e a resposta parcial será calculada com base nele. Se a especificação fields não corresponder a nenhuma das 20 primeiras entradas selecionadas pela consulta, você vai receber um feed vazio. Você não vai receber as primeiras 20 entradas correspondentes.

Observação: não tente usar condições de campo como seletores de consultas. Ou seja, não tente recuperar um feed completo e aplicar condições de campo para filtrar itens de interesse de um conjunto de dados muito grande. Sempre que possível, use outros parâmetros de consulta, como start-index e max-results, para reduzir os resultados a um tamanho gerenciável. Caso contrário, os ganhos de desempenho possíveis com a resposta parcial podem ser superados pela degradação grave de desempenho causada pelo uso inadequado.

Como formatar o valor de parâmetro dos campos

As diretrizes a seguir explicam como criar o valor do parâmetro de consulta fields. Cada diretriz inclui exemplos e apresenta descrições de como o valor do parâmetro afeta a resposta.

Observação: assim como com todos os valores de parâmetro de consulta, fields também precisa ter codificação de URL. Para facilitar a leitura, os exemplos abaixo omitem a codificação.

Identifique os campos a serem retornados ou faça seleções de campos.

O valor do parâmetro de consulta fields é uma lista separada por vírgulas de elementos ou atributos (chamados coletivamente de campos), e cada campo é especificado em relação ao elemento raiz da representação do recurso. Assim, se você estiver recuperando um feed, os campos serão especificados em relação ao elemento <feed>. Se estiver recuperando uma única entrada, os campos serão especificados em relação ao elemento <entry>. Se o elemento selecionado for (ou fizer parte) de um elemento repetido no feed, o serviço retornará todas as instâncias desse elemento.

Veja alguns exemplos no nível do feed:

Exemplos	Efeito
`entry`	Retorna todos os elementos `<entry>` e todos os subelementos dessas entradas, mas não outros elementos filhos de `<feed>`.
`id,entry`	Retorna o feed `<id>` e todos os elementos `<entry>`.
`entry/title`	Retorna o elemento `<title>` para todas as entradas de feed. Sempre que um elemento aninhado é retornado, a resposta inclui tags de inclusão para qualquer elemento pai . As tags mães não incluem outros elementos filhos ou atributos, a menos que também sejam selecionadas explicitamente.
`entry/author/uri`	Retorna apenas o subelemento `<uri>` do elemento `<author>` para todas as entradas de feed.
`entry/*:rating`	Retorna apenas subelementos com o nome local `rating` em qualquer namespace para todas as entradas de feed.

Veja alguns exemplos básicos:

Exemplos	Efeito
`author`	Retorna o elemento filho `<author>` da entrada de destino.
`@gd:etag`	Retorna o atributo `etag` da entrada de destino.
`author/uri`	Retorna o subelemento `<uri>` do elemento `<author>` para a entrada de destino.
`media:group/media:*`	Retorna todos os subcampos de `<media:group>` no namespace `media` da entrada de destino.

Restrinja a resposta a campos selecionados que correspondam a determinados critérios ou use condições de campo.

Por padrão, se a solicitação especificar um elemento que ocorre mais de uma vez, a resposta parcial incluirá todas as instâncias desse elemento. No entanto, também é possível especificar que a resposta inclua apenas elementos que tenham um determinado valor de atributo ou elementos que atendam a alguma outra condição usando a sintaxe "[ ]", conforme mostrado nos exemplos abaixo. Consulte a seção Sintaxe da condição de campo para mais detalhes.

Exemplos	Efeito
`entry[link/@rel='edit']`	Retorna todas as entradas de feed que contêm um elemento `<link>` com um valor de atributo `rel` de `'edit'`.
`entry/title[text()='Today']`	Retornará todos os elementos `<title>` que ocorrem nas entradas de feed, se o conteúdo for `'Today'`.
`entry/author[name='Jo']`	Retornará todos os elementos `<author>` que ocorrem nas entradas de feed se tiverem um subelemento `<name>` com conteúdo `'Jo'`.
`author[name='Jo']`	Retorna o elemento `<author>` na entrada de destino se tiver um subelemento `<name>` com conteúdo `'Jo'`.

Solicite apenas partes dos elementos selecionados ou use subseleções de campo.

Por padrão, se a solicitação especificar elementos específicos, o serviço retornará os elementos inteiros. É possível especificar que a resposta inclua somente determinados subelementos nos elementos selecionados. Para fazer isso, use a sintaxe de subseleção "( )", como nos exemplos abaixo.

Exemplos	Efeito
`entry/author(uri)`	Retorna apenas o subelemento `<uri>` para autores em entradas de feed.
`entry/author[name='Jo'](uri)`	Retorna apenas o subelemento `<uri>` de `<author>` para todas as entradas que tenham um nome de autor `'Jo'`.
`entry(link(@rel,@href))`	Retorna apenas os valores dos atributos `rel` e `href` para cada elemento `<link>` nas entradas de feed.
`entry(title,link[@rel='edit'])`	Retorna apenas elementos `<title>` e `<link>` com atributos de edição `rel` para cada entrada de feed.
`entry(title,author(uri)`	Retorna elementos `<title>` e elementos `<uri>` do autor para cada entrada de feed.

Mais informações sobre a sintaxe de condições de campo

É possível usar condições de campo com campos ou subcampos. A condição precisa ser avaliada como verdadeira para que o campo selecionado seja incluído nos resultados.Se não houver condição de campo, todos os campos do tipo selecionado serão incluídos.

O valor do texto do campo selecionado é usado para comparações. Nesse contexto, se o campo for um elemento, o valor do texto será o conteúdo dele. Se o campo for um atributo, o valor do texto será o valor do atributo. Se o campo não tiver um valor de texto, a comparação falhará e o campo não será incluído nos resultados.

A tabela a seguir mostra os operadores XPath compatíveis com as condições de campo e oferece alguns exemplos.

Operador	Sintaxe	Exemplos
Comparação de strings	`=` ou `eq` `!=` ou `ne`	Retorna a entrada inteira se contiver um elemento `<link>` com um atributo `rel` definido como "`self'`": `entry[link/@rel='self']` Retorna toda a entrada se ela tiver um elemento `<title>` com conteúdo igual à string `'unknown'`: `entry[title eq 'unknown']` Retorna todo o elemento `<title>` se o conteúdo não for `'unknown'`: `title[text() != 'unknown']`
Comparação lógica	`and or not`	Retorna qualquer link que tenha um atributo `rel` definido como `'self'` ou `'edit'`: `link[@rel='self' or @rel='edit']` Retorna qualquer link que tenha um atributo `rel` definido como `'self'` e um atributo `type` definido como `'application/atom+xml'`: `link[@rel='self' and @type='application/atom+xml']` Retorna qualquer link que não tenha um atributo `rel` com valor `'self'`: `link[not(@rel='self')]` Observe que, assim como em XPath, `not` se parece com uma chamada de função.
Comparação numérica	`=` ou `eq` `!=` ou `ne` `>` ou `gt` `>`= ou `ge` `<` ou `lt` `<=` ou `le`	Retorna qualquer elemento `<gd:rating>` com um atributo `value` que pode ser transformado no inteiro 5: `gd:rating[@value=5]` Retorna qualquer elemento `<gd:rating>` com um atributo `average` que pode ser transformado em um ponto flutuante maior que 4.3: `gd:rating[@average gt 4.3]`
Comparação de datas	Use operadores de comparação numérica, como mostrado nos exemplos.	Para fazer comparações de data ou data/hora, você pode transmitir elementos, atributos ou literais de string para `xs:date` ou `xs:dateTime`. Para `xs:dateTime`, o fuso horário padrão é UTC, mas é melhor especificar explicitamente um fuso horário. Retorna qualquer elemento `<yt:recorded>` que contenha uma data desde 1o de janeiro de 2005: `yt:recorded[xs:date(text())>=xs:date('2005-01-01')]` Retorna as entradas que foram atualizadas após o horário especificado no fuso horário UTC: `entry[xs:dateTime(updated)>xs:dateTime('2008-07-25T08:19:37.549Z')]`
Existência	Use o nome do elemento ou atributo como mostrado nos exemplos.	Retorna todas as entradas que contêm um link com o atributo `rel`: `entry[link/@rel]` Retorna todos os elementos `<gd:rating>` que têm um atributo com o nome `value`: `entry/gd:rating[@value]`
Booleano	`true()false()`	Os booleanos podem ser úteis durante os testes para forçar as condições de campo a um estado verdadeiro ou falso. Retorna qualquer elemento `<link>`: `link[true()]`

Como processar respostas parciais

Depois que um servidor que aceita resposta parcial processar uma solicitação válida que inclua o parâmetro de consulta fields, ele retornará um código de status HTTP 200 OK junto com os atributos ou elementos solicitados. Se o parâmetro de consulta fields tiver um erro ou for inválido, o servidor retornará um código de status HTTP 400 Bad Request.

O elemento raiz da resposta é <feed> ou <entry>, dependendo do URI de destino. O conteúdo do elemento raiz inclui apenas os campos selecionados para esse feed ou entrada, além das tags incluídas para todos os elementos pais.

O valor do parâmetro de consulta fields da solicitação pode ser retornado de duas maneiras:

O elemento raiz tem um atributo gd:fields que mostra o valor do parâmetro de consulta fields especificado na solicitação.
Se o URI de destino for um feed, cada entrada editável terá um atributo gd:fields que mostra a parte da seleção de fields que se aplica a ele.

Observação:para ver esses valores de atributo gd:fields na resposta parcial, inclua-os na especificação do parâmetro de consulta fields. Para fazer isso, use @gd:fields ou a @gd:* mais geral, que também inclui informações de ETag.

O exemplo de consulta a seguir pede ao servidor para retornar um documento que contenha apenas atributos no namespace gd (no nível do feed e da entrada), bem como o ID do feed, o título e o link de edição para cada entrada do feed:

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

O servidor retorna a seguinte resposta parcial com um código de status 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 os campos selecionados não corresponderem, o serviço retornará um código de status HTTP 200 Successful, mas a resposta parcial será um feed vazio:

<?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>

Atualização parcial (experimental)

Os produtos do Google compatíveis com a resposta parcial e os recursos editáveis também permitem que você use a atualização parcial. Com a atualização parcial, você envia apenas os campos que quer atualizar, em vez de enviar uma versão modificada da representação completa do recurso. Isso permite que o aplicativo cliente seja mais eficiente ao fazer atualizações e também ao usar a resposta parcial para recuperar dados.

No entanto, em vez de usar PUT, use uma solicitação PATCH ao fazer uma atualização parcial. A semântica de PATCH é eficiente o suficiente para permitir que você adicione, substitua e exclua campos específicos de uma entrada específica, tudo com uma única solicitação.

Para descobrir se uma atualização parcial está disponível para o produto que você está usando, consulte a documentação específica do produto.

Como enviar uma solicitação de atualização parcial

Para enviar uma solicitação de atualização parcial, envie uma solicitação PATCH HTTP ao mesmo URL que normalmente usaria com PUT para atualizar o recurso. O corpo da solicitação PATCH é um elemento <entry> parcial que especifica os campos que você quer adicionar ou modificar. O atributo gd:fields da entrada indica os campos que você quer excluir.

O servidor processa solicitações PATCH em uma ordem específica:

Primeiro, ele remove da representação de recurso os campos especificados pelo atributo gd:fields.
A sintaxe do atributo gd:fields é a mesma do parâmetro de consulta fields usado ao solicitar uma resposta parcial. Consulte Sintaxe com suporte para ver mais detalhes.
Em seguida, ele combina as representações existentes de recursos com os dados fornecidos no corpo da solicitação.
Veja mais detalhes sobre como os dados são mesclados em Como adicionar ou atualizar campos abaixo.

Observação:como o corpo de uma solicitação PATCH geralmente não está em conformidade com o formato de distribuição Atom, o Content-Type usado com uma solicitação PATCH é application/xml.

Veja um exemplo de uma solicitação de atualização parcial:

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>

Esta solicitação PATCH faz as seguintes mudanças na representação de recurso armazenada no servidor para a entrada do URI de destino:

Remove o elemento <description>.
Atualiza o elemento <title>.

Semântica de uma solicitação de atualização parcial

As instruções abaixo explicam como configurar sua solicitação PATCH para excluir, adicionar ou atualizar campos específicos de uma entrada. Uma única solicitação PATCH pode executar qualquer combinação dessas operações.

Exclusão de campos. Use o atributo gd:fields do elemento <entry> para identificar os campos que você quer excluir do recurso. O exemplo de solicitação a seguir exclui o título e o resumo associados a uma entrada. No entanto, a solicitação não adiciona nem atualiza outros dados para a entrada.
```
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'/>
```
Adicionar ou atualizar campos. Use o corpo do elemento <entry> para especificar os dados que você quer adicionar ou atualizar em um recurso. Esses campos são mesclados aos dados atuais do recurso após a exclusão, de acordo com as seguintes regras:
- Campos que ainda não estão presentes são adicionados. Se os dados do recurso ainda não especificarem um valor para um campo, ele será adicionado aos dados atuais. Por exemplo, se uma entrada não tiver um título e sua solicitação PATCH contiver um elemento <title>, o novo título vai ser adicionado à entrada.
- Os campos que já estiverem presentes serão substituídos ou anexados. O comportamento específico para mesclar campos que já estão especificados nos dados do recurso depende das características do campo:
  - Os campos não repetidos são substituídos. Se os dados do recurso já especificarem um valor para um elemento não repetido, o valor especificado na solicitação PATCH substituirá o valor atual do elemento. Por exemplo, no exemplo abaixo, o novo título substitui o título existente.
```
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>
```
    Veja a seguir um exemplo mais complexo. Para esse exemplo, suponha que a entrada possa ter apenas um autor e que o recurso de destino já tenha valores para o nome e o endereço de e-mail do autor. Embora o elemento <author> tenha dois campos filhos, apenas o <name> está presente nos dados fornecidos. Como resultado, somente o valor desse campo é substituído. O valor do elemento <email> que está ausente nos dados fornecidos permanece inalterado.
```
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>
```
  - Campos repetidos são anexados. Se os dados do recurso já especificarem um valor para um elemento repetido, o novo elemento fornecido vai ser adicionado ao conjunto de valores atual.
    
    Há momentos em que você quer fazer algo diferente de adicionar uma nova instância de um elemento repetido. Por exemplo, você pode querer seguir um destes procedimentos:
    - Substitua uma lista inteira de elementos repetidos. É possível excluir todos os campos repetidos usando o atributo gd:fields (gd:fields='ns:accessControl', por exemplo) e fornecendo um conjunto completo dos campos substitutos. Como todos os elementos atuais são excluídos primeiro, o conjunto de campos fornecido não entra em conflito com os valores existentes quando são anexados.
    - Substituir um valor em um conjunto de valores existentes por um elemento repetido. Nesse caso, basta remover o único elemento definindo o valor de gd:fields o suficiente para evitar a exclusão de outros valores que você quer manter. Por exemplo, para remover apenas um controle de acesso com um action de embed, você pode usar gd:fields='ns:accessControl[@action="embed"]'. Em seguida, forneça o único campo que você quer substituir no corpo do 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>
```

Como processar a resposta para uma atualização parcial

Depois de processar uma solicitação de atualização parcial válida, a API retorna um código de resposta HTTP 200 OK. Por padrão, o corpo da resposta é a entrada completa que você atualizou. O servidor atualiza os valores de ETag quando processa uma solicitação PATCH da mesma forma que faz com PUT.

Se uma solicitação PATCH resultar em um novo estado de recurso sintática ou semanticamente inválido, o servidor retornará um código de status HTTP HTTP 400 Bad Request ou 422 Unprocessable Entity e o estado do recurso permanecerá inalterado. Por exemplo, se você tentar excluir um campo obrigatório e não fornecer um substituto, o servidor retornará um erro.

Observação: é importante entender como campos diferentes se relacionam. É possível colocar um recurso em um estado inconsistente atualizando apenas parte dos valores mutuamente interdependentes. Por exemplo, é possível atualizar o horário de início para um valor posterior ao horário de término. Embora a API retorne um código de erro, recomendamos que você teste totalmente esses tipos de condições para garantir consistência.

Notação alternativa quando PATCH não for compatível

Se o firewall não permitir PATCH, faça uma solicitação HTTP POST e defina o cabeçalho de substituição como PATCH, conforme mostrado abaixo.

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

Usar resposta parcial com atualização parcial

Você pode usar uma resposta parcial como base para uma solicitação de atualização parcial subsequente. Se você fizer isso, especifique um parâmetro de consulta fields que inclua links de edição, bem como @gd:*. Isso garante que a resposta parcial inclua informações como os valores de atributo ETag e gd:fields, que são importantes para as próximas solicitações.

Veja um exemplo que retorna uma resposta parcial que pode ser usada como base para uma atualização parcial futura:

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

O servidor responde:

<?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>

Suponha que você queira remover o usuário com o e-mail 'jane@gmail.com', adicionar um usuário com o e-mail 'will@gmail.com' e mudar o e-mail do usuário atualmente listado como 'jo@gmail.com' para 'josy@gmail.com'.

É possível fazer essas alterações simplesmente começando com os resultados da resposta anterior, modificando apenas os campos que são diferentes e enviando a entrada parcial modificada como o corpo da solicitação PATCH. Para este exemplo, as modificações necessárias são:

Exclua <gd:who email='jane'/> da lista de elementos fornecidos.
Adicione <gd:who email='will@gmail.com'/> à lista de elementos fornecidos.
Substitua <gd:who email='jo@gmail.com'/> por <gd:who email='josy@gmail.com'/>.

A solicitação PATCH com base na resposta parcial exibida é mostrada abaixo:

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>

Observação: essa abordagem depende da inclusão dos atributos gd:fields e gd:etag na resposta parcial da entrada. O corpo da entrada parcial precisa reter todos os campos e atributos que estavam presentes na resposta parcial, exceto aqueles que você quer remover. É possível atualizar os campos existentes no corpo com novos valores e incluir novos campos que você quiser adicionar.

Autenticação

Quando um cliente tenta acessar um serviço, pode ser necessário fornecer as credenciais do usuário para demonstrar que o usuário tem autoridade para executar a ação em questão.

A abordagem que um cliente deve usar para autenticação depende do tipo de cliente:

Um aplicativo para computador precisa usar um sistema de autenticação específico do Google chamado Autenticação de conta para aplicativos instalados (também conhecido como "ClientLogin"). Clientes baseados na Web não devem usar esse sistema.
Um cliente baseado na Web, como um front-end de terceiros para um serviço do Google, deve usar um sistema de autenticação específico do Google chamado Proxy de autenticação de conta para aplicativos baseados na Web (também conhecido como "ALERT").

No sistema ClientLogin, o cliente da área de trabalho pede suas credenciais e as envia para o sistema de autenticação do Google.

Se a autenticação for bem-sucedida, o sistema retornará um token usado posteriormente pelo cliente (em um cabeçalho de autorização HTTP) quando enviar solicitações da API Data.

Se a autenticação falhar, o servidor retornará um código de status 403 Forbidden, além de um cabeçalho WWW-Authenticate contendo um desafio aplicável para a autenticação.

O sistema XPN funciona de maneira semelhante, mas em vez de solicitar as credenciais ao usuário, ele o conecta a um serviço do Google que solicita credenciais. Em seguida, o serviço retorna um token que pode ser usado pelo aplicativo da Web. A vantagem dessa abordagem é que o Google, em vez do front-end da Web, processa e armazena com segurança as credenciais do usuário.

Para ver detalhes sobre esses sistemas de autenticação, consulte a visão geral da autenticação das APIs de dados do Google ou a documentação da autenticação da Conta do Google.

Estado da sessão

Muitas implementações de lógica de negócios exigem aderência da sessão, acompanhando o estado da sessão do usuário.

O Google acompanha o estado da sessão de duas maneiras: usando cookies e usando um token que pode ser enviado como um parâmetro de consulta. Os dois métodos têm o mesmo efeito. Recomendamos que os clientes ofereçam suporte a um desses métodos de acompanhamento do estado da sessão (um deles é suficiente). Se um cliente não for compatível com nenhum desses métodos, ele ainda trabalhará com as APIs de dados, mas o desempenho poderá ser prejudicado se comparado aos clientes compatíveis. Especificamente, se um cliente não for compatível com esses métodos, todas as solicitações resultam em um redirecionamento, e cada solicitação (e quaisquer dados associados) é enviada ao servidor duas vezes, o que afeta o desempenho do cliente e do servidor.

As bibliotecas de cliente do Google lidam com o estado da sessão. Portanto, se você usar nossas bibliotecas, não precisará fazer nada para receber suporte ao estado da sessão.

Outros recursos

Os seguintes documentos de terceiros podem ser úteis:

Comparação entre Atom e RSS internamente
Visão geral do Atom da IBM
Extensões do Dublin Core para RSS
Definições de método do HTTP 1.1; especificação para GET, POST, PUT e DELETE
Definições de código de status HTTP 1.1
Como criar um protocolo REST
Como criar serviços da Web da maneira REST
Introdução técnica ao XML
Namespaces XML por exemplo
Seção ETag da especificação HTTP

Voltar ao início