Perguntas frequentes

    Visão geral

  1. O que é uma API Google Data?
  2. Tenho uma solicitação de recurso ou um relatório de bug. Onde 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 usar REST?
  7. Você tem alguma dica ou exemplo de código para problemas comuns?
  8. O Gmail tem uma API Data?

    9. Autenticação

  9. Qual é o nome do serviço no ClientLogin para cada API Data?
  10. Quando um usuário sai de um aplicativo, é necessário informar os servidores de API?
  11. Um token de autenticação ClientLogin tem uma data de validade?
  12. Tenho uma pergunta geral sobre as Contas do Google. Para onde devo ir?
  13. Como posso me autenticar em uma API?
  14. Qual valor devo usar para o parâmetro de escopo tmp/OAuth 1?
  15. Existem diferentes tipos de tokens tmp? Os tokens expiram?
  16. Qual é a principal diferença entre o ClientLogin e o XPN/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 de CAPTCHA?
  20. Devo usar o ClientLogin no meu aplicativo da Web?
  21. Como descobrir o nome de usuário do usuário ao usar o XPN/OAuth 1?
  22. Como uso o OAuth 1 com as bibliotecas de cliente da API Google Data?
  23. Como usar o tmp 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 compatíveis com o Google?
  26. Como informar um bug ou solicitar um recurso para uma das bibliotecas de cliente de dados do Google?
  27. Como 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 as ferramentas adequadas para depuração HTTP?
  30. Como faço para ter informações da geração de registros HTTP na biblioteca de cliente Java?
  31. Como faço para ter informações da geração de registros HTTP na biblioteca de cliente .NET?
  32. Como posso ativar a codificação gzip nos feeds de dados do Google?
  33. Por que estou vendo um erro "Não foi possível se conectar ao sslv2" ao usar o cliente PHP?
  34. Como consigo o documento de serviço do Atom que descreve um feed?

Visão geral

O que é uma API de dados do Google?

