Este documento descreve o protocolo usado pelas APIs de dados do Google, incluindo informações sobre como é uma consulta, como são os resultados e assim por diante.
Para mais informações sobre as APIs de dados do Google, consulte o documento do Guia do desenvolvedor de dados do Google e o Guia do protocolo.
Público-alvo
Este documento é destinado a qualquer pessoa que queira entender os detalhes do formato e protocolo XML usados pelas APIs de dados do Google.
Se você quer apenas escrever um código que use as APIs do cliente de dados do Google, não é necessário saber esses detalhes. Em vez disso, você pode usar 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 de dados do Google
- programação usando o protocolo sem usar as bibliotecas de cliente de dados do Google 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 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 do documento de dados do Google.
Formato do documento
O Google Data, o Atom e o RSS 2.0 compartilham o mesmo modelo de dados básicos: 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.
As APIs de dados do Google podem usar o formato de distribuição Atom (para leituras e gravações) ou o formato RSS (somente leitura).
O Atom é o formato padrão dos dados do Google. Para solicitar uma resposta no formato RSS, use o parâmetro /alt=rss/. Para mais informações, consulte Solicitações de consulta.
Quando você solicita dados no formato RSS, os dados do Google fornecem um feed (ou outra representação do recurso) nesse formato. Se não houver uma propriedade RSS equivalente para uma determinada propriedade dos dados do Google, os dados do Google vão usar a propriedade Atom, rotulando com um namespace adequado para indicar que é uma extensão do RSS.
Observação: a maioria dos feeds de dados do Google no formato Atom usa o namespace Atom como o padrão especificando um atributo xmlns no elemento de feed. Consulte a seção de exemplos para ver como fazer isso. Portanto, os exemplos neste documento não especificam explicitamente atom: para elementos em um feed no formato Atom.
As tabelas a seguir mostram as representações Atom e RSS dos elementos do esquema. Todos os dados não mencionados nessas tabelas são tratados como XML simples e mostrados da mesma forma nas duas representações. A menos que indicado de outra forma, os elementos XML em uma determinada coluna estão no namespace correspondente a essa coluna. Esse 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 de dados do Google:
| Item do esquema do feed | Representação do Atom | Representação de RSS |
|---|---|---|
| Título do feed | /feed/title |
/rss/channel/title |
| ID de feed | /feed/id |
/rss/channel/atom:id |
| Link HTML do feed | /feed/link[@rel="alternate"], e [@type="text/html"]/@href |
/rss/channel/link |
| Descrição do feed | /feed/subtitle |
/rss/channel/description |
| Idioma do feed | /feed/@xml:lang |
/rss/channel/language |
| Direitos autorais do feed | /feed/rights |
/rss/channel/copyright |
| Autor do feed |
Obrigatório em alguns casos. Consulte a especificação Atom. |
/rss/channel/managingEditor |
| Data da última atualização do feed | /feed/updated(formato RFC 3339) |
/rss/channel/lastBuildDate(formato RFC 822) |
| Categoria do feed | /feed/category/@term |
/rss/channel/category |
| Esquema de categoria do feed | /feed/category/@scheme |
/rss/channel/category/@domain |
| Gerador de feeds | /feed/generator/feed/generator/@uri |
/rss/channel/generator |
| Ícone de feed | /feed/icon |
/rss/channel/image/url (a menos que também exista um logotipo, caso no qual o ícone não está incluído no feed) |
| Logotipo do feed | /feed/logo |
/rss/channel/image/url |
A tabela a seguir mostra os elementos de um feed de resultados da pesquisa de dados do Google. Os dados do Google expõem 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 | Representação RSS/OpenSearch |
|---|---|---|
| Número de resultados da pesquisa | /feed/openSearch:totalResults |
/rss/channel/openSearch:totalResults |
| Índice inicial dos resultados da pesquisa | /feed/openSearch:startIndex |
/rss/channel/openSearch:startIndex |
| Número de resultados da pesquisa por página | /feed/openSearch:itemsPerPage |
/rss/channel/openSearch:itemsPerPage |
A tabela a seguir mostra os elementos de uma entrada de dados do Google:
| Item do esquema de entrada | Representação do Atom | Representação de RSS |
|---|---|---|
| ID da entrada | /feed/entry/id |
/rss/channel/item/guid |
| ID da versão de entrada | Opcionalmente incorporado em EditURI (consulte a seção Simultaneidade otimista deste documento). | — |
| Título da entrada | /feed/entry/title |
/rss/channel/item/title |
| Link de entrada | /feed/entry/link |
/rss/channel/item/link/rss/channel/item/enclosure/rss/channel/item/comments |
| Resumo da entrada |
Obrigatório em alguns casos. Consulte a especificação Atom. |
/rss/channel/item/atom:summary |
| Conteúdo da inscrição |
Se não houver elemento de conteúdo, a entrada precisará conter pelo menos um elemento |
/rss/channel/item/description |
| Autor da entrada |
Obrigatório em alguns casos. Consulte a especificação Atom. |
/rss/channel/item/author |
| Categoria da entrada | /feed/entry/category/@term |
/rss/channel/item/category |
| Esquema de categoria de entrada | /feed/entry/category/@scheme |
/rss/channel/item/category/@domain |
| Data de publicação da entrada | /feed/entry/published(RFC 3339) |
/rss/channel/item/pubDate(RFC 822) |
| Data de atualização da entrada | /feed/entry/updated(RFC 3339) |
/rss/channel/item/atom: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 consulta um serviço de dados do Google emitindo uma solicitação GET HTTP. 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
Os serviços de dados do Google são compatíveis com a HTTP condicional GET. Eles definiram o cabeçalho de resposta da última modificação 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 de dados do Google retorna uma resposta HTTP 304 (não modificado).
Um serviço de dados do Google deve suportar consultas de categoria e 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 |
|---|---|---|
q |
String de consulta de texto completo |
|
/-/category |
Filtro de categoria |
|
category |
Filtro de categoria |
|
author |
Autor da entrada |
|
alt |
Tipo de representação alternativo |
|
updated-min, updated-max |
Limites na data de atualização da entrada |
|
published-min, published-max |
Limites na data de publicação de entrada |
|
start-index |
Índice com base em 1 do primeiro resultado a ser recuperado |
|
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. |
| ID da entrada | ID de uma entrada específica a ser recuperada |
|
Sobre as consultas de categoria
Decidimos especificar um formato um pouco incomum para consultas de categoria. Em vez de uma consulta como esta:
http://example.com/jo?category=Fritz&category=2006
usamos:
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 serão as consultas mais comuns.
A desvantagem dessa abordagem é que você precisa usar /-/ em consultas de categoria para que os serviços de dados do Google 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-indexna 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 do Atom e do Google 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
typedepende 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:atom="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
<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>
<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>
<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 dos serviços de dados do Google.
| 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. |
| 500 ERRO INTERNO DO SERVIDOR | Erro interno. Esse é o código padrão usado para todos os erros não reconhecidos. |
Simultaneidade otimista (controle de versões)
Às vezes, é importante garantir que vários clientes não substituam acidentalmente as alterações uns dos outros. Isso é feito mais facilmente garantindo que a versão atual de uma entrada que um cliente está modificando seja igual à versão em que o cliente está baseado suas modificações. Se um segundo cliente fizer uma atualização antes do primeiro, a atualização do primeiro cliente será negada, porque o primeiro cliente não está mais se baseando nas modificações da versão mais recente.
Nos feeds de dados do Google que suportam o controle de versão, conseguimos essa semântica anexando um ID de versão ao EditURI de cada entrada. Apenas o EditURI é afetado, não o ID de entrada. Nesse esquema, cada atualização muda o EditURI da entrada, garantindo que as atualizações subsequentes com base na versão original falhem. As exclusões, é claro, são idênticas às atualizações em relação a esse recurso. Se você enviar uma exclusão com um número de versão antigo, ela falhará.
Nem todos os feeds de dados do Google são compatíveis com a simultaneidade otimista. Em um feed que é compatível, se o servidor detectar um conflito de versão em PUT ou DELETE, ele responde com 409 Conflict. O corpo da resposta contém o estado atual da entrada (um documento de entrada do Atom). Recomendamos que o cliente resolva o conflito e reenvie a solicitação usando o EditURI da resposta 409.
Notas de motivação e design
Essa abordagem da simultaneidade otimista permite implementar a semântica desejada sem exigir uma nova marcação para IDs de versão, o que torna as respostas dos dados do Google compatíveis com endpoints Atom de dados que não são do Google.
Em vez de especificar os IDs de versão, poderíamos optar por analisar o carimbo de data/hora de atualização em cada entrada (/atom:entry/atom:updated). No entanto, há dois problemas para usar esse carimbo:
- Ela só funciona para atualizações, não para exclusões.
- Ele força os aplicativos a usar valores de data/hora como IDs de versão, o que dificultaria a reformulação dos dados do Google em muitos armazenamentos de dados existentes.
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 de dados do Google, precisa usar um sistema de autenticação específico do Google chamado Proxy de autenticação da 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 de autenticação retornará um token que o cliente usa posteriormente (em um cabeçalho de autorização HTTP) ao enviar solicitações de dados do Google.
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 documentação Visão geral da autenticação de dados do Google ou 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 os serviços de dados do Google, mas o desempenho poderá ser afetado em comparação com os 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,PUTeDELETE - 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