google api php client
v2.18.0
ПРИМЕЧАНИЕ . Сначала проверьте, доступен ли пакет, который вы хотите установить, в нашем списке облачных пакетов Google, поскольку это рекомендуемые библиотеки.
Клиентская библиотека Google API позволяет вам работать с API Google, такими как Gmail, Drive или YouTube, на вашем сервере.
Эти клиентские библиотеки официально поддерживаются Google. Однако библиотеки считаются завершенными и находятся в режиме обслуживания. Это означает, что мы исправим критические ошибки и проблемы безопасности, но не будем добавлять никаких новых функций.
Для API Google Cloud Platform, таких как Datastore, Cloud Storage, Pub/Sub и Compute Engine, мы рекомендуем использовать клиентские библиотеки Google Cloud. Полный список поддерживаемых клиентских библиотек Google Cloud см. на странице googleapis/google-cloud-php.
В папке docs содержатся подробные руководства по использованию этой библиотеки.
Вы можете использовать Composer или просто загрузить релиз.
Предпочтительный метод — через композитор. Следуйте инструкциям по установке, если у вас еще не установлен композитор.
После установки композитора выполните следующую команду в корне вашего проекта, чтобы установить эту библиотеку:
composer require google/apiclient:^2.15.0 Если вы столкнулись с ошибкой тайм-аута, либо увеличьте тайм-аут для композитора, добавив флаг env как COMPOSER_PROCESS_TIMEOUT=600 composer install , либо вы можете поместить это в раздел config схемы композитора:
{
"config": {
"process-timeout": 600
}
}
Наконец, обязательно включите автозагрузчик:
require_once ' /path/to/your-project/vendor/autoload.php ' ; Эта библиотека использует google/apiclient-services . Эта библиотека предоставляет актуальные оболочки API для большого количества API Google. Чтобы пользователи могли использовать новейшие клиенты 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 "
]
}
} В этом примере будут удалены все службы, кроме «Диска» и «YouTube», при запуске composer update или новой composer install .
ВАЖНО : Если вы добавите какие-либо службы обратно в composer.json , вам нужно будет явно удалить vendor/google/apiclient-services , чтобы внесенные вами изменения вступили в силу:
rm -r vendor/google/apiclient-services
composer update ПРИМЕЧАНИЕ . Эта команда выполняет точное совпадение имени службы, поэтому, чтобы сохранить YouTubeReporting и YouTubeAnalytics , вам необходимо явно добавить каждый из них:
{
"extra" : {
"google/apiclient-services" : [
" Drive " ,
" YouTube " ,
" YouTubeAnalytics " ,
" YouTubeReporting "
]
}
} Если вы предпочитаете не использовать композитор, вы можете загрузить пакет целиком. На странице «Релизы» перечислены все стабильные версии. Загрузите любой файл с именем 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/
А затем перейдите к указанному вами хосту и порту (в приведенном выше примере 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.
Следуйте инструкциям по созданию учетных данных веб-приложения.
Загрузите учетные данные 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 (например, API данных YouTube) не поддерживают учетные записи служб. Проверьте документацию по конкретному API, возвращают ли вызовы API непредвиденные ошибки 401 или 403.
Следуйте инструкциям по созданию учетной записи службы.
Загрузите учетные данные 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 );Классы, используемые для вызова API в google-api-php-client-services, генерируются автоматически. Они напрямую сопоставляются с запросами и ответами JSON, найденными в API Explorer.
Запрос JSON к API хранилища данных будет выглядеть следующим образом:
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 );Используемый метод зависит от предпочтений, но будет очень сложно использовать эту библиотеку без предварительного понимания синтаксиса JSON для API , поэтому рекомендуется просмотреть API-обозреватель, прежде чем использовать какой-либо из представленных здесь сервисов.
Если для внешних приложений требуется аутентификация Google или API Google еще недоступен в этой библиотеке, 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 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 );Часто бывает очень полезно отлаживать вызовы API, просматривая необработанный HTTP-запрос. Эта библиотека поддерживает использование веб-прокси Charles. Загрузите и запустите Charles, а затем перехватите весь HTTP-трафик через Charles с помощью следующего кода:
// 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.
Для просмотра SSL-запросов в Charles требуется еще один шаг. Перейдите в Charles > Прокси > Настройки SSL-прокси и добавьте домен, который вы хотите захватить. В случае API Google это обычно *.googleapis.com .
Клиент Google API использует Guzzle в качестве HTTP-клиента по умолчанию. Это означает, что вы можете управлять своими HTTP-запросами так же, как и для любого приложения, использующего Guzzle.
Скажем, например, мы хотим применить реферер к каждому запросу.
use GuzzleHttp Client ;
$ httpClient = new Client ([
' headers ' => [
' referer ' => ' mysite.com '
]
]);
$ client = new Google Client ();
$ client -> setHttpClient ( $ httpClient );Другие функции Guzzle, такие как обработчики и промежуточное ПО, предлагают еще больший контроль.
При использовании OAuth2 3LO (например, вы являетесь клиентом, запрашивающим учетные данные у третьей стороны, как в примере с простой загрузкой файла), вы можете воспользоваться преимуществом частичного согласия.
Чтобы клиенты могли предоставлять только определенные области на экране OAuth2, передайте параметр строки запроса для enable_serial_consent при создании URL-адреса авторизации:
$ authUrl = $ client -> createAuthUrl ( $ scope , [ ' enable_serial_consent ' => ' true ' ]); После завершения потока вы можете увидеть, какие области были предоставлены, вызвав getGrantedScope для объекта 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.
Пожалуйста, посетите страницу участия для получения дополнительной информации. В частности, мы любим запросы на включение, но, пожалуйста, не забудьте подписать лицензионное соглашение для участников.
Для поддержки библиотеки лучше всего задать вопрос через тег google-api-php-client в StackOverflow: https://stackoverflow.com/questions/tagged/google-api-php-client
Если в библиотеке возникла конкретная ошибка, отправьте сообщение о проблеме в систему отслеживания проблем GitHub, включая пример сбойного кода и все обнаруженные конкретные ошибки. Запросы на функции также могут быть отправлены, если они являются запросами базовой библиотеки, а не специфичными для API: для этого обратитесь к документации по отдельным API, чтобы узнать, где лучше всего подавать запросы. Постарайтесь четко сформулировать проблему, которую будет решать эта функция.
Если X является особенностью библиотеки, удалите файл! Если X является примером использования определенного сервиса, лучше всего обратиться к командам, работающим над этими конкретными API. Мы предпочитаем ссылаться на их примеры, а не добавлять их в библиотеку, поскольку они затем смогут прикрепить их к конкретным версиям библиотека. Если у вас есть примеры других API, сообщите нам, и мы с радостью добавим ссылку в README выше!
Классы GoogleService обычно автоматически генерируются на основе документов обнаружения API: https://developers.google.com/discovery/. Иногда к API добавляются новые функции с необычными именами, что может привести к неожиданному или нестандартному стилю именования классов PHP.
Некоторые службы по умолчанию возвращают XML или аналогичный формат, а не JSON, который поддерживает библиотека. Вы можете запросить ответ JSON, добавив аргумент «alt» к необязательным параметрам, который обычно является последним аргументом вызова метода:
$ opt_params = array (
' alt ' => " json "
); Библиотека удаляет значения NULL из объектов, отправляемых в API Google, поскольку это значение по умолчанию для всех неинициализированных свойств. Чтобы обойти эту проблему, установите для поля, которое вы хотите обнулить, значение GoogleModel::NULL_VALUE . Это заполнитель, который будет заменен истинным нулевым значением при отправке по сети.
Запустите тесты PHPUnit с помощью PHPUnit. Вы можете настроить ключ API и токен в BaseTest.php для выполнения всех вызовов, но для этого потребуется определенная настройка в консоли разработчика Google.
phpunit tests/
Чтобы проверить наличие нарушений стиля кодирования, запустите
vendor/bin/phpcs src --standard=style/ruleset.xml -np
Чтобы автоматически исправлять (устранимые) нарушения стиля кодирования, запустите
vendor/bin/phpcbf src --standard=style/ruleset.xml