Uma API Google Data é baseada no protocolo de dados do Google. O protocolo de dados do Google é baseado nos formatos de distribuição Atom 1.0 e RSS 2.0, além do Atom Publishing Protocol (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 aos padrões. 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 Atom Publishing.

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

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

JSON é a notação de objeto JavaScript.

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

Leia mais sobre como usar o 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 de dados do Google é 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 das respostas 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 benefício adicional do JSON é que é mais fácil "analisar" o 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 cliente JavaScript com os serviços Blogger, Contatos ou Agenda permite a leitura e a gravação de 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 Atom XML 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.

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

Por que vocês estão usando o REST?
O REST é simples, leve, escalonável e mapeia muito bem a representação e a 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 para receber ajuda com nossas bibliotecas de cliente e fazer solicitações brutas.
O Gmail tem uma API Data?

Não, mas você pode usar o feed Atom do Gmail com XPN ou 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ê tiver interesse em gerenciar seus e-mails, o Gmail também é compatível com IMAP/POP.

Autenticação

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

Qual é o nome do serviço em ClientLogin para cada API Data?
Um "nome de serviço" é uma string curta que o sistema de autenticação ClientLogin usa para identificar um serviço do Google.
API Google Nome do serviço
APIs Google Analytics Data analytics
APIs do G Suite
(Informações e gerenciamento de domínios)		 apps
API Google Sites Data jotspot
API Blogger Data blogger
API Book Search Data print
API de dados do Google Agenda cl
API Google Code Search Data codesearch
API Contacts Data cp
API Content for Shopping structuredcontent
API Documents List Data writely
API Finance Data finance
Feed Atom do Gmail mail
API Health Data health
weaver (sandbox H9)
APIs Maps Data local
API de dados dos Álbuns da web do Picasa lh2
API Google Data Data annotateweb
API 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 sai de um aplicativo, é necessário informar os servidores de API?
Não, não é necessário informar à API Google Data quando um usuário sai de um aplicativo. No entanto, caso seu aplicativo não precise mais usar um token ISBN emitido, ele precisará revogar o token.
Um token de autenticação ClientLogin tem data de validade?
Um token ClientLogin pode durar duas semanas a partir da data de emissão, mas esse limite é específico do serviço e pode ser mais curto.
Tenho uma pergunta geral sobre as Contas do Google. Aonde devo ir?
Acesse a Central de Ajuda das Contas do Google.
Como faço para me autenticar em uma API?
A solicitação HTTP precisa incluir um cabeçalho de autorização que contenha um token recebido usando ClientLogin, XPN ou OAuth 1.
Qual valor devo usar para o parâmetro de escopo XPN/Oauth 1?
Um parâmetro scope é exigido por XPN e OAuth 1 para identificar a quais serviços do Google seu aplicativo terá acesso. Para saber mais sobre o OAuth 2.0, consulte a documentação da API específica.

API Google Nome de serviço do 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 Book Search Data 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 Documents List Data 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 Google Data Data http://www.google.com/sidewiki/feeds/
API 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
Existem diferentes tipos de tokens tmp? Os tokens expiram?
Há dois tipos de tokens tmp. O primeiro é um token de uso único que é apresentado ao seu aplicativo da Web por meio do parâmetro de consulta "token". Esse 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 o token seja revogado explicitamente pelo usuário ou pela chamada de API AuthSubRevokeToken. Um token de uso único só poderá ser trocado por um token de sessão se o URL original de AuthSubRequest tiver especificado session=1 como um parâmetro de consulta.
Qual é a principal diferença entre ClientLogin e tmp/OAuth 1?

O XPN foi projetado para aplicativos da Web. Ele garante que as credenciais do usuário sejam enviadas diretamente do navegador da Web para os servidores do Google, e não por um site de terceiros.

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

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

Posso usar a autenticação ClientLogin em aplicativos da Web de terceiros?
O uso de 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 do usuário. Isso pode ser suscetível à espionagem. Em vez disso, um aplicativo deve armazenar as credenciais do usuário no servidor e ter uma única "conta de serviço" que é sempre usada para autenticação no Google.
O que é um CAPTCHA?
Um captcha (teste completamente automatizado de Turing para dizer os computadores e humanos) é um tipo de teste de resposta a desafios usado para determinar se o usuário é humano. O termo é uma marca registrada da Universidade Carnegie Mellon. Veja mais detalhes na Wikipédia. Implementamos o CAPTCHA no ClientLogin.
Como gerar um desafio CAPTCHA?
Um algoritmo proprietário é usado para determinar quando um desafio CAPTCHA é necessário durante a autenticação. Tentativas repetidas de autenticação com credenciais inválidas geralmente 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 não é seguro e é altamente recomendado.
Como descobrir o nome de usuário do usuário ao usar o XPN/OAuth 1?
Como você só recebe um token do Google que concede acesso aos feeds do usuário, não sabe qual é o nome de usuário dele. Isso pode gerar um problema se o URL do feed que você quer usar tiver o nome de usuário como parte dele. Nesse caso, é possível usar o nome de usuário especial default para indicar "o usuário do token de autenticação que 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 tmp com as bibliotecas de cliente da API Google Data?
Consulte o artigo Como usar o XPN 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 suporte das bibliotecas de cliente do Google?

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

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, faça uma postagem no grupo de discussão das APIs de dados do Google. Queremos saber sua opinião.

Como informo um bug ou solicitação de recurso para uma das bibliotecas de cliente?

Os bugs ou as solicitações de recursos das bibliotecas de cliente podem ser informados nos seguintes locais:

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

Como ativar as opções de depuração nas bibliotecas de cliente da API Google Data?
Consulte o artigo a seguir para saber como ativar a depuração com algumas das bibliotecas de cliente: Depuração de clientes da API Google Data: como explorar 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 (em inglês)
JavaScript JSdoc (em inglês)
.NET NDoc (em inglês)
PHP phpDoc
Python PyDoc (em inglês)

Solução de problemas

Quais são as ferramentas adequadas para depuração HTTP?

Há uma série de ferramentas listadas abaixo, mas também é possível ler o artigo On the Wire: Network Capture Tools for API Developers, que descreve exemplos detalhados de WireShark e GoDaddy.

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 streams de solicitação e resposta HTTP. O tráfego entre o aplicativo e os serviços de autenticação não pode ser analisado usando o Wireshark porque a comunicação é criptografada com SSL. O Wireshark também pode ser usado para analisar o tráfego capturado usando ferramentas como o tcpdump. Ele está disponível para desenvolvedores como código-fonte e instalador do Windows. Pacotes de terceiros estão disponíveis para muitas plataformas.
Vietnã
O GoDaddy é um "proxy de depuração HTTP". Se você puder configurar seu código ou ambiente de execução para usar um servidor proxy para o tráfego HTTP, o GoDaddy estará entre seu aplicativo e os serviços de dados do Google onde poderá inspecionar o tráfego. O GoDaddy 2 inclui suporte para SSL. No momento, o utilizam o Windows.
cURL
O cURL é uma ferramenta de linha de comando que pode fazer solicitações HTTP/HTTPS. É muito útil para testar rapidamente as interações com um serviço sem precisar criar suporte HTTP primeiro no cliente.
Como faço para receber informações de geração de registros HTTP na biblioteca de cliente Java?

As bibliotecas de cliente Java usam o pacote java.util.logging para ativar a geração de registros de solicitações HTTP. Isso permite que você ative a geração de registros de cabeçalhos para solicitações e respostas, além de códigos de status e URLs de solicitação. No momento, os registros completos de solicitações e respostas não são registrados. O nome do logger usado para esses registros é com.google.gdata.client.http.HttpGDataRequest.

Caso um código de erro seja retornado dos servidores, uma exceção será lançada. As classes de exceção são herdadas de com.google.gdata.util.ServiceException e incluem um método público chamado getResponseBody(). Veja o Javadoc para mais informações.

Como faço para ter informações de geração de registros HTTP na biblioteca de cliente .NET?
A biblioteca .NET usará os métodos de rastreamento System.Diagnostics para registrar o caminho da 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, você precisa fazer duas coisas: definir um cabeçalho "Accept-Encoding" e modificar seu user agent para conter a string "gzip". Um exemplo de cabeçalhos formados corretamente:

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

Desde 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 anteriores da biblioteca de cliente PHP lançada antes de julho de 2007 (versão 1.0.0 e anteriores) que força as conexões a usar SSLv2. Ao se conectar a um servidor com SSLv2 desativado, o seguinte erro vai aparecer:

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 você não conseguir fazer upgrade para uma versão mais recente, poderá corrigir isso adicionando o seguinte código ao seu aplicativo, em que $gdata é sua instância existente de Zend_Gdata (ou subclasse apropriada):

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

É possível conseguir o documento de serviço do Atom transmitindo o parâmetro alt=atom-service na solicitação. Observação:somente a versão 2 das APIs de dados do Google retornará um documento de serviço em conformidade com a sintaxe do documento de serviço AtomPub. A versão 1 das APIs de dados do Google ainda retornará um documento de serviço, mas é baseada em uma especificação de rascunho AtomPub anterior (há alterações de sintaxe e namespace entre as duas versões).