Perguntas frequentes

    Visão geral

  1. O que é uma API de dados do Google?
  2. Quero solicitar um recurso ou informar um bug. Onde devo postar?
  3. Onde posso fazer uma pergunta sobre uma API específica?
  4. O que é JSON?
  5. Preciso usar XML? Há outros formatos de dados disponíveis?
  6. Por que você está usando REST?
  7. Você tem alguma dica ou exemplo de código curto para problemas comuns?
  8. O Gmail tem uma API de dados?

    9. Autenticação

  9. Qual é o nome do serviço no ClientLogin para cada API de dados?
  10. Quando um usuário faz logout de um aplicativo, é necessário informar os servidores da API?
  11. Um token de autenticação do ClientLogin tem uma data de validade?
  12. Tenho uma dúvida geral sobre as Contas do Google. O que fazer?
  13. Como faço para me autenticar em uma API?
  14. Qual valor devo usar para o parâmetro de escopo do AuthSub/OAuth 1?
  15. Existem diferentes tipos de tokens AuthSub? Os tokens expiram?
  16. Qual é a principal diferença entre o ClientLogin e o AuthSub/OAuth 1?
  17. Posso usar a autenticação ClientLogin em aplicativos da Web de terceiros?
  18. O que é um CAPTCHA?
  19. Como gerar um desafio CAPTCHA?
  20. Devo usar o ClientLogin no meu aplicativo da Web?
  21. Como descobrir o nome de usuário de um usuário ao usar AuthSub/OAuth 1?
  22. Como usar o OAuth 1 com as bibliotecas de cliente da API Google Data?
  23. Como uso o AuthSub com as bibliotecas de cliente da API Google Data?
  24. Como usar o ClientLogin com as bibliotecas de cliente da API Google Data?

    25. Bibliotecas de cliente

  25. Quais linguagens de programação têm bibliotecas de cliente com suporte do Google?
  26. Como faço para informar um bug ou solicitar um recurso para uma das bibliotecas de cliente do Google Data?
  27. Como faço para ativar as opções de depuração nas bibliotecas de cliente?
  28. Onde posso encontrar documentos de referência para as classes da biblioteca de cliente?

    29. Solução de problemas

  29. Quais são algumas boas ferramentas para depuração de HTTP?
  30. Como faço para receber informações de registro HTTP na biblioteca de cliente Java?
  31. Como faço para receber informações de registro HTTP na biblioteca de cliente .NET?
  32. Como posso ativar a codificação gzip nos feeds de dados do Google?
  33. Por que aparece o erro "Não foi possível se conectar ao sslv2" ao usar o cliente PHP?
  34. Como faço para receber o documento de serviço do Atom que descreve um feed?

Visão geral

O que é uma API de dados do Google?

Uma API de dados do Google é baseada no protocolo de dados do Google. O protocolo Google Data é baseado nos formatos de distribuição Atom 1.0 e RSS 2.0, além do protocolo de publicação Atom (APP, na sigla em inglês).

O protocolo de dados do Google estende esses padrões de várias maneiras, usando os mecanismos de extensão integrados a eles. Os feeds estão em conformidade com os formatos de distribuição Atom ou RSS. O modelo de publicação está em conformidade com o protocolo de publicação Atom.

O protocolo também fornece um modelo geral para feeds, consultas e resultados. Você pode usar essa biblioteca para enviar consultas e atualizações a qualquer API Data.

Tenho uma solicitação de recurso ou um relatório de bug. Onde devo postar?
Confira nosso Issue Tracker. Procure sua solicitação de recurso e marque com uma estrela para mostrar seu apoio e receber atualizações sobre o status dela.
Onde posso fazer uma pergunta sobre uma API específica?
Se o problema não estiver listado aqui ou se você quiser mais esclarecimentos, há grupos de discussão específicos para cada API de dados do Google:
O que é JSON?

JSON se refere a JavaScript Object Notation.

