google api php client
v2.18.0
注意：请首先检查您要安装的软件包是否在我们的 Google 云软件包列表中可用，因为这些是推荐的库。
Google API 客户端库使您能够在服务器上使用 Google API，例如 Gmail、Drive 或 YouTube。
这些客户端库由 Google 官方支持。但是，这些库被认为是完整的并且处于维护模式。这意味着我们将解决关键错误和安全问题，但不会添加任何新功能。
对于 Google Cloud Platform API（例如 Datastore、Cloud Storage、Pub/Sub 和 Compute Engine），我们建议使用 Google Cloud 客户端库。有关受支持的 Google Cloud 客户端库的完整列表，请参阅 googleapis/google-cloud-php。
docs 文件夹提供了使用此库的详细指南。
您可以使用Composer或直接下载版本
首选方法是通过 Composer。如果您尚未安装 Composer，请按照安装说明进行操作。
安装 Composer 后，在项目根目录中执行以下命令来安装该库：
composer require google/apiclient:^2.15.0如果您遇到超时错误，则可以通过添加 env 标志为COMPOSER_PROCESS_TIMEOUT=600 composer install来增加 Composer 的超时，或者可以将其放在 Composer 架构的config部分中：
{
"config": {
"process-timeout": 600
}
}
最后，请确保包含自动加载器：
require_once ' /path/to/your-project/vendor/autoload.php ' ;该库依赖于google/apiclient-services 。该库为大量 Google API 提供了最新的 API 包装器。为了让用户可以使用最新的 API 客户端，该库不会固定到特定版本的google/apiclient-services 。为了防止意外安装具有重大更改的 API 包装器，强烈建议您在生产中使用此库之前自行固定到最新版本。
有超过 200 个 Google API 服务。您很有可能并不想要所有这些。为了避免在代码中附带这些依赖项，您可以运行GoogleTaskComposer::cleanup任务并指定要保留在composer.json中的服务：
{
"require" : {
"google/apiclient" : " ^2.15.0 "
},
"scripts" : {
"pre-autoload-dump" : " Google \ Task \ Composer::cleanup "
},
"extra" : {
"google/apiclient-services" : [
" Drive " ,
" YouTube "
]
}
}当运行composer update或全新的composer install时，此示例将删除除“Drive”和“YouTube”之外的所有服务。
重要提示：如果您在composer.json中添加任何服务，则需要明确删除vendor/google/apiclient-services目录才能使您所做的更改生效：
rm -r vendor/google/apiclient-services
composer update注意：此命令对服务名称执行精确匹配，因此为了保留YouTubeReporting和YouTubeAnalytics ，您需要显式添加它们：
{
"extra" : {
"google/apiclient-services" : [
" Drive " ,
" YouTube " ,
" YouTubeAnalytics " ,
" YouTubeReporting "
]
}
}如果您不想使用 Composer，可以下载完整的软件包。发布页面列出了所有稳定版本。下载名为google-api-php-client-[RELEASE_NAME].zip的任何文件，获取包含此库及其依赖项的包。
解压缩您下载的 zip 文件，并将自动加载器包含在您的项目中：
require_once ' /path/to/google-api-php-client/vendor/autoload.php ' ;有关其他安装和设置说明，请参阅文档。
有关主要客户端功能的示例，请参阅examples/目录。您可以通过运行 php 内置 Web 服务器在浏览器中查看它们。
$ php -S localhost:8000 -t examples/
然后浏览到您指定的主机和端口（在上面的示例中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" ;
}可以在
examples/simple-file-upload.php中看到这样的示例。
按照说明创建 Web 应用程序凭据
下载 JSON 凭证
使用GoogleClient::setAuthConfig设置这些凭据的路径：
$ client = new Google Client ();
$ client -> setAuthConfig ( ' /path/to/client_credentials.json ' );设置您要调用的 API 所需的范围
$ client -> addScope ( Google Service Drive :: DRIVE );设置应用程序的重定向 URI
// 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 );在处理重定向 URI 的脚本中，将授权代码交换为访问令牌：
if ( isset ( $ _GET [ ' code ' ])) {
$ token = $ client -> fetchAccessTokenWithAuthCode ( $ _GET [ ' code ' ]);
}可以在
examples/service-account.php中看到这样的示例。
某些 API（例如 YouTube 数据 API）不支持服务帐户。如果 API 调用返回意外的 401 或 403 错误，请检查特定的 API 文档。
按照说明创建服务帐户
下载 JSON 凭证
使用GOOGLE_APPLICATION_CREDENTIALS环境变量设置这些凭据的路径：
putenv ( ' GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json ' );告诉 Google 客户端使用您的服务帐户凭据进行身份验证：
$ client = new Google Client ();
$ client -> useApplicationDefaultCredentials ();设置您要调用的 API 所需的范围
$ client -> addScope ( Google Service Drive :: DRIVE );如果您已委派对服务帐户的域范围访问权限并且想要模拟用户帐户，请使用 setSubject 方法指定用户帐户的电子邮件地址：
$ client -> setSubject ( $ user_to_impersonate );如果您想要特定的 JSON 密钥而不是使用GOOGLE_APPLICATION_CREDENTIALS环境变量，您可以执行以下操作：
$ jsonKey = [
' type ' => ' service_account ' ,
// ...
];
$ client = new Google Client ();
$ client -> setAuthConfig ( $ jsonKey );用于调用 google-api-php-client-services 中 API 的类是自动生成的。它们直接映射到 API Explorer 中找到的 JSON 请求和响应。
对数据存储区 API 的 JSON 请求如下所示：
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
}
}使用这个库，相同的调用将如下所示：
// 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 );然而，由于 JSON API 的每个属性都有一个对应的生成类，所以上面的代码也可以这样写：
// 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 );使用的方法是一个偏好问题，但如果不先了解 API 的 JSON 语法，就很难使用这个库，因此建议在使用此处的任何服务之前先查看 API Explorer。
如果外部应用程序需要 Google 身份验证，或者此库中尚未提供 Google API，则可以直接发出 HTTP 请求。
如果您安装此客户端只是为了验证您自己的 HTTP 客户端请求，则应使用google/auth 。
authorize方法返回一个授权的Guzzle客户端，因此使用该客户端发出的任何请求都将包含相应的授权。
// 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 ' );建议使用其他缓存库来提高性能。这可以通过将 PSR-6 兼容库传递给客户端来完成：
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 );在此示例中，我们使用 PHP 缓存。使用 Composer 将其添加到您的项目中：
composer require cache/filesystem-adapter
使用刷新令牌或服务帐户凭据时，在授予新的访问令牌时执行某些操作可能会很有用。为此，请将可调用对象传递给客户端上的setTokenCallback方法：
$ 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 );通过查看原始 HTTP 请求来调试 API 调用通常非常有用。该库支持使用 Charles Web Proxy。下载并运行 Charles，然后使用以下代码捕获通过 Charles 的所有 HTTP 流量：
// 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 );现在，该库进行的所有调用都将显示在 Charles UI 中。
Charles 中还需要执行一项附加步骤才能查看 SSL 请求。转至Charles > 代理 > SSL 代理设置并添加您想要捕获的域。对于 Google API，这通常是*.googleapis.com 。
Google API 客户端使用 Guzzle 作为其默认 HTTP 客户端。这意味着您可以像使用 Guzzle 控制任何应用程序一样控制 HTTP 请求。
举例来说，我们希望为每个请求应用一个引荐来源网址。
use GuzzleHttp Client ;
$ httpClient = new Client ([
' headers ' => [
' referer ' => ' mysite.com '
]
]);
$ client = new Google Client ();
$ client -> setHttpClient ( $ httpClient );其他 Guzzle 功能（例如处理程序和中间件）提供了更多控制。
使用 OAuth2 3LO 时（例如，您是向第三方请求凭据的客户端，例如在简单文件上传示例中），您可能希望利用部分同意。
要允许客户端仅在 OAuth2 屏幕中授予某些范围，请在生成授权 URL 时传递enable_serial_consent的查询字符串参数：
$ authUrl = $ client -> createAuthUrl ( $ scope , [ ' enable_serial_consent ' => ' true ' ]);流程完成后，您可以通过调用 OAuth2 对象上的getGrantedScope来查看授予了哪些范围：
// 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
请参阅贡献页面以获取更多信息。我们特别喜欢拉取请求 - 但请确保签署贡献者许可协议。
要获得该库的支持，最好的询问地点是通过 StackOverflow 上的 google-api-php-client 标签：https://stackoverflow.com/questions/tagged/google-api-php-client
如果该库存在特定错误，请在 GitHub 问题跟踪器中提交问题，包括失败代码的示例和检索到的任何特定错误。也可以提交功能请求，只要它们是核心库请求，并且不是特定于 API 的：对于这些请求，请参阅各个 API 的文档，了解提交请求的最佳位置。请尝试清楚地说明该功能将解决的问题。
如果 X 是该库的一个功能，请归档！如果 X 是使用特定服务的示例，那么最好的地方是那些特定 API 的团队 - 我们的首选是链接到他们的示例，而不是将它们添加到库中，因为他们可以固定到特定版本的图书馆。如果您有任何其他 API 的示例，请告诉我们，我们将很乐意添加上面的自述文件的链接！
GoogleService类通常是从 API 发现文档自动生成的：https://developers.google.com/discovery/。有时，新功能会以不寻常的名称添加到 API 中，这可能会导致 PHP 类中出现一些意外或非标准样式的命名。
某些服务默认返回 XML 或类似内容，而不是该库支持的 JSON。您可以通过向可选参数添加“alt”参数来请求 JSON 响应，该参数通常是方法调用的最后一个参数：
$ opt_params = array (
' alt ' => " json "
);该库会从发送到 Google API 的对象中剔除空值，因为它是所有未初始化属性的默认值。要解决此问题，请将您想要为 null 的字段设置为GoogleModel::NULL_VALUE 。这是一个占位符，在通过网络发送时将被替换为 true null。
使用 PHPUnit 运行 PHPUnit 测试。您可以在 BaseTest.php 中配置 API 密钥和令牌来运行所有调用，但这需要在 Google 开发者控制台上进行一些设置。
phpunit tests/
要检查编码风格违规情况，请运行
vendor/bin/phpcs src --standard=style/ruleset.xml -np
要自动修复（可修复的）编码风格违规，请运行
vendor/bin/phpcbf src --standard=style/ruleset.xml
