gomee / google-apiclient-clone

Google API 客户端库

维护者

详细信息

github.com/vccvn/google-api-php-client-clone

主页

源代码

问题

安装次数: 3

依赖项: 0

建议者: 0

安全: 0

星星: 0

关注者: 1

分支: 0

公开问题: 0

v2.15.3 2024-01-04 19:15 UTC

Requires

Requires (Dev)

Suggests

Apache-2.0 e70273c06d18824de77e114247ae3102f8aec64d

google

This package is auto-updated.

Last update: 2024-10-01 00:11:30 UTC

README

PHP 的 Google APIs 客户端库

注意：请首先检查您想要安装的软件包是否在我们的Google 云软件包列表中可用，因为这些是推荐的库。

参考文档
https://googleapis.github.io/google-api-php-client/main/
许可证
Apache 2.0

Google API 客户端库使您能够在服务器上使用 Google API，如 Gmail、Drive 或 YouTube。

这些客户端库由 Google 正式支持。然而，这些库被认为是完整的，并且处于维护模式。这意味着我们将解决关键错误和安全问题，但不会添加任何新功能。

Google 云平台

对于 Google 云平台 API，如 Datastore、Cloud Storage、Pub/Sub 和 Compute Engine，我们建议使用 Google 云客户端库。有关支持的 Google 云客户端库的完整列表，请参阅 googleapis/google-cloud-php。

要求

开发者文档

docs 文件夹 提供了使用此库的详细指南。

安装

您可以使用 Composer 或直接 下载发行版

Composer

首选方法是使用 composer。如果您尚未安装 composer，请遵循安装说明。

安装完成后，在项目根目录中执行以下命令以安装此库

composer require google/apiclient:^2.15.0

如果您遇到超时错误，则可以增加 composer 的超时时间，方法是在命令中添加 env 标志，例如 COMPOSER_PROCESS_TIMEOUT=600 composer install，或者您可以将此放在 composer schema 的 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 服务。您可能不需要它们全部。为了避免将这些依赖项与代码一起打包，您可以使用 Google\Task\Composer::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网络服务器来在浏览器中查看它们。

$ php -S localhost:8000 -t examples/

然后浏览到您指定的主机和端口（在上面的示例中，https://: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";
}

使用OAuth进行身份验证

此示例可参见examples/simple-file-upload.php。

  1. 按照说明创建Web应用程序凭证

  2. 下载JSON凭证

  3. 使用Google\Client::setAuthConfig设置这些凭证的路径

    $client = new Google\Client();
$client->setAuthConfig('/path/to/client_credentials.json');

  4. 设置您要调用的API所需的权限范围

    $client->addScope(Google\Service\Drive::DRIVE);

  5. 设置您应用程序的重定向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);

  6. 在处理重定向URI的脚本中，用访问令牌交换授权代码

    if (isset($_GET['code'])) {
    $token = $client->fetchAccessTokenWithAuthCode($_GET['code']);
}

使用服务帐户进行身份验证

此示例可参见examples/service-account.php。

某些API（例如YouTube数据API）不支持服务帐户。如果API调用返回意外的401或403错误，请检查特定API的文档。

  1. 按照说明创建服务帐户

  2. 下载JSON凭证

  3. 使用环境变量GOOGLE_APPLICATION_CREDENTIALS设置这些凭证的路径

    putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json');

  4. 告诉Google客户端使用您的服务帐户凭证进行身份验证

    $client = new Google\Client();
$client->useApplicationDefaultCredentials();

  5. 设置您要调用的API所需的权限范围

    $client->addScope(Google\Service\Drive::DRIVE);

  6. 如果您已将域范围访问委托给服务帐户，并且您想模拟用户帐户，请使用setSubject方法指定用户帐户的电子邮件地址

    $client->setSubject($user_to_impersonate);

如何使用特定的JSON密钥

如果您想使用特定的JSON密钥而不是使用GOOGLE_APPLICATION_CREDENTIALS环境变量，您可以这样做

$jsonKey = [
   'type' => 'service_account',
   // ...
];
$client = new Google\Client();
$client->setAuthConfig($jsonKey);

发起请求

用于在google-api-php-client-services中调用API的类是自动生成的。它们直接映射到在APIs 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语法，将很难使用这个库，因此建议在使用这里的任何服务之前先查看APIs Explorer。

直接发送HTTP请求

如果外部应用程序需要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 Cache。使用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);

使用Charles调试您的HTTP请求

通过查看原始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。

直接控制HTTP客户端配置

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是库的功能，请保留！如果X是使用特定服务的示例，最佳去处是那些特定API的团队 - 我们更喜欢链接到他们的示例而不是将它们添加到库中，因为这样他们可以针对库的具体版本进行固定。如果您有其他API的示例，请告诉我们，我们将非常乐意在上面的README中添加链接！

为什么一些Google\Service类的名称很奇怪？

Google\Service类通常是自动从API发现文档生成的：https://developers.google.com/discovery/。有时API会添加具有不寻常名称的新功能，这可能导致PHP类中出现一些意外的或非标准化的命名风格。

如何处理非JSON响应类型？

一些服务默认返回XML或类似格式，而不是JSON，而库支持的是JSON。您可以通过向方法调用的最后一个参数添加一个名为'alt'的可选参数来请求JSON响应。

$opt_params = array(
  'alt' => "json"
);

如何将字段设置为null？

由于所有未初始化属性默认值为null，库会从发送到Google API的对象中删除null。为了解决这个问题，请将您想要设置为null的字段设置为Google\Model::NULL_VALUE。这是一个占位符，当通过线发送时将被替换为真正的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