JSON é um formato leve de troca de dados cuja simplicidade resultou em uso generalizado entre desenvolvedores da Web. Ele é fácil de ler e escrever, pode ser analisado usando qualquer linguagem de programação, e as estruturas dele são mapeadas diretamente para estruturas de dados usadas na maioria das linguagens de programação.

Leia mais sobre Como usar JSON com as APIs de dados do Google.

Preciso usar XML? Há outros formatos de dados disponíveis?
O formato de dados padrão das APIs Google Data é XML, na forma de um feed Atom. No entanto, ao solicitar um feed, é possível especificar um formato alternativo usando o parâmetro de consulta alt.
  • alt=rss
    Os dados de resposta são formatados como um feed RSS.
  • alt=json ou alt=json-in-script
    retorna uma representação JSON da estrutura XML do feed Atom. O JSON também é mais fácil de "analisar" no código do cliente JavaScript. No momento, o uso de JSON está disponível apenas como opção somente leitura. No entanto, usar a biblioteca de cliente JavaScript com os serviços Blogger, Contatos ou Agenda permite ler e gravar dados.

    Leia mais sobre Como solicitar e usar feeds JSON.

  • alt=atom-in-script
    Semelhante a alt=json-in-script, mas os resultados são retornados como uma string XML Atom em vez de JSON.
  • alt=rss-in-script
    Semelhante a alt=atom-in-script, mas os resultados são retornados como uma string XML RSS em vez de Atom.

Leia mais sobre os formatos alternativos no Guia de referência de dados do Google.

Por que você está usando REST?
O REST é simples, leve, escalonável e se adapta muito bem à representação e exposição de dados.
Há dicas ou pequenos exemplos de código dos problemas comuns disponíveis?
Consulte o blog de dicas da API Google Data (link em inglês) para receber ajuda com nossas bibliotecas de cliente e com a criação de solicitações brutas.
O Gmail tem uma API de dados?

Não, mas você pode usar o feed Atom do Gmail com o AuthSub ou o OAuth 1 para solicitar acesso somente leitura às mensagens não lidas de um usuário. O escopo precisa ser definido como https://mail.google.com/mail/feed/atom/. Um exemplo de consulta seria:

GET https://mail.google.com/mail/feed/atom/

Se você quiser gerenciar seu e-mail, o Gmail também oferece suporte a IMAP/POP.

Autenticação

Na documentação das APIs de dados do Google, "OAuth" se refere ao OAuth 1. Para detalhes sobre o OAuth 2.0, consulte a documentação da sua API específica.

Qual é o nome do serviço no ClientLogin para cada API de dados?
Um "nome de serviço" é uma string breve que o sistema de autenticação ClientLogin usa para identificar um serviço do Google.
API do Google Nome do serviço
APIs Google Analytics Data analytics
APIs do G Suite
(informações e gerenciamento de domínio)		 apps
API Google Sites Data jotspot
API Blogger Data blogger
API Data de Pesquisa de livros print
API de dados do Google Agenda cl
API Google Code Search Data codesearch
API Contacts Data cp
API Content for Shopping structuredcontent
API Data de lista de documentos writely
API Finance Data finance
Feed Atom do Gmail mail
API Health Data health
weaver (sandbox H9)
APIs de dados do Maps local
API de dados dos Álbuns da Web do Picasa lh2
API Sidewiki Data annotateweb
API Google Sheets Data wise
API Webmaster Tools sitemaps
API YouTube Data youtube

Para mais informações sobre os outros parâmetros usados em uma solicitação do ClientLogin, consulte a documentação do ClientLogin.

