google api php client
v2.18.0
NOTA : verifique primeiro se o pacote que você deseja instalar está disponível em nossa lista de pacotes de nuvem do Google, pois essas são as bibliotecas recomendadas.
A biblioteca cliente da API do Google permite que você trabalhe com APIs do Google, como Gmail, Drive ou YouTube, em seu servidor.
Essas bibliotecas cliente são oficialmente suportadas pelo Google. Porém, as bibliotecas são consideradas completas e estão em modo de manutenção. Isso significa que abordaremos bugs críticos e problemas de segurança, mas não adicionaremos novos recursos.
Para APIs do Google Cloud Platform, como Datastore, Cloud Storage, Pub/Sub e Compute Engine, recomendamos o uso das bibliotecas de cliente do Google Cloud. Para obter uma lista completa das bibliotecas de cliente do Google Cloud compatíveis, consulte googleapis/google-cloud-php.
A pasta docs fornece guias detalhados para usar esta biblioteca.
Você pode usar o Composer ou simplesmente baixar o lançamento
O método preferido é via compositor. Siga as instruções de instalação se ainda não tiver o compositor instalado.
Depois que o compositor estiver instalado, execute o seguinte comando na raiz do seu projeto para instalar esta biblioteca:
composer require google/apiclient:^2.15.0 Se você estiver enfrentando um erro de tempo limite, aumente o tempo limite do compositor adicionando o sinalizador env como COMPOSER_PROCESS_TIMEOUT=600 composer install ou você pode colocar isso na seção config do esquema do compositor:
{
"config": {
"process-timeout": 600
}
}
Finalmente, certifique-se de incluir o autoloader:
require_once ' /path/to/your-project/vendor/autoload.php ' ; Esta biblioteca depende de google/apiclient-services . Essa biblioteca fornece wrappers de API atualizados para um grande número de APIs do Google. Para que os usuários possam fazer uso dos clientes API mais recentes, esta biblioteca não se fixa a uma versão específica de google/apiclient-services . Para evitar a instalação acidental de wrappers de API com alterações significativas , é altamente recomendável que você mesmo fixe a versão mais recente antes de usar esta biblioteca em produção.
Existem mais de 200 serviços API do Google. As chances são boas de que você não queira todos eles. Para evitar o envio dessas dependências com seu código, você pode executar a tarefa GoogleTaskComposer::cleanup e especificar os serviços que deseja manter em composer.json :
{
"require" : {
"google/apiclient" : " ^2.15.0 "
},
"scripts" : {
"pre-autoload-dump" : " Google \ Task \ Composer::cleanup "
},
"extra" : {
"google/apiclient-services" : [
" Drive " ,
" YouTube "
]
}
} Este exemplo removerá todos os serviços, exceto "Drive" e "YouTube", quando composer update ou uma nova composer install for executada.
IMPORTANTE : se você adicionar algum serviço novamente em composer.json , precisará remover o diretório vendor/google/apiclient-services explicitamente para que a alteração feita tenha efeito:
rm -r vendor/google/apiclient-services
composer update NOTA : Este comando executa uma correspondência exata no nome do serviço, portanto, para manter YouTubeReporting e YouTubeAnalytics também, você precisará adicionar cada um deles explicitamente:
{
"extra" : {
"google/apiclient-services" : [
" Drive " ,
" YouTube " ,
" YouTubeAnalytics " ,
" YouTubeReporting "
]
}
} Se preferir não usar o compositor, você pode baixar o pacote completo. A página Releases lista todas as versões estáveis. Baixe qualquer arquivo com o nome google-api-php-client-[RELEASE_NAME].zip para um pacote incluindo esta biblioteca e suas dependências.
Descompacte o arquivo zip baixado e inclua o autoloader em seu projeto:
require_once ' /path/to/google-api-php-client/vendor/autoload.php ' ;Para obter instruções adicionais de instalação e configuração, consulte a documentação.
Consulte o diretório examples/ para obter exemplos dos principais recursos do cliente. Você pode visualizá-los em seu navegador executando o servidor web integrado do php.
$ php -S localhost:8000 -t examples/
E então navegue até o host e a porta que você especificou (no exemplo acima, http://localhost:8000 ).
// include your composer dependencies
require_once ' vendor/autoload.php ' ;
$ client = new Google Client ();
$ client -> setApplicationName ( " Client_Library_Examples " );
$ client -> setDeveloperKey ( " YOUR_APP_KEY " );
$ service = new Google Service Books ( $ client );
$ query = ' Henry David Thoreau ' ;
$ optParams = [
' filter ' => ' free-ebooks ' ,
];
$ results = $ service -> volumes -> listVolumes ( $ query , $ optParams );
foreach ( $ results -> getItems () as $ item ) {
echo $ item [ ' volumeInfo ' ][ ' title ' ], " <br /> n" ;
}Um exemplo disso pode ser visto em
examples/simple-file-upload.php.
Siga as instruções para criar credenciais de aplicativos da Web
Baixe as credenciais JSON
Defina o caminho para essas credenciais usando GoogleClient::setAuthConfig :
$ client = new Google Client ();
$ client -> setAuthConfig ( ' /path/to/client_credentials.json ' );Defina os escopos necessários para a API que você irá chamar
$ client -> addScope ( Google Service Drive :: DRIVE );Defina o URI de redirecionamento do seu aplicativo
// Your redirect URI can be any registered URI, but in this example
// we redirect back to this same page
$ redirect_uri = ' http:// ' . $ _SERVER [ ' HTTP_HOST ' ] . $ _SERVER [ ' PHP_SELF ' ];
$ client -> setRedirectUri ( $ redirect_uri );No script que trata o URI de redirecionamento, troque o código de autorização por um token de acesso:
if ( isset ( $ _GET [ ' code ' ])) {
$ token = $ client -> fetchAccessTokenWithAuthCode ( $ _GET [ ' code ' ]);
}Um exemplo disso pode ser visto em
examples/service-account.php.
Algumas APIs (como a API de dados do YouTube) não oferecem suporte a contas de serviço. Verifique na documentação específica da API se as chamadas de API retornam erros 401 ou 403 inesperados.
Siga as instruções para criar uma conta de serviço
Baixe as credenciais JSON
Defina o caminho para essas credenciais usando a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS :
putenv ( ' GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json ' );Diga ao cliente Google para usar as credenciais da sua conta de serviço para autenticação:
$ client = new Google Client ();
$ client -> useApplicationDefaultCredentials ();Defina os escopos necessários para a API que você irá chamar
$ client -> addScope ( Google Service Drive :: DRIVE );Se você delegou acesso de todo o domínio à conta de serviço e deseja representar uma conta de usuário, especifique o endereço de e-mail da conta de usuário usando o método setSubject:
$ client -> setSubject ( $ user_to_impersonate ); Se quiser uma chave JSON específica em vez de usar a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS , você pode fazer o seguinte:
$ jsonKey = [
' type ' => ' service_account ' ,
// ...
];
$ client = new Google Client ();
$ client -> setAuthConfig ( $ jsonKey );As classes usadas para chamar a API em google-api-php-client-services são geradas automaticamente. Eles mapeiam diretamente para as solicitações e respostas JSON encontradas no APIs Explorer.
Uma solicitação JSON para a API Datastore ficaria assim:
POST https://datastore.googleapis.com/v1beta3/projects/YOUR_PROJECT_ID:runQuery?key=YOUR_API_KEY
{
"query" : {
"kind" : [{
"name" : " Book "
}],
"order" : [{
"property" : {
"name" : " title "
},
"direction" : " descending "
}],
"limit" : 10
}
}Usando esta biblioteca, a mesma chamada seria mais ou menos assim:
// create the datastore service class
$ datastore = new Google Service Datastore ( $ client );
// build the query - this maps directly to the JSON
$ query = new Google Service Datastore Query ([
' kind ' => [
[
' name ' => ' Book ' ,
],
],
' order ' => [
' property ' => [
' name ' => ' title ' ,
],
' direction ' => ' descending ' ,
],
' limit ' => 10 ,
]);
// build the request and response
$ request = new Google Service Datastore RunQueryRequest ([ ' query ' => $ query ]);
$ response = $ datastore -> projects -> runQuery ( ' YOUR_DATASET_ID ' , $ request );Porém, como cada propriedade da API JSON possui uma classe gerada correspondente, o código acima também poderia ser escrito assim:
// create the datastore service class
$ datastore = new Google Service Datastore ( $ client );
// build the query
$ request = new Google Service Datastore_RunQueryRequest ();
$ query = new Google Service Datastore Query ();
// - set the order
$ order = new Google Service Datastore_PropertyOrder ();
$ order -> setDirection ( ' descending ' );
$ property = new Google Service Datastore PropertyReference ();
$ property -> setName ( ' title ' );
$ order -> setProperty ( $ property );
$ query -> setOrder ([ $ order ]);
// - set the kinds
$ kind = new Google Service Datastore KindExpression ();
$ kind -> setName ( ' Book ' );
$ query -> setKinds ([ $ kind ]);
// - set the limit
$ query -> setLimit ( 10 );
// add the query to the request and make the request
$ request -> setQuery ( $ query );
$ response = $ datastore -> projects -> runQuery ( ' YOUR_DATASET_ID ' , $ request );O método utilizado é uma questão de preferência, mas será muito difícil utilizar esta biblioteca sem primeiro entender a sintaxe JSON da API , por isso é recomendado dar uma olhada no APIs Explorer antes de utilizar qualquer um dos serviços aqui.
Se a autenticação do Google for desejada para aplicativos externos ou se uma API do Google ainda não estiver disponível nesta biblioteca, as solicitações HTTP poderão ser feitas diretamente.
Se você estiver instalando este cliente apenas para autenticar suas próprias solicitações de cliente HTTP, você deverá usar google/auth .
O authorize retorna um Guzzle Client autorizado, portanto qualquer solicitação feita usando o cliente conterá a autorização correspondente.
// create the Google client
$ client = new Google Client ();
/**
* Set your method for authentication. Depending on the API, This could be
* directly with an access token, API key, or (recommended) using
* Application Default Credentials.
*/
$ client -> useApplicationDefaultCredentials ();
$ client -> addScope ( Google Service Plus :: PLUS_ME );
// returns a Guzzle HTTP Client
$ httpClient = $ client -> authorize ();
// make an HTTP request
$ response = $ httpClient -> get ( ' https://www.googleapis.com/plus/v1/people/me ' );Recomenda-se usar outra biblioteca de cache para melhorar o desempenho. Isso pode ser feito passando uma biblioteca compatível com PSR-6 para o cliente:
use League Flysystem Adapter Local ;
use League Flysystem Filesystem ;
use Cache Adapter Filesystem FilesystemCachePool ;
$ filesystemAdapter = new Local ( __DIR__ . ' / ' );
$ filesystem = new Filesystem ( $ filesystemAdapter );
$ cache = new FilesystemCachePool ( $ filesystem );
$ client -> setCache ( $ cache );Neste exemplo usamos PHP Cache. Adicione isto ao seu projeto com o compositor:
composer require cache/filesystem-adapter
Ao usar Tokens de Atualização ou Credenciais de Conta de Serviço, pode ser útil executar alguma ação quando um novo token de acesso for concedido. Para fazer isso, passe um callable para o método setTokenCallback no cliente:
$ logger = new Monolog Logger ();
$ tokenCallback = function ( $ cacheKey , $ accessToken ) use ( $ logger ) {
$ logger -> debug ( sprintf ( ' new access token received at cache key %s ' , $ cacheKey ));
};
$ client -> setTokenCallback ( $ tokenCallback );Muitas vezes é muito útil depurar suas chamadas de API visualizando a solicitação HTTP bruta. Esta biblioteca oferece suporte ao uso do Charles Web Proxy. Baixe e execute Charles e capture todo o tráfego HTTP por meio de Charles com o seguinte código:
// FOR DEBUGGING ONLY
$ httpClient = new GuzzleHttp Client ([
' proxy ' => ' localhost:8888 ' , // by default, Charles runs on localhost port 8888
' verify ' => false , // otherwise HTTPS requests will fail.
]);
$ client = new Google Client ();
$ client -> setHttpClient ( $ httpClient );Agora todas as chamadas feitas por esta biblioteca aparecerão na UI do Charles.
Uma etapa adicional é necessária no Charles para visualizar as solicitações SSL. Vá para Charles > Proxy > Configurações de proxy SSL e adicione o domínio que deseja capturar. No caso das APIs do Google, geralmente é *.googleapis.com .
O cliente API do Google usa Guzzle como cliente HTTP padrão. Isso significa que você pode controlar suas solicitações HTTP da mesma maneira que faria com qualquer aplicativo que usa o Guzzle.
Digamos, por exemplo, que desejamos aplicar um referenciador a cada solicitação.
use GuzzleHttp Client ;
$ httpClient = new Client ([
' headers ' => [
' referer ' => ' mysite.com '
]
]);
$ client = new Google Client ();
$ client -> setHttpClient ( $ httpClient );Outros recursos do Guzzle, como Handlers e Middleware, oferecem ainda mais controle.
Ao usar o OAuth2 3LO (por exemplo, você é um cliente que solicita credenciais de terceiros, como no exemplo de upload de arquivo simples), você pode querer aproveitar as vantagens do Consentimento Parcial.
Para permitir que os clientes concedam apenas determinados escopos na tela do OAuth2, passe o parâmetro querystring para enable_serial_consent ao gerar o URL de autorização:
$ authUrl = $ client -> createAuthUrl ( $ scope , [ ' enable_serial_consent ' => ' true ' ]); Depois que o fluxo for concluído, você poderá ver quais escopos foram concedidos chamando getGrantedScope no objeto OAuth2:
// Space-separated string of granted scopes if it exists, otherwise null.
echo $ client -> getOAuth2Service ()-> getGrantedScope ();YouTube: https://github.com/youtube/api-samples/tree/master/php
Por favor, consulte a página de contribuição para mais informações. Em particular, adoramos solicitações pull - mas certifique-se de assinar o contrato de licença do contribuidor.
Para suporte com a biblioteca, o melhor lugar para perguntar é através da tag google-api-php-client no StackOverflow: https://stackoverflow.com/questions/tagged/google-api-php-client
Se houver um bug específico com a biblioteca, registre um problema no rastreador de problemas do GitHub, incluindo um exemplo do código com falha e quaisquer erros específicos recuperados. As solicitações de recursos também podem ser arquivadas, desde que sejam solicitações da biblioteca principal e não específicas da API: para essas, consulte a documentação das APIs individuais para saber o melhor local para registrar as solicitações. Tente fornecer uma declaração clara do problema que o recurso resolveria.
Se X for um recurso da biblioteca, arquive! Se X for um exemplo de uso de um serviço específico, o melhor lugar para ir é às equipes dessas APIs específicas - nossa preferência é vincular seus exemplos em vez de adicioná-los à biblioteca, pois eles podem então fixar versões específicas de a biblioteca. Se você tiver algum exemplo para outras APIs, informe-nos e teremos prazer em adicionar um link para o README acima!
As classes GoogleService geralmente são geradas automaticamente a partir dos documentos de descoberta da API: https://developers.google.com/discovery/. Às vezes, novos recursos são adicionados às APIs com nomes incomuns, o que pode causar alguns estilos de nomenclatura inesperados ou fora do padrão nas classes PHP.
Alguns serviços retornam XML ou similar por padrão, em vez de JSON, que é o que a biblioteca suporta. Você pode solicitar uma resposta JSON adicionando um argumento 'alt' aos parâmetros opcionais que normalmente é o último argumento de uma chamada de método:
$ opt_params = array (
' alt ' => " json "
); A biblioteca remove nulos dos objetos enviados às APIs do Google, pois é o valor padrão de todas as propriedades não inicializadas. Para contornar isso, defina o campo que você deseja anular como GoogleModel::NULL_VALUE . Este é um espaço reservado que será substituído por um verdadeiro nulo quando enviado pela rede.
Execute os testes do PHPUnit com PHPUnit. Você pode configurar uma chave de API e um token em BaseTest.php para executar todas as chamadas, mas isso exigirá alguma configuração no Google Developer Console.
phpunit tests/
Para verificar violações de estilo de codificação, execute
vendor/bin/phpcs src --standard=style/ruleset.xml -np
Para corrigir automaticamente violações de estilo de codificação (corrigíveis), execute
vendor/bin/phpcbf src --standard=style/ruleset.xml
