Aviso: esta página é sobre as APIs mais antigas do Google, as APIs Google Data. Ela é relevante apenas para as APIs listadas no diretório de APIs Google Data, muitas das quais foram substituídas por APIs mais recentes. Para informações sobre uma nova API específica, consulte a documentação dela. Para informações sobre como autorizar solicitações com uma API mais recente, consulte Autenticação e autorização de contas do Google.
Vídeo:assista Trevor Johns explicar a instalação da biblioteca de cliente, a arquitetura da biblioteca e um tutorial de código.
Atualizado em outubro de 2008 (originalmente escrito por Daniel Holevoet)
- Introdução
- Pré-instalação
- Instalar o PHP
- Como instalar a biblioteca de cliente PHP do Google Data
- Verifique se você consegue acessar os arquivos da biblioteca de cliente.
- Onde saber mais
- Apêndice A: como editar o caminho do PHP no arquivo de configuração
php.ini - Apêndice B: Como usar o PHP na linha de comando
- Apêndice C: dicas e soluções
- Histórico de revisões
Introdução
A biblioteca de cliente PHP de dados do Google é uma coleção avançada de classes que permite interagir com as APIs de dados do Google. Ao contrário das outras bibliotecas de cliente, ela é empacotada como parte do conhecido Zend Framework, mas também pode ser baixada separadamente. Assim como nossas outras bibliotecas de cliente, ela também é de código aberto e foi projetada para ser simples e eficiente, permitindo que você comece seus projetos rapidamente.
Pré-instalação
O PHP já pode estar instalado na sua máquina de desenvolvimento ou no servidor da Web. Portanto, a primeira etapa é verificar esse fato e garantir que a versão do PHP seja recente o suficiente para ser usada na biblioteca de cliente. A maneira mais fácil de verificar é colocar um novo arquivo em um diretório acessível pela Web no seu servidor. Digite as seguintes informações no arquivo:
<?php phpinfo(); ?>
Em seguida, verifique se ele pode ser acessado na Web definindo as permissões adequadas e navegue até o local dele no navegador. Se o PHP estiver instalado e o servidor conseguir renderizar páginas PHP, você vai ver algo semelhante à captura de tela abaixo:
A captura de tela mostra a página de informações do PHP. Esta página mostra a versão do PHP instalada (5.2.6 neste caso), além das extensões ativadas (na seção "Configurar comando") e a localização do arquivo de configuração interna do PHP (na seção "Arquivo de configuração carregado"). Se a página não for exibida ou se a versão do PHP for anterior à 5.1.4, instale ou faça upgrade da versão do PHP. Caso contrário, pule a próxima seção e continue para instalar a biblioteca de cliente PHP.
Observação:se você tiver acesso à linha de comando e planejar usar o PHP para executar scripts de linha de comando, consulte a seção de PHP da linha de comando deste artigo.
Como instalar o PHP
A instalação varia um pouco de acordo com a plataforma. Por isso, é importante seguir as instruções específicas para sua plataforma durante a instalação. Antes de começarmos, vale a pena ressaltar que os pacotes pré-instalados que também incluem o servidor da Web Apache e o banco de dados MySQL com PHP ganharam popularidade. Para Windows, Mac OS X e Linux, há o projeto XAMPP (em inglês). Os usuários do Mac OS X também podem usar o projeto MAMP. Os dois pacotes oferecem suporte ao OpenSSL em PHP, que é necessário para interagir com feeds autenticados.
Se você instalar o PHP seguindo as etapas abaixo, instale e ative também o suporte ao OpenSSL. Mais detalhes sobre isso podem ser encontrados na seção OpenSSL do site do PHP. As seções a seguir se concentram em como instalar o PHP por conta própria.
No Windows
A maneira mais fácil de instalar ou fazer upgrade do PHP no Windows é com o instalador disponível na página de downloads do PHP.
- Escolha a opção do instalador do PHP (na seção de binários do Windows) correspondente à versão mais recente do PHP e permita o download.
- Abra o instalador e siga as instruções do assistente de instalação.
- Quando o assistente pedir, escolha o servidor da Web instalado no seu sistema para que ele seja configurado para funcionar com PHP.
- Para verificar a instalação, siga as etapas descritas na seção acima.
No Mac OS X
O PHP está incluído no OS X, mas antes de usá-lo, faça upgrade para a versão mais recente. Para fazer upgrade, instale um dos vários pacotes binários sem custo financeiro ou compile por conta própria. Para mais detalhes, consulte a página de documentação do PHP sobre instalação no Mac OS X.
Depois de instalar ou configurar o OS X, verifique a instalação seguindo as etapas descritas na seção de pré-instalação deste documento.
No Linux
Dependendo da distribuição do Linux, pode haver uma opção de configuração integrada ou fácil de usar para a instalação do PHP. Por exemplo, no Ubuntu, você pode usar um gerenciador de pacotes ou apenas digitar o seguinte em um terminal:
sudo apt-get install php5
Se não houver uma instalação empacotada disponível com sua distribuição do Linux, instale pelo código-fonte. Há instruções detalhadas para compilar PHP para Apache 1.3 e compilar PHP para Apache 2. O PHP.net também tem instruções para outros servidores.
Como instalar a biblioteca de cliente PHP do Google Data
Agora que você tem uma versão funcional do PHP instalada, é hora de instalar a biblioteca de cliente. A biblioteca de cliente faz parte do Zend Framework de código aberto, mas também pode ser baixada como uma versão independente. Se você já tiver uma versão do Zend Framework instalada (1.6 ou mais recente), pule a instalação, porque a Biblioteca de cliente de dados do Google está incluída. No entanto, usar a versão mais recente do framework garante que você tenha todos os recursos e correções de bugs mais recentes disponíveis. Por isso, é recomendável.
Ao fazer o download da estrutura completa, você terá acesso não apenas à biblioteca de cliente de dados do Google, mas também ao restante da estrutura. A biblioteca de cliente usa algumas outras classes que fazem parte do Zend Framework completo, mas não é necessário baixar todo o framework, já que as classes estão incluídas no download independente.
- Faça o download dos arquivos da biblioteca de cliente de dados do Google. Pesquise "APIs de dados do Google" nessa página.
- Descompacte os arquivos baixados. Quatro subdiretórios precisam ser criados:
demos: exemplos de aplicativosdocumentation: documentação dos arquivos da biblioteca de cliente.library: os arquivos de origem da biblioteca de cliente real.tests: arquivos de teste de unidade para testes automatizados.
- Adicione o local da pasta
libraryao seu caminho do PHP (consulte a próxima seção)
Verificando se você pode acessar os arquivos da biblioteca de cliente
A última etapa é garantir que você possa referenciar e incluir os arquivos da biblioteca de cliente PHP no diretório em que está criando o projeto. Isso é feito definindo a variável include_path no arquivo de configuração do PHP (php.ini). A variável include_path contém vários locais de diretório que o PHP procura quando você emite uma instrução require ou include que extrai classes, bibliotecas ou arquivos externos para o script atual, semelhante à instrução import em Java. Você precisa anexar o local dos arquivos da biblioteca de cliente ao que já foi definido no seu include_path. Isso pode ser feito de duas maneiras, ambas explicadas em detalhes abaixo:
- Defina permanentemente a diretiva
include_pathno arquivo de configuraçãophp.inina linha de comando. Isso exige acesso ao shell e permissões de gravação. - Defina a variável de caminho
include_pathno nível "por diretório". Isso exige o servidor da Web Apache e a capacidade de criar arquivos.htaccess. - Use a função
set_include_path()para definir dinamicamente o caminho de inclusão nos seus scripts. Ele pode ser definido dinamicamente em cada um dos seus arquivos .php.
Se você tiver acesso ao shell e permissões de gravação no arquivo php.ini (ou se estiver escrevendo código na máquina local), siga as instruções no Apêndice A. Se você estiver usando o servidor da Web Apache e puder criar arquivos .htaccess, defina a variável include_path no nível "por diretório". Isso significa que todos os arquivos no diretório em que você está trabalhando podem referenciar automaticamente o diretório da biblioteca de cliente.
É possível especificar opções de configuração do PHP, conforme mostrado no snippet abaixo:
# This works for PHP5 in both Apache versions 1 and 2 <IfModule mod_php5.c> php_value include_path ".:/usr/local/lib/php:/path/to/ZendGdata/library" </IfModule>
Observação:consulte o Manual do PHP para mais informações sobre como mudar as configurações.
Se você não tiver acesso ao shell do servidor e não puder modificar ou criar arquivos .htaccess, use sempre a função set_include_path. Talvez você já tenha um valor definido para include_path. Por isso, é recomendável seguir o modelo abaixo para anexar os novos valores em vez de substituir todo o caminho:
$clientLibraryPath = '/path/to/ZendGdata/library'; $oldPath = set_include_path(get_include_path() . PATH_SEPARATOR . $clientLibraryPath);
Observação:consulte as páginas do manual do PHP para mais detalhes sobre a função set_include_path.
Executar o verificador de instalação do PHP
Para verificar se o caminho de inclusão foi definido corretamente, execute o script Verificador de instalação do PHP. Basta copiar e colar o conteúdo desse arquivo em um novo arquivo em um diretório acessível pela Web no seu servidor e navegar até ele no navegador. Se você vir uma saída semelhante à abaixo, tudo foi configurado corretamente e você está pronto para usar a biblioteca de cliente do PHP:
Se você encontrar erros (como na captura de tela abaixo), siga a orientação. Talvez você não tenha as extensões ou o caminho ainda não esteja definido corretamente. Talvez seja necessário reiniciar o servidor para que as mudanças entrem em vigor. Isso só se aplica se você estiver modificando o arquivo php.ini. A captura de tela abaixo mostra que o include_path está definido como /path/to/nowhere:
Observação:o verificador de instalação do PHP verifica o seguinte em sucessão: (1) as extensões PHP necessárias estão instaladas? (2) O include_path aponta para o diretório da biblioteca de cliente PHP? (3) É possível fazer conexões SSL? Por fim, é possível fazer uma conexão com a API YouTube Data? Se um teste específico falhar, os outros não serão executados.
Agora que a biblioteca de cliente está instalada, é hora de tentar executar as amostras.
Como executar as amostras
Na raiz do diretório Zend/Gdata, há uma pasta de demonstrações, que são exemplos para ajudar você a começar. Alguns desses exemplos foram criados para serem executados na linha de comando, como demos/Zend/Gdata/Blogger.php e demos/Zend/Gdata/Spreadsheet-ClientLogin.php, e podem ser executados com php /path/to/example. As amostras restantes podem ser executadas na linha de comando e em um navegador da Web. Se você quiser visualizá-los em um navegador, coloque-os no diretório que usaria para veicular páginas da Web. Esses exemplos dão uma ideia básica de como escrever e executar um aplicativo do Google Data, mas, quando você estiver pronto para mais, há outros recursos para o programador curioso.
Observação:se quiser ver as demonstrações baseadas na Web on-line, acesse googlecodesamples.com e procure os aplicativos PHP.
Onde saber mais
Os melhores lugares para procurar informações sobre as classes que fazem parte da biblioteca de cliente são o guia de referência da API no site do Zend Framework. Selecione o pacote Zend_Gdata no menu suspenso.
Neste ponto, você já pode começar a programar. Então, crie alguns aplicativos incríveis. Estamos ansiosos para ver seus resultados!
Confira os guias para desenvolvedores de PHP dos seguintes serviços:
Como a biblioteca de cliente PHP é um projeto de código aberto, o suporte para mais APIs é adicionado continuamente. Cada serviço tem um grupo de suporte próprio. Consulte nossa entrada de perguntas frequentes para ver uma lista dos grupos de suporte disponíveis.
Se você precisar de ajuda para resolver problemas com suas chamadas de API, há artigos disponíveis sobre depuração de solicitações de API usando ferramentas de captura de tráfego de rede e sobre uso de servidores proxy com as APIs de dados do Google. Há também alguns artigos externos disponíveis sobre como instalar o XAMPP no Linux e como instalar o XAMPP no Windows. Além de todos esses artigos, confira as postagens sobre a biblioteca de cliente PHP no blog de dicas da API Google Data.
Apêndice A: editar o caminho do PHP no arquivo de configuração php.ini
O caminho do PHP é uma variável que contém uma lista de locais que o PHP pesquisa quando procura bibliotecas adicionais durante o carregamento. Para que o PHP possa carregar e acessar os arquivos da biblioteca de cliente PHP de dados do Google na sua máquina ou servidor, eles precisam ser colocados em um local conhecido pelo PHP. Ou, como alternativa, o local dos arquivos precisa ser anexado ao seu caminho do PHP. As mudanças no arquivo php.ini geralmente exigem a reinicialização do servidor. Você pode sempre verificar o valor atual da variável include_path acessando a página de informações do PHP mencionada anteriormente. Procure a célula Arquivo de configuração carregado na primeira tabela e encontre o caminho na coluna à direita.
Observação:se você estiver usando o PHP na linha de comando, talvez seja necessário modificar outra variável de caminho. Consulte o Apêndice B: como usar o PHP na linha de comando.
Depois de encontrar o arquivo php.ini, siga estas etapas para anexar ao caminho.
- Abra o arquivo
php.inino seu editor de texto favorito. - Localize a linha que faz referência ao caminho do PHP. Ela deve começar com
include_path. - Adicione o caminho em que você armazenou o Zend Framework à lista de locais já presentes, adicionando o novo caminho com o separador designado para seu SO (
:em sistemas semelhantes ao Unix,;no Windows). Um caminho correto em sistemas semelhantes ao Unix teria esta aparência:/path1:/path2:/usr/local/lib/php/library
\path1;\path2;\php\library
- Salve e feche o arquivo.
Observação:no Mac OS X, o Finder não permite o acesso a arquivos que estão em locais do sistema, como o diretório /etc. Portanto, talvez seja mais fácil editá-los usando um editor de linha de comando, como vi ou pico. Para fazer isso, use um comando como: pico /path/to/php.ini.
Apêndice B: como usar o PHP na linha de comando
A partir da versão 5 do PHP, há um utilitário de linha de comando disponível no PHP, conhecido como CLI para "interpretador de linha de comando". Usar esse utilitário permite que scripts PHP sejam executados na linha de comando. Isso pode ser útil se você estiver executando o PHP localmente na sua máquina e procurando maneiras de testar rapidamente alguns scripts. No seu servidor, isso exige acesso ao shell. É importante observar que o PHP geralmente usa dois arquivos php.ini separados. Um contém as opções de configuração do PHP em execução no servidor, e outro para as configurações que o PHP usa ao ser executado na linha de comando. Se você quiser executar os aplicativos de demonstração da linha de comando na biblioteca de cliente, também precisará modificar o arquivo php.ini da linha de comando.
Para localizá-lo, digite os seguintes comandos em sistemas semelhantes ao Unix (Mac OS X, Linux e outros):
php -i | grep php.ini
Esse comando vai resultar na exibição das seguintes informações no terminal:
Configuration File (php.ini) Path => /etc/php5/cli Loaded Configuration File => /etc/php5/cli/php.ini
Observação:os locais reais dos caminhos (/etc/php...) podem variar no seu sistema.
Apêndice C: dicas e soluções
Esta seção contém um breve resumo de alguns dos problemas que os desenvolvedores descobriram ao trabalhar com PHP e as soluções adequadas.
Problema com a extensão dom-xml no XAMPP
A biblioteca de cliente PHP usa as classes DOMDocument para transformar solicitações e respostas XML em objetos PHP. A extensão dom-xml pode causar problemas com o processamento de XML e resultar em transformações incorretas. Alguns dos nossos desenvolvedores descobriram que, ao usar o XAMPP, o construtor DOMDocument é substituído por uma chamada de função mais antiga, conforme explicado no site do PHP. Para corrigir esse problema, verifique se o processamento de XML não foi substituído no arquivo php.ini. Remova as referências a php_domxml.dll do arquivo de configuração.
As solicitações estão atingindo o tempo limite ao usar a biblioteca de cliente
Se você estiver usando a biblioteca de cliente para fazer solicitações grandes, como o envio de vídeos para a API YouTube Data, talvez seja necessário mudar o parâmetro timeout na classe Zend_Http_Client. Isso pode ser feito facilmente transmitindo um parâmetro $config durante a instanciação, que define o valor timeout como algo diferente do padrão de 10 segundos:
// assuming your Zend_Http_Client already exists as $httpClient
// and that you want to change the timeout from the 10 second default to 30 seconds
$config = array('timeout' => 30);
$httpClient->setConfig($config);
Alguns provedores de hospedagem não permitem conexões HTTPS nos servidores deles.
Ficamos sabendo que alguns provedores de hospedagem não permitem conexões https dos servidores padrão. Se você receber uma mensagem de erro semelhante à abaixo, talvez seja necessário fazer suas conexões https por um proxy seguro:
Unable to Connect to sslv2://www.google.com:443. Error #110: Connection timed out
Seu provedor de hospedagem tem informações sobre o endereço real do servidor proxy a ser usado. O snippet abaixo demonstra como uma configuração de proxy personalizada pode ser usada com a biblioteca de cliente do PHP:
// Load the proxy adapter class in addition to the other required classes
Zend_Loader::loadClass('Zend_Http_Client_Adapter_Proxy');
// Configure the proxy connection with your hostname and portnumber
$config = array(
'adapter' => 'Zend_Http_Client_Adapter_Proxy',
'proxy_host' => 'your.proxy.server.net',
'proxy_port' => 3128
);
// A simple https request would be an attempt to authenticate via ClientLogin
$proxiedHttpClient = new Zend_Http_Client('http://www.google.com:443', $config);
$username = 'foo@example.com';
$password = 'barbaz';
// The service name would depend on what API you are interacting with, here
// we are using the Google DocumentsList Data API
$service = Zend_Gdata_Docs::AUTH_SERVICE_NAME;
// Try to perform the ClientLogin authentication using our proxy client.
// If there is an error, we exit since it doesn't make sense to go on.
try {
// Note that we are creating another Zend_Http_Client
// by passing our proxied client into the constructor.
$httpClient = Zend_Gdata_ClientLogin::getHttpClient(
$username, $password, $service, $proxiedHttpClient);
} catch (Zend_Gdata_App_HttpException $httpException) {
// You may want to handle this differently in your application
exit("An error occurred trying to connect to the proxy server\n" .
$httpException->getMessage() . "\n");
}
Histórico de revisões
1º de outubro de 2008
Atualizado por Jochen Hartmann. Esta atualização contém as seguintes alterações:
- Tornamos a configuração do PHP para servidores da Web mais clara ao mover para um apêndice as seções que se referem ao PHP de linha de comando.
- Adicionada observação sobre vários arquivos de configuração php.ini.
- Adicionamos seções sobre como definir dinamicamente o include_path.
- Adição de uma seção sobre o script de verificação da instalação.
- Adicionamos um link para exemplos on-line.
- Adição de links para XAMPP e MAMP.
- Adicionamos um apêndice "Dicas e soluções".