Quando um usuário faz logout de um aplicativo, é necessário informar os servidores da API?
Não, não é necessário informar a API Google Data quando um usuário faz logout de um aplicativo. No entanto, se o aplicativo não precisar mais usar um token do AuthSub emitido, ele deverá revogar o token.
Um token de autenticação do ClientLogin tem uma data de validade?
Um token do ClientLogin pode durar duas semanas a partir da data de emissão, mas esse limite é específico do serviço e pode ser menor.
Tenho uma pergunta geral sobre as Contas do Google. O que fazer?
Acesse a Central de Ajuda das Contas do Google.
Como faço para me autenticar em uma API?
Sua solicitação HTTP precisa incluir um cabeçalho de autorização que contenha um token obtido usando ClientLogin, AuthSub ou OAuth 1.
Qual valor devo usar para o parâmetro de escopo do AuthSub/OAuth 1?
Um parâmetro scope é exigido pelo AuthSub e pelo OAuth 1 para identificar a quais serviços do Google seu aplicativo terá acesso. Para detalhes do OAuth 2.0, consulte a documentação da sua API específica.

API do Google Nome do serviço ClientLogin
API Google Analytics Data https://www.google.com/analytics/feeds/
API Google Sites Data http(s)://sites.google.com/feeds/
API Blogger Data http://www.blogger.com/feeds/
API Data de Pesquisa de livros http://www.google.com/books/feeds/
API de dados do Google Agenda http(s)://www.google.com/calendar/feeds/
API Contacts Data http(s)://www.google.com/m8/feeds/
API Content for Shopping https://www.googleapis.com/auth/structuredcontent
API Data de lista de documentos http(s)://docs.google.com/feeds/
API Finance Data http://finance.google.com/finance/feeds/
Feed Atom do Gmail https://mail.google.com/mail/feed/atom/
API Health Data https://www.google.com/health/feeds/
https://www.google.com/h9/feeds/ (sandbox H9)
API de dados do Google Maps http://maps.google.com/maps/feeds/
API de dados dos Álbuns da Web do Picasa http://picasaweb.google.com/data/
API Portable Contacts http://www-opensocial.googleusercontent.com/api/people
API Sidewiki Data http://www.google.com/sidewiki/feeds/
API Google Sheets Data http(s)://spreadsheets.google.com/feeds/
API Webmaster Tools http://www.google.com/webmasters/tools/feeds/
API YouTube Data http://gdata.youtube.com
Há diferentes tipos de tokens AuthSub? Os tokens expiram?
Há dois tipos de tokens AuthSub. O primeiro é um token de uso único que é apresentado ao seu aplicativo da Web pelo parâmetro de consulta "token". O token expira na primeira vez que é usado com o serviço para o qual foi emitido ou quando é trocado por um token de sessão.

Os tokens de sessão não expiram, a menos que sejam revogados explicitamente pelo usuário ou pela chamada da API AuthSubRevokeToken. Um token de uso único só pode ser trocado por um token de sessão se o URL AuthSubRequest original especificou session=1 como um parâmetro de consulta.
Qual é a principal diferença entre o ClientLogin e o AuthSub/OAuth 1?

O AuthSub foi criado para aplicativos da Web. Ele garante que as credenciais do usuário sejam enviadas com segurança diretamente do navegador da Web de um usuário para os servidores do Google, em vez de um site de terceiros.

O ClientLogin é para aplicativos instalados em computadores. Ele exige que o aplicativo solicitante transmita as credenciais do usuário ao Google em nome dele.

Consulte a documentação sobre a API Google Account Authentication.

