Visão geral do guia do desenvolvedor

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.

A missão do Google é organizar as informações de todo o mundo e torná-las acessíveis e úteis. Isso inclui tornar as informações acessíveis em contextos diferentes de um navegador da Web e de serviços fora do Google.

O protocolo de dados do Google oferece um meio seguro para os desenvolvedores externos criarem novos aplicativos que permitem aos usuários finais acessar e atualizar os dados armazenados por muitos produtos do Google. Os desenvolvedores externos podem usar o protocolo de dados do Google diretamente ou qualquer uma das linguagens de programação compatíveis fornecidas pelas bibliotecas de cliente.

Público-alvo

Este conjunto de documentos se destina a qualquer pessoa que queira entender o protocolo de dados do Google. Mesmo que você queira apenas escrever o código que usa as bibliotecas de cliente específicas da linguagem, esse conjunto de documentos pode ser útil se você quiser entender o que está acontecendo abaixo da camada de abstração da biblioteca de cliente.

Se você estiver procurando o Guia do desenvolvedor para uma API específica, acesse o Diretório de APIs do protocolo de dados do Google.

Se você quiser acessar uma API na sua linguagem de programação favorita, acesse a página de download de Bibliotecas de cliente.

Contexto

Vários produtos do Google, como o Google Agenda e o Google Planilhas, oferecem APIs com base no protocolo de dados do Google. Você, o desenvolvedor, pode usar essas APIs para criar aplicativos cliente que ofereçam aos usuários finais novas formas de acessar e manipular os dados armazenados nesses produtos do Google.

Observação: os produtos do Google que fornecem APIs também são chamados de serviços nestes e em outros documentos relacionados.

Se você escrever o código que usa o protocolo de dados do Google diretamente, ele acessará a API usando solicitações HTTP como GET ou POST. Com essas solicitações, os dados armazenados pelo produto do Google são transferidos e recebidos via transferência na forma de feeds de dados. Os feeds de dados são simplesmente listas estruturadas que contêm os dados. Antes, o formato do feed principal era o XML AtomPub, mas agora o JSON ou JavaScript Object Notation também está disponível como um formato alternativo.

Se preferir não escrever código que faça solicitações HTTP diretamente, programe o aplicativo cliente usando uma das linguagens de programação disponíveis no conjunto de bibliotecas cliente. Ao fazer isso, os detalhes das solicitações HTTP serão processados pela biblioteca do cliente, e você criará o código em um nível mais conceitual usando os métodos específicos da linguagem e as classes fornecidas pela biblioteca do cliente.

Consulte a documentação específica do produto para mais informações sobre os idiomas disponíveis para a API ou a versão da API que você está usando.

Versões do protocolo

Protocolo versão 2.0 x versão 1.0 do protocolo

A primeira versão do Protocolo de dados do Google foi desenvolvida antes da finalização do protocolo de publicação Atom. A segunda versão do protocolo de dados do Google é totalmente compatível com o padrão AtomPub RFC 5023.

O protocolo de dados do Google versão 2.0 também inclui suporte para:

  • ETags HTTP Um padrão da Web que ajuda os aplicativos cliente a usar melhor o armazenamento em cache HTTP. Os serviços incluídos nas bibliotecas de cliente compatíveis com o protocolo v2.0 processam as ETags automaticamente.
  • Resposta parcial e Atualização parcial (experimental) Recursos para fazer solicitações para transferir menos dados. Ao solicitar apenas as informações que você realmente precisa ou enviar atualizações que incluam apenas os dados que realmente quer alterar, seu aplicativo cliente pode ser muito mais eficiente no uso dos recursos de rede, CPU e memória. No momento, a resposta parcial e a atualização parcial estão disponíveis apenas para alguns produtos. Consulte a documentação específica do produto para saber se a API é compatível com ela.

Como atualizar o aplicativo

Se a API que você está usando tiver sido criada com base na versão mais recente do protocolo, a funcionalidade do protocolo v2.0 estará incluída na documentação. Em geral, recomendamos que você atualize o aplicativo cliente para a versão mais recente disponível para sua API.

Como atualizar um cliente baseado em biblioteca de cliente

Se o aplicativo cliente usa uma biblioteca de cliente, como a biblioteca de cliente Java ou a biblioteca de cliente .NET, ele pode conter uma versão da API que ofereça suporte aos recursos do protocolo v2.0. Para saber se as duas condições a seguir são verdadeiras, consulte a documentação da API para o produto do Google que você está usando:

  • Há uma versão da API com suporte aos recursos do protocolo de dados do Google v2.0.
  • A biblioteca de cliente que você está usando também é compatível com essa versão da API.

Se a biblioteca de cliente for compatível e você quiser atualizar o aplicativo existente, basta fazer o download e usar a versão mais recente da biblioteca de cliente. Todo o código ainda funciona, e a biblioteca de cliente cuida das mudanças no Protocolo v2.0 em segundo plano.

Como atualizar um cliente HTTP bruto

Se você gravou o aplicativo cliente usando o protocolo de dados do Google diretamente, será necessário fazer as seguintes alterações:

  • Solicitações de versão não padrão. Adicione um cabeçalho de versão HTTP (GData-Version: X.0) a cada solicitação HTTP enviada, em que X é a versão da API compatível com os recursos do protocolo de dados v2.0 do Google. Como alternativa, adicione um parâmetro de consulta (v=X.0) ao URL de cada solicitação, em que X é, mais uma vez, a versão correta da API. Se você não especificar uma versão posterior, suas solicitações serão enviadas para a versão suportada mais antiga da API por padrão.
  • Simultaneidade otimista. Se você estava usando uma versão de uma API compatível com simultaneidade otimista, talvez seja necessário mudar a atualização e excluir o código para usar ETags. Para mais informações, leia a seção ETags da documentação de referência do Protocolo de dados do Google e leia as seções "Atualizar" e "Excluir" do guia do desenvolvedor de protocolo para o serviço que seu aplicativo cliente está usando.
  • Self ou editar URIs. Se o cliente acompanha os URIs próprios ou editados para feeds ou entradas, é possível que eles tenham mudado. Para conseguir o novo URI, solicite o item novamente usando o URI antigo, mas marque-a como uma solicitação de versão X.0, em que X é a versão da API compatível com os recursos do protocolo de dados v2.0 do Google. O servidor retorna a nova representação da entrada, incluindo os novos URIs, que você pode armazenar no lugar dos antigos.
  • URIs de namespace. Caso seu cliente armazene URIs de namespace da API Google Data Protocol ou os codifique, será necessário atualizá-los:
    • O namespace AtomPub (prefixo app) foi alterado de http://purl.org/atom/app para http://www.w3.org/2007/app.
    • O namespace do OpenSearch (prefixo openSearch) foi alterado de http://a9.com/-/spec/opensearchrss/1.0/ para http://a9.com/-/spec/opensearch/1.1/.