google api php client
v2.18.0
REMARQUE : veuillez d'abord vérifier si le package que vous souhaitez installer est disponible dans notre liste de packages Google Cloud, car ce sont les bibliothèques recommandées.
La bibliothèque cliente des API Google vous permet de travailler avec des API Google telles que Gmail, Drive ou YouTube sur votre serveur.
Ces bibliothèques clientes sont officiellement prises en charge par Google. Cependant, les bibliothèques sont considérées comme complètes et sont en mode maintenance. Cela signifie que nous corrigerons les bogues critiques et les problèmes de sécurité, mais n'ajouterons aucune nouvelle fonctionnalité.
Pour les API Google Cloud Platform telles que Datastore, Cloud Storage, Pub/Sub et Compute Engine, nous vous recommandons d'utiliser les bibliothèques clientes Google Cloud. Pour obtenir la liste complète des bibliothèques clientes Google Cloud prises en charge, consultez googleapis/google-cloud-php.
Le dossier docs fournit des guides détaillés sur l'utilisation de cette bibliothèque.
Vous pouvez utiliser Composer ou simplement télécharger la version
La méthode préférée est via composer. Suivez les instructions d'installation si Composer n'est pas déjà installé.
Une fois composer installé, exécutez la commande suivante à la racine de votre projet pour installer cette bibliothèque :
composer require google/apiclient:^2.15.0 Si vous êtes confronté à une erreur de délai d'attente, augmentez le délai d'attente pour composer en ajoutant l'indicateur env comme COMPOSER_PROCESS_TIMEOUT=600 composer install ou vous pouvez le mettre dans la section config du schéma composer :
{
"config": {
"process-timeout": 600
}
}
Enfin, assurez-vous d'inclure le chargeur automatique :
require_once ' /path/to/your-project/vendor/autoload.php ' ; Cette bibliothèque s'appuie sur google/apiclient-services . Cette bibliothèque fournit des wrappers d'API à jour pour un grand nombre d'API Google. Afin que les utilisateurs puissent utiliser les derniers clients API, cette bibliothèque ne s'épingle pas sur une version spécifique de google/apiclient-services . Afin d'éviter l'installation accidentelle de wrappers d'API avec des modifications avec rupture , il est fortement recommandé d'épingler vous-même la dernière version avant d'utiliser cette bibliothèque en production.
Il existe plus de 200 services API Google. Il y a de fortes chances que vous ne les vouliez pas tous. Afin d'éviter d'envoyer ces dépendances avec votre code, vous pouvez exécuter la GoogleTaskComposer::cleanup et spécifier les services que vous souhaitez conserver dans composer.json :
{
"require" : {
"google/apiclient" : " ^2.15.0 "
},
"scripts" : {
"pre-autoload-dump" : " Google \ Task \ Composer::cleanup "
},
"extra" : {
"google/apiclient-services" : [
" Drive " ,
" YouTube "
]
}
} Cet exemple supprimera tous les services autres que « Drive » et « YouTube » lors de l'exécution composer update ou d'une nouvelle composer install .
IMPORTANT : si vous ajoutez à nouveau des services dans composer.json , vous devrez supprimer explicitement le répertoire vendor/google/apiclient-services pour que la modification que vous avez apportée prenne effet :
rm -r vendor/google/apiclient-services
composer update REMARQUE : Cette commande effectue une correspondance exacte avec le nom du service. Par conséquent, pour conserver également YouTubeReporting et YouTubeAnalytics , vous devez ajouter chacun d'eux explicitement :
{
"extra" : {
"google/apiclient-services" : [
" Drive " ,
" YouTube " ,
" YouTubeAnalytics " ,
" YouTubeReporting "
]
}
} Si vous préférez ne pas utiliser composer, vous pouvez télécharger le package dans son intégralité. La page Releases répertorie toutes les versions stables. Téléchargez n'importe quel fichier portant le nom google-api-php-client-[RELEASE_NAME].zip pour un package comprenant cette bibliothèque et ses dépendances.
Décompressez le fichier zip que vous téléchargez et incluez le chargeur automatique dans votre projet :
require_once ' /path/to/google-api-php-client/vendor/autoload.php ' ;Pour des instructions d’installation et de configuration supplémentaires, consultez la documentation.
Consultez le répertoire examples/ pour des exemples des principales fonctionnalités du client. Vous pouvez les afficher dans votre navigateur en exécutant le serveur Web intégré à PHP.
$ php -S localhost:8000 -t examples/
Ensuite, accédez à l'hôte et au port que vous avez spécifiés (dans l'exemple ci-dessus, 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" ;
}Un exemple de ceci peut être vu dans
examples/simple-file-upload.php.
Suivez les instructions pour créer des informations d'identification d'application Web
Téléchargez les informations d'identification JSON
Définissez le chemin d'accès à ces informations d'identification à l'aide de GoogleClient::setAuthConfig :
$ client = new Google Client ();
$ client -> setAuthConfig ( ' /path/to/client_credentials.json ' );Définissez les étendues requises pour l'API que vous allez appeler
$ client -> addScope ( Google Service Drive :: DRIVE );Définir l'URI de redirection de votre application
// 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 );Dans le script gérant l'URI de redirection, échangez le code d'autorisation contre un jeton d'accès :
if ( isset ( $ _GET [ ' code ' ])) {
$ token = $ client -> fetchAccessTokenWithAuthCode ( $ _GET [ ' code ' ]);
}Un exemple de ceci peut être vu dans
examples/service-account.php.
Certaines API (telles que l'API YouTube Data) ne prennent pas en charge les comptes de service. Vérifiez auprès de la documentation spécifique de l'API si les appels d'API renvoient des erreurs 401 ou 403 inattendues.
Suivez les instructions pour créer un compte de service
Téléchargez les informations d'identification JSON
Définissez le chemin d'accès à ces informations d'identification à l'aide de la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS :
putenv ( ' GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json ' );Dites au client Google d'utiliser les informations d'identification de votre compte de service pour s'authentifier :
$ client = new Google Client ();
$ client -> useApplicationDefaultCredentials ();Définissez les étendues requises pour l'API que vous allez appeler
$ client -> addScope ( Google Service Drive :: DRIVE );Si vous disposez d'un accès délégué à l'échelle du domaine au compte de service et que vous souhaitez usurper l'identité d'un compte utilisateur, spécifiez l'adresse e-mail du compte utilisateur à l'aide de la méthode setSubject :
$ client -> setSubject ( $ user_to_impersonate ); Si vous souhaitez utiliser une clé JSON spécifique au lieu d'utiliser la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS , vous pouvez procéder comme suit :
$ jsonKey = [
' type ' => ' service_account ' ,
// ...
];
$ client = new Google Client ();
$ client -> setAuthConfig ( $ jsonKey );Les classes utilisées pour appeler l'API dans google-api-php-client-services sont générées automatiquement. Ils correspondent directement aux requêtes et réponses JSON trouvées dans l'explorateur d'API.
Une requête JSON adressée à l'API Datastore ressemblerait à ceci :
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
}
}En utilisant cette bibliothèque, le même appel ressemblerait à ceci :
// 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 );Cependant, comme chaque propriété de l'API JSON possède une classe générée correspondante, le code ci-dessus pourrait également être écrit comme ceci :
// 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 );La méthode utilisée est une question de préférence, mais il sera très difficile d'utiliser cette bibliothèque sans comprendre au préalable la syntaxe JSON de l'API , il est donc recommandé de consulter l'explorateur d'API avant d'utiliser l'un des services ici.
Si l'authentification Google est souhaitée pour les applications externes, ou si une API Google n'est pas encore disponible dans cette bibliothèque, les requêtes HTTP peuvent être effectuées directement.
Si vous installez ce client uniquement pour authentifier vos propres requêtes client HTTP, vous devez plutôt utiliser google/auth .
La méthode authorize renvoie un client Guzzle autorisé, donc toute demande faite à l'aide du client contiendra l'autorisation correspondante.
// 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 ' );Il est recommandé d'utiliser une autre bibliothèque de mise en cache pour améliorer les performances. Cela peut être fait en transmettant une bibliothèque compatible PSR-6 au client :
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 );Dans cet exemple, nous utilisons PHP Cache. Ajoutez ceci à votre projet avec composer :
composer require cache/filesystem-adapter
Lors de l'utilisation de jetons d'actualisation ou d'informations d'identification de compte de service, il peut être utile d'effectuer certaines actions lorsqu'un nouveau jeton d'accès est accordé. Pour ce faire, transmettez un callable à la méthode setTokenCallback sur le client :
$ 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 );Il est souvent très utile de déboguer vos appels API en visualisant la requête HTTP brute. Cette bibliothèque prend en charge l'utilisation de Charles Web Proxy. Téléchargez et exécutez Charles, puis capturez tout le trafic HTTP via Charles avec le code suivant :
// 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 );Désormais, tous les appels effectués par cette bibliothèque apparaîtront dans l'interface utilisateur de Charles.
Une étape supplémentaire est requise dans Charles pour afficher les requêtes SSL. Accédez à Charles > Proxy > Paramètres de proxy SSL et ajoutez le domaine que vous souhaitez capturer. Dans le cas des API Google, il s'agit généralement *.googleapis.com .
Le client API Google utilise Guzzle comme client HTTP par défaut. Cela signifie que vous pouvez contrôler vos requêtes HTTP de la même manière que vous le feriez pour n'importe quelle application utilisant Guzzle.
Disons, par exemple, que nous souhaitions appliquer un référent à chaque requête.
use GuzzleHttp Client ;
$ httpClient = new Client ([
' headers ' => [
' referer ' => ' mysite.com '
]
]);
$ client = new Google Client ();
$ client -> setHttpClient ( $ httpClient );D'autres fonctionnalités de Guzzle telles que les gestionnaires et le middleware offrent encore plus de contrôle.
Lorsque vous utilisez OAuth2 3LO (par exemple, vous êtes un client demandant des informations d'identification à un tiers, comme dans l'exemple simple de téléchargement de fichier), vous souhaiterez peut-être profiter du consentement partiel.
Pour permettre aux clients d'accorder uniquement certaines étendues dans l'écran OAuth2, transmettez le paramètre querystring pour enable_serial_consent lors de la génération de l'URL d'autorisation :
$ authUrl = $ client -> createAuthUrl ( $ scope , [ ' enable_serial_consent ' => ' true ' ]); Une fois le flux terminé, vous pouvez voir quelles étendues ont été accordées en appelant getGrantedScope sur l'objet 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
Veuillez consulter la page de contribution pour plus d'informations. En particulier, nous aimons les pull request - mais assurez-vous de signer le contrat de licence du contributeur.
Pour obtenir de l'aide concernant la bibliothèque, le meilleur endroit pour demander est via la balise google-api-php-client sur StackOverflow : https://stackoverflow.com/questions/tagged/google-api-php-client
S'il existe un bogue spécifique avec la bibliothèque, veuillez signaler un problème dans le suivi des problèmes GitHub, y compris un exemple du code défaillant et toute erreur spécifique récupérée. Des demandes de fonctionnalités peuvent également être déposées, à condition qu'il s'agisse de demandes de bibliothèque principale et non spécifiques à une API : pour celles-ci, reportez-vous à la documentation de chaque API pour connaître le meilleur endroit pour déposer les demandes. Veuillez essayer de fournir une déclaration claire du problème que la fonctionnalité résoudrait.
Si X est une fonctionnalité de la bibliothèque, rangez-le ! Si X est un exemple d'utilisation d'un service spécifique, le meilleur endroit où s'adresser est de s'adresser aux équipes chargées de ces API spécifiques. Notre préférence est de créer un lien vers leurs exemples plutôt que de les ajouter à la bibliothèque, car elles peuvent ensuite les épingler à des versions spécifiques de la bibliothèque. Si vous avez des exemples d'autres API, faites-le-nous savoir et nous ajouterons volontiers un lien vers le README ci-dessus !
Les classes GoogleService sont généralement générées automatiquement à partir des documents de découverte des API : https://developers.google.com/discovery/. Parfois, de nouvelles fonctionnalités sont ajoutées aux API avec des noms inhabituels, ce qui peut entraîner des styles de dénomination inattendus ou non standard dans les classes PHP.
Certains services renvoient XML ou similaire par défaut, plutôt que JSON, ce que prend en charge la bibliothèque. Vous pouvez demander une réponse JSON en ajoutant un argument « alt » aux paramètres facultatifs qui est normalement le dernier argument d'un appel de méthode :
$ opt_params = array (
' alt ' => " json "
); La bibliothèque supprime les valeurs NULL des objets envoyés aux API Google car il s'agit de la valeur par défaut de toutes les propriétés non initialisées. Pour contourner ce problème, définissez le champ que vous souhaitez null sur GoogleModel::NULL_VALUE . Il s'agit d'un espace réservé qui sera remplacé par un vrai null lorsqu'il sera envoyé via le réseau.
Exécutez les tests PHPUnit avec PHPUnit. Vous pouvez configurer une clé API et un jeton dans BaseTest.php pour exécuter tous les appels, mais cela nécessitera une configuration sur la console de développement Google.
phpunit tests/
Pour vérifier les violations de style de codage, exécutez
vendor/bin/phpcs src --standard=style/ruleset.xml -np
Pour corriger automatiquement les violations de style de codage (réparables), exécutez
vendor/bin/phpcbf src --standard=style/ruleset.xml
