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