Posso usar a autenticação ClientLogin em aplicativos da Web de terceiros?
O uso do ClientLogin em aplicativos da Web de terceiros é aceitável, mas não é recomendado. Como prática recomendada, o aplicativo da Web nunca deve pedir as credenciais de login de um usuário, já que isso pode ser suscetível a espionagem. Em vez disso, um aplicativo deve armazenar credenciais de usuário no lado do servidor e ter uma única "conta de serviço" que é sempre usada para autenticar com o Google.
O que é um CAPTCHA?
Um CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) é um tipo de teste de desafio-resposta usado para determinar se o usuário é humano. O termo é uma marca registrada da Universidade Carnegie Mellon. Confira mais detalhes na Wikipédia. Implementamos o CAPTCHA no ClientLogin.
Como gerar um teste de CAPTCHA?
Um algoritmo proprietário é usado para determinar quando um teste de CAPTCHA é necessário durante a autenticação. Tentativas repetidas de autenticação com credenciais inválidas geram um desafio CAPTCHA.
Devo usar o ClientLogin no meu aplicativo da Web?
Não. O ClientLogin deve ser usado por aplicativos instalados em hardware de propriedade do usuário. O uso da API ClientLogin em aplicativos da Web é inseguro e não é recomendado.
Como descobrir o nome de usuário do usuário ao usar AuthSub/OAuth 1?
Como você só recebe um token do Google que concede acesso aos feeds do usuário, talvez não saiba qual é o nome de usuário dele. Isso pode ser um problema se o URL do feed que você quer usar contiver o nome de usuário. Nesse caso, você pode usar o nome de usuário especial default para significar "o usuário cujo token de autenticação estou usando".
Como usar o OAuth 1 com as bibliotecas de cliente da API Google Data?
Consulte o artigo Como usar o OAuth 1 com as bibliotecas de cliente da API Google Data.
Como usar o AuthSub com as bibliotecas de cliente da API Google Data?
Consulte o artigo Como usar o AuthSub com as bibliotecas de cliente da API Google Data.
Como usar o ClientLogin com as bibliotecas de cliente da API Google Data?
Consulte o artigo Como usar o ClientLogin com as bibliotecas de cliente da API Google Data.

Bibliotecas de cliente

Quais linguagens de programação têm bibliotecas de cliente com suporte do Google?

As bibliotecas de cliente Java, .NET, Python e Objective-C têm suporte oficial do Google. Além disso, nosso parceiro Zend escreveu uma biblioteca de cliente PHP. Com essas bibliotecas, é possível criar solicitações do protocolo de dados do Google, enviá-las a um serviço e processar respostas do servidor. Também há uma biblioteca de cliente JavaScript que, no momento, só é compatível com o Blogger, a Agenda e o Google Contatos.

Se você escrever uma biblioteca de cliente em uma linguagem diferente de Java, .Net, Python ou Objective-C e quiser compartilhar com a comunidade de desenvolvedores da API Data, poste no grupo de discussão das APIs Google Data. Queremos saber sua opinião.

Como informo um bug ou solicito um recurso para uma das bibliotecas de cliente?

Bugs ou solicitações de recursos para as bibliotecas de cliente podem ser informados nos seguintes locais:

Depois de postar o bug, crie uma conversa no fórum de desenvolvedores para a API adequada.

Como faço para ativar as opções de depuração nas bibliotecas de cliente da API Google Data?
Consulte o artigo a seguir para informações sobre como ativar a depuração com algumas das bibliotecas de cliente: Depuração de clientes da API Google Data: como analisar o tráfego no seu programa
Onde posso encontrar documentos de referência para as classes da biblioteca de cliente?
Biblioteca de cliente Guia de referência
Java Javadoc
JavaScript JSdoc
.NET NDoc
PHP phpDoc
Python PyDoc

Solução de problemas

Quais são algumas boas ferramentas para depuração HTTP?

Há várias ferramentas listadas abaixo, mas talvez você também queira ler o artigo On the Wire: Network Capture Tools for API Developers (em inglês), que descreve exemplos detalhados do WireShark e do Fiddler.

Wireshark
O Wireshark é um "analisador de protocolo de rede". Ele permite capturar o tráfego de rede e analisar o conteúdo. É muito útil para depurar o tráfego que ocorre em bibliotecas em que você não tem acesso direto aos fluxos de solicitação e resposta HTTP. O tráfego entre seu aplicativo e os serviços de autenticação não podem ser analisados usando o Wireshark, já que a comunicação é criptografada usando SSL. O Wireshark também pode ser usado para analisar o tráfego capturado com ferramentas como o tcpdump. O Wireshark está disponível para desenvolvedores como código-fonte e um instalador do Windows. Pacotes de terceiros estão disponíveis para muitas plataformas.
Fiddler
O Fiddler é um "proxy de depuração HTTP". Se você puder configurar seu código ou ambiente de execução para usar um servidor proxy para tráfego HTTP, o Fiddler ficará entre seu aplicativo e os serviços de dados do Google, permitindo que você inspecione o tráfego. O Fiddler 2 inclui suporte para SSL. No momento, o Fiddler está disponível apenas para Windows.
cURL
cURL é uma ferramenta de linha de comando que pode fazer solicitações HTTP/HTTPS. Ela é muito útil para testes rápidos de interações com um serviço sem precisar criar primeiro o suporte HTTP no cliente.
Como faço para receber informações de registro HTTP na biblioteca de cliente Java?

As bibliotecas de cliente Java usam o pacote java.util.logging para ativar o registro de solicitações HTTP. Isso permite ativar o registro em log de cabeçalhos para solicitações e respostas, bem como códigos de status e URLs de solicitação. No momento, não é possível registrar em log os fluxos completos de solicitação e resposta. O nome do logger usado para esses registros é com.google.gdata.client.http.HttpGDataRequest.

Se um código de erro for retornado dos servidores, uma exceção será gerada. As classes de exceção herdam de com.google.gdata.util.ServiceException e incluem um método público chamado getResponseBody(). Consulte o Javadoc para mais informações.

Como faço para receber informações de registro HTTP na biblioteca de cliente .NET?
A biblioteca .NET usa os métodos de rastreamento System.Diagnostics para registrar o caminho de execução, se o rastreamento estiver ativado. Além disso, em caso de erro, uma GDataRequestException é gerada. A exceção contém um ResponseString que permite acessar o corpo da resposta HTTP.
Como posso ativar a codificação gzip nos feeds de dados do Google?

Para receber uma resposta codificada em gzip de uma das APIs de dados do Google, é preciso definir um cabeçalho "Accept-Encoding" e modificar seu user agent para conter a string "gzip". Exemplo de cabeçalhos formados corretamente:

User-Agent: my program (gzip)
Accept-Encoding: gzip
Por que recebo o erro "Não foi possível se conectar ao sslv2" ao usar o cliente PHP?

Em julho de 2009, começamos a desativar o SSLv2 nos nossos servidores como uma medida de precaução para melhorar a segurança. Infelizmente, há um bug nas versões iniciais da biblioteca de cliente PHP lançadas antes de julho de 2007 (versão 1.0.0 e anteriores) que força as conexões a usar o SSLv2. Ao se conectar a um servidor com o SSLv2 desativado, o seguinte erro é gerado:

PHP Fatal error:  Uncaught exception 'Zend_Http_Client_Adapter_Exception' with message 'Unable to Connect to sslv2://www.google.com:443.'

Para corrigir esse erro, faça upgrade para uma versão mais recente da biblioteca de cliente PHP, disponível em http://framework.zend.com/download.

Se não for possível fazer upgrade para uma versão mais recente, adicione o seguinte código ao aplicativo, em que $gdata é sua instância atual de Zend_Gdata (ou subclasse apropriada):

$gdata->getHttpClient()->setConfig(array('ssltransport' => 'ssl'));
Como faço para receber o documento de serviço do Atom que descreve um feed?

Para receber o documento de serviço do Atom, transmita o parâmetro alt=atom-service na solicitação. Observação:somente a versão 2 das APIs Google Data vai retornar um documento de serviço que esteja de acordo com a sintaxe do documento de serviço AtomPub. A versão 1 das APIs de dados do Google ainda vai retornar um documento de serviço, mas ele é baseado em uma especificação de rascunho do AtomPub anterior. Há mudanças de sintaxe e namespace entre as duas versões.