Noções básicas sobre protocolos

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 os princípios básicos do protocolo de dados do Google usado por muitas APIs do Google, incluindo exemplos de 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 do desenvolvedor e a Referência de protocolos.

Público-alvo

Este documento é destinado a qualquer pessoa que queira entender a ideia geral do formato e protocolo XML usados pelas APIs de dados do Google.

Mesmo que você queira apenas criar um código que usa as bibliotecas de cliente específicas da linguagem, é recomendável ler este documento para entender o que está acontecendo abaixo da camada de abstração da biblioteca de cliente.

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. Seu cliente pode interagir com o servidor usando qualquer linguagem de programação que permita emitir solicitações HTTP e analisar respostas baseadas em XML.

Se você quiser testar os exemplos deste documento sem escrever um código, os utilitários de linha de comando cURL ou Wget podem ser úteis. Para mais informações, consulte as páginas manuais desses utilitários ou o documento sobre Como usar cURL para interagir com os serviços que usam o protocolo de dados do Google.

Exemplos

Os exemplos a seguir mostram solicitações HTTP que você pode enviar para um serviço genérico usando o protocolo da API Google Data Protocol diretamente e os resultados que podem ser recebidos. Para ver exemplos de como enviar as solicitações usando várias linguagens de programação, consulte as amostras e as bibliotecas de cliente específicas de cada linguagem. Para saber como usar o protocolo de dados do Google com serviços específicos do Google, consulte a documentação específica do serviço.

Solicitar um feed ou outro recurso

Suponha que haja um feed chamado /myFeed e suponha que ele não contenha nenhuma entrada. Para vê-lo, envie a seguinte solicitação HTTP para o servidor:

GET /myFeed

O servidor responde:

200 OK

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

Embora o feed não contenha entradas, ele contém metadados, como um título e o nome de um autor. Ele também contém um identificador de versão, na forma de uma ETag HTTP.

Inserir uma nova entrada

Para criar uma nova entrada, envie uma solicitação POST e forneça a representação XML da nova entrada:

POST /myFeed

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

Observe que você não fornece os elementos <id>, <link> ou <updated> padrão do Atom. O servidor os cria em resposta à solicitação POST. Observe também que o autor de um feed não precisa ser a mesma pessoa que o autor da entrada.

O servidor responde:

201 CREATED

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

Como pesquisar uma string

Para fazer uma pesquisa de texto completo por uma string específica, ao usar um serviço compatível com pesquisas de texto completo, envie uma solicitação GET com o parâmetro q. Para mais informações sobre parâmetros de consulta, consulte Solicitações de consulta no documento de referência do protocolo.

GET /myFeed?q=This

O servidor responde com um feed contendo todas as entradas que correspondem à string de pesquisa This. Nesse caso, há apenas uma resposta.

200 OK

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

Como atualizar uma entrada

Para atualizar uma entrada atual, siga as etapas abaixo.

  1. Recupere a entrada que você quer atualizar.
  2. Modifique como quiser.
  3. Envie uma solicitação PUT, com a entrada atualizada no corpo da mensagem, para o URI de edição da entrada. O URI de edição aparece no exemplo anterior como o atributo href do elemento <link rel='edit'>.

Também é necessário especificar a ETag da entrada original para não substituir as alterações de outra pessoa.

No exemplo a seguir, estamos mudando o texto da entrada de seu valor antigo ("Esta é minha entrada") para um novo valor ("Esta é minha primeira entrada"):

PUT /myFeed/1/1/

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

O servidor responde:

200 OK

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

A ETag mudou. Para mais informações sobre as versões dos recursos, consulte a seção Controle de versões de recursos (ETags) do documento de referência de protocolo.

Para ver a nova entrada no contexto, solicite todo o recurso novamente:

GET /myFeed

O servidor responde:

200 OK

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

Observação: se o firewall não permitir PUT, faça uma POST HTTP e defina o cabeçalho de modificação do método da seguinte maneira:

X-HTTP-Method-Override: PUT

Como excluir uma entrada

Para excluir uma entrada existente, envie uma solicitação DELETE, usando o URI de edição da entrada (conforme fornecido pelo servidor no exemplo anterior).

Se o firewall não permitir DELETE, faça uma POST de HTTP e defina o cabeçalho de modificação do método da seguinte maneira:

X-HTTP-Method-Override: DELETE

Ao excluir uma entrada, é possível optar por fazer ou não uma exclusão condicional (somente se a entrada não tiver sido alterada desde a última vez que você a recuperou) ou uma exclusão incondicional. Para mais informações, consulte a seção Controle de versão de recursos (ETags) do documento de referência de protocolo. Para fazer uma exclusão incondicional, defina o seguinte cabeçalho HTTP:

If-Match: *

O exemplo a seguir exclui uma entrada (se os cabeçalhos estiverem definidos corretamente):

DELETE /myFeed/1/

O servidor responde:

200 OK

Faça outro GET para ver se o feed agora não contém entradas:

GET /myFeed

O servidor responde com um feed que contém apenas metadados:

200 OK

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

Se a exclusão falhar, o servidor vai responder com um código de erro. Para mais informações, consulte os códigos de status HTTP no documento de referência do protocolo.

Como solicitar entradas ou feeds parciais (experimental)

Ao contrário do exemplo simples de feed mostrado neste documento, na prática, os feeds podem ser bastante complexos. Com algumas APIs, é possível solicitar apenas os elementos ou atributos de interesse, em vez da representação completa do recurso. Ao evitar a recuperação e análise de dados desnecessários, é possível melhorar significativamente a eficiência do aplicativo cliente.

Para solicitar uma resposta parcial, use o parâmetro de consulta fields para especificar quais elementos ou atributos você quer retornar. Para mais informações, consulte Resposta parcial no documento de referência do protocolo.

O exemplo a seguir solicita apenas o ID do feed, o autor e o título de cada entrada.

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

O servidor responde:

200 OK

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

É possível usar o parâmetro fields com qualquer tipo de solicitação que retorne dados. Além de GET, isso inclui POST, PUT e PATCH, que são usados para fazer solicitações de atualização parcial.

Observação: o parâmetro de consulta fields controla apenas os dados enviados em resposta a uma solicitação. Ele não afeta os dados que você precisa fornecer no corpo de uma solicitação PUT, POST ou PATCH.

Veja abaixo exemplos de POST e PUT.

  • Ao fazer uma solicitação POST para uma resposta parcial, ainda é necessário fornecer os mesmos dados descritos em Como inserir uma nova entrada. O exemplo a seguir solicita uma resposta parcial que contém apenas o título da entrada recém-criada: 
    POST /myFeed?fields=title
      
...data...
    .

    O servidor responde:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
  • Ao fazer uma solicitação PUT para uma resposta parcial, você ainda precisa fornecer uma versão modificada da representação completa de recursos, conforme descrito em Como atualizar uma entrada. O exemplo a seguir solicita uma resposta parcial que contém apenas o novo valor de ETag da entrada modificada: 
    PUT /myFeed/1/1?fields=@gd:etag
  
...data...

    O servidor responde:

    200 OK

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

Atualizar campos específicos (experimental)

Se a API usada for compatível com resposta parcial e tiver campos editáveis, também será possível evitar o envio de dados desnecessários ao modificar uma entrada. A atualização parcial permite enviar dados apenas para os campos que você quer alterar.

Para usar a atualização parcial, envie uma solicitação PATCH para o mesmo URI de edição usado com PUT. Os dados enviados com PATCH precisam seguir determinadas convenções. No entanto, a semântica é flexível o suficiente para você substituir dados no recurso de destino, adicionar a ele ou até mesmo excluir dele, tudo com uma única solicitação.

Observação: assim como em PUT, é necessário especificar a ETag da entrada original para não sobrepor as alterações de outras pessoas.

Para mais informações sobre PATCH e a semântica relacionada, consulte Atualização parcial no documento de referência do protocolo.

Este exemplo mostra uma solicitação de atualização parcial que modifica o título da entrada:

PATCH /myFeed/1/1/

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

Quando o servidor recebe uma solicitação PATCH, primeiro ele remove todos os campos especificados pelo atributo gd:fields da entrada (se presente) e depois mescla todos os dados fornecidos no corpo da solicitação com o recurso de destino. Neste exemplo, o elemento de título é removido primeiro do recurso de destino, e o novo valor do título é mesclado. Essa solicitação substitui o título antigo pelo novo.

No entanto, a semântica de PATCH é para mesclar a representação parcial no recurso atual. Nem sempre é necessário remover um campo para atualizar o valor dele.

  • Se o campo existir apenas uma vez na entrada de destino, o campo na representação parcial substituirá o campo na entrada de destino.
  • Se o campo puder existir mais de uma vez na entrada de destino, o campo parcial será adicionado à entrada de destino na mesclagem.

A diferença entre a mesclagem e a repetição de campos é mostrada no próximo exemplo, que adiciona um novo título e autor à entrada sem usar o atributo gd:fields para remover um deles.

PATCH /myFeed/1/1/

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

Como a representação de entrada parcial não tem o atributo gd:fields, nenhum campo é removido. No entanto, os novos valores dos elementos <title> e <author> são mesclados com o recurso de destino:

  • Como o Atom permite apenas um título por entrada, o novo título substitui o valor existente. 
  • Como o Atom permite vários autores por entrada, o novo autor é anexado à lista de elementos de autores que já estão no recurso de destino.

    Observação:nem todas as APIs estão em conformidade com o padrão Atom. Por exemplo, algumas APIs permitem apenas um único elemento <author> por entrada. Outras herdam o autor da entrada do nível do feed, tornando o campo somente leitura.

Depois que o servidor processar uma solicitação PATCH válida, ele retornará um código de status HTTP 200, além de uma cópia da representação completa da entrada atualizada.

Se preferir que o servidor retorne apenas determinados elementos ou atributos, use o parâmetro de consulta fields com PATCH para solicitar uma resposta parcial.

Outros recursos

Os seguintes documentos de terceiros podem ser úteis:

Voltar ao início