google api php client
v2.18.0
CATATAN : harap periksa terlebih dahulu apakah paket yang ingin Anda instal tersedia di daftar paket cloud Google kami, karena ini adalah perpustakaan yang direkomendasikan.
Perpustakaan Klien Google API memungkinkan Anda bekerja dengan Google API seperti Gmail, Drive, atau YouTube di server Anda.
Pustaka klien ini secara resmi didukung oleh Google. Namun, perpustakaan dianggap lengkap dan berada dalam mode pemeliharaan. Artinya, kami akan mengatasi bug kritis dan masalah keamanan namun tidak akan menambahkan fitur baru apa pun.
Untuk API Google Cloud Platform seperti Datastore, Cloud Storage, Pub/Sub, dan Compute Engine, sebaiknya gunakan pustaka klien Google Cloud. Untuk daftar lengkap pustaka klien Google Cloud yang didukung, lihat googleapis/google-cloud-php.
Folder docs menyediakan panduan rinci untuk menggunakan perpustakaan ini.
Anda dapat menggunakan Komposer atau cukup Unduh Rilisnya
Metode yang disukai adalah melalui komposer. Ikuti petunjuk instalasi jika Anda belum menginstal composer.
Setelah komposer terinstal, jalankan perintah berikut di root proyek Anda untuk menginstal perpustakaan ini:
composer require google/apiclient:^2.15.0 Jika Anda menghadapi kesalahan batas waktu, tambah batas waktu untuk komposer dengan menambahkan tanda env sebagai COMPOSER_PROCESS_TIMEOUT=600 composer install atau Anda dapat meletakkannya di bagian config skema komposer:
{
"config": {
"process-timeout": 600
}
}
Terakhir, pastikan untuk menyertakan autoloader:
require_once ' /path/to/your-project/vendor/autoload.php ' ; Perpustakaan ini bergantung pada google/apiclient-services . Pustaka tersebut menyediakan wrapper API terkini untuk sejumlah besar Google API. Agar pengguna dapat menggunakan klien API terbaru, perpustakaan ini tidak menyematkan ke versi google/apiclient-services tertentu. Untuk mencegah pemasangan pembungkus API yang tidak disengaja dengan perubahan yang dapat menyebabkan kerusakan , sangat disarankan agar Anda menyematkan sendiri ke versi terbaru sebelum menggunakan perpustakaan ini dalam produksi.
Ada lebih dari 200 layanan Google API. Kemungkinan besar Anda tidak menginginkan semuanya. Untuk menghindari pengiriman dependensi ini dengan kode Anda, Anda dapat menjalankan tugas GoogleTaskComposer::cleanup dan menentukan layanan yang ingin Anda simpan di composer.json :
{
"require" : {
"google/apiclient" : " ^2.15.0 "
},
"scripts" : {
"pre-autoload-dump" : " Google \ Task \ Composer::cleanup "
},
"extra" : {
"google/apiclient-services" : [
" Drive " ,
" YouTube "
]
}
} Contoh ini akan menghapus semua layanan selain "Drive" dan "YouTube" ketika composer update atau composer install baru dijalankan.
PENTING : Jika Anda menambahkan kembali layanan apa pun di composer.json , Anda harus menghapus direktori vendor/google/apiclient-services secara eksplisit agar perubahan yang Anda buat dapat diterapkan:
rm -r vendor/google/apiclient-services
composer update CATATAN : Perintah ini melakukan pencocokan persis pada nama layanan, jadi untuk mempertahankan YouTubeReporting dan YouTubeAnalytics , Anda harus menambahkan masing-masing secara eksplisit:
{
"extra" : {
"google/apiclient-services" : [
" Drive " ,
" YouTube " ,
" YouTubeAnalytics " ,
" YouTubeReporting "
]
}
} Jika Anda memilih untuk tidak menggunakan composer, Anda dapat mendownload paket secara keseluruhan. Halaman Rilis mencantumkan semua versi stabil. Unduh file apa pun dengan nama google-api-php-client-[RELEASE_NAME].zip untuk paket yang menyertakan pustaka ini dan dependensinya.
Buka kompresi file zip yang Anda unduh, dan sertakan pemuat otomatis dalam proyek Anda:
require_once ' /path/to/google-api-php-client/vendor/autoload.php ' ;Untuk petunjuk instalasi dan pengaturan tambahan, lihat dokumentasi.
Lihat direktori examples/ untuk contoh fitur klien utama. Anda dapat melihatnya di browser Anda dengan menjalankan server web bawaan php.
$ php -S localhost:8000 -t examples/
Dan kemudian menjelajah ke host dan port yang Anda tentukan (dalam contoh di atas, 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" ;
}Contohnya dapat dilihat di
examples/simple-file-upload.php.
Ikuti instruksi untuk Membuat Kredensial Aplikasi Web
Unduh kredensial JSON
Tetapkan jalur ke kredensial ini menggunakan GoogleClient::setAuthConfig :
$ client = new Google Client ();
$ client -> setAuthConfig ( ' /path/to/client_credentials.json ' );Tetapkan cakupan yang diperlukan untuk API yang akan Anda panggil
$ client -> addScope ( Google Service Drive :: DRIVE );Setel URI pengalihan aplikasi Anda
// 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 );Dalam skrip yang menangani URI pengalihan, tukarkan kode otorisasi dengan token akses:
if ( isset ( $ _GET [ ' code ' ])) {
$ token = $ client -> fetchAccessTokenWithAuthCode ( $ _GET [ ' code ' ]);
}Contohnya dapat dilihat di
examples/service-account.php.
Beberapa API (seperti YouTube Data API) tidak mendukung akun layanan. Periksa dokumentasi API spesifik apakah panggilan API menghasilkan kesalahan 401 atau 403 yang tidak terduga.
Ikuti instruksi untuk Membuat Akun Layanan
Unduh kredensial JSON
Tetapkan jalur ke kredensial ini menggunakan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS :
putenv ( ' GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json ' );Beri tahu klien Google untuk menggunakan kredensial akun layanan Anda untuk mengautentikasi:
$ client = new Google Client ();
$ client -> useApplicationDefaultCredentials ();Tetapkan cakupan yang diperlukan untuk API yang akan Anda panggil
$ client -> addScope ( Google Service Drive :: DRIVE );Jika Anda telah mendelegasikan akses seluruh domain ke akun layanan dan ingin menyamar sebagai akun pengguna, tentukan alamat email akun pengguna tersebut menggunakan metode setSubject:
$ client -> setSubject ( $ user_to_impersonate ); Jika Anda ingin kunci JSON tertentu daripada menggunakan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS , Anda dapat melakukan ini:
$ jsonKey = [
' type ' => ' service_account ' ,
// ...
];
$ client = new Google Client ();
$ client -> setAuthConfig ( $ jsonKey );Kelas yang digunakan untuk memanggil API di google-api-php-client-services dibuat secara otomatis. Mereka memetakan langsung ke permintaan dan respons JSON yang ditemukan di API Explorer.
Permintaan JSON ke Datastore API akan terlihat seperti ini:
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
}
}Dengan menggunakan perpustakaan ini, panggilan yang sama akan terlihat seperti ini:
// 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 );Namun, karena setiap properti JSON API memiliki kelas yang dihasilkan, kode di atas juga dapat ditulis seperti ini:
// 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 );Metode yang digunakan adalah masalah preferensi, tetapi akan sangat sulit untuk menggunakan perpustakaan ini tanpa terlebih dahulu memahami sintaks JSON untuk API tersebut , jadi disarankan untuk melihat APIs Explorer sebelum menggunakan layanan apa pun di sini.
Jika Otentikasi Google diinginkan untuk aplikasi eksternal, atau Google API belum tersedia di perpustakaan ini, permintaan HTTP dapat dibuat secara langsung.
Jika Anda menginstal klien ini hanya untuk mengautentikasi permintaan klien HTTP Anda sendiri, Anda harus menggunakan google/auth sebagai gantinya.
Metode authorize mengembalikan Klien Guzzle yang diotorisasi, sehingga setiap permintaan yang dibuat menggunakan klien akan berisi otorisasi yang sesuai.
// 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 ' );Disarankan untuk menggunakan perpustakaan caching lain untuk meningkatkan kinerja. Hal ini dapat dilakukan dengan meneruskan perpustakaan yang kompatibel dengan PSR-6 ke klien:
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 );Dalam contoh ini kita menggunakan PHP Cache. Tambahkan ini ke proyek Anda dengan komposer:
composer require cache/filesystem-adapter
Saat menggunakan Refresh Tokens atau Service Account Credentials, mungkin berguna untuk melakukan beberapa tindakan ketika token akses baru diberikan. Untuk melakukannya, teruskan callable ke metode setTokenCallback pada klien:
$ 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 );Seringkali sangat berguna untuk men-debug panggilan API Anda dengan melihat permintaan HTTP mentah. Perpustakaan ini mendukung penggunaan Charles Web Proxy. Unduh dan jalankan Charles, lalu tangkap semua lalu lintas HTTP melalui Charles dengan kode berikut:
// 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 );Sekarang semua panggilan yang dilakukan oleh perpustakaan ini akan muncul di Charles UI.
Satu langkah tambahan diperlukan di Charles untuk melihat permintaan SSL. Buka Charles > Proxy > Pengaturan Proxy SSL dan tambahkan domain yang ingin Anda ambil. Dalam kasus Google API, biasanya *.googleapis.com .
Klien Google API menggunakan Guzzle sebagai klien HTTP defaultnya. Itu berarti Anda dapat mengontrol permintaan HTTP dengan cara yang sama seperti yang Anda lakukan untuk aplikasi apa pun yang menggunakan Guzzle.
Katakanlah, misalnya, kita ingin menerapkan perujuk pada setiap permintaan.
use GuzzleHttp Client ;
$ httpClient = new Client ([
' headers ' => [
' referer ' => ' mysite.com '
]
]);
$ client = new Google Client ();
$ client -> setHttpClient ( $ httpClient );Fitur Guzzle lainnya seperti Handlers dan Middleware menawarkan kontrol lebih besar.
Saat menggunakan OAuth2 3LO (misalnya, Anda adalah klien yang meminta kredensial dari pihak ketiga, seperti pada contoh pengunggahan file sederhana), Anda mungkin ingin memanfaatkan Persetujuan Parsial.
Untuk mengizinkan klien hanya memberikan cakupan tertentu di layar OAuth2, teruskan parameter string kueri untuk enable_serial_consent saat membuat URL otorisasi:
$ authUrl = $ client -> createAuthUrl ( $ scope , [ ' enable_serial_consent ' => ' true ' ]); Setelah alurnya selesai, Anda dapat melihat cakupan mana yang diberikan dengan memanggil getGrantedScope pada objek 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
Silakan lihat halaman kontribusi untuk informasi lebih lanjut. Secara khusus, kami menyukai permintaan penarikan - namun pastikan untuk menandatangani perjanjian lisensi kontributor.
Untuk dukungan perpustakaan, tempat terbaik untuk bertanya adalah melalui tag google-api-php-client di StackOverflow: https://stackoverflow.com/questions/tagged/google-api-php-client
Jika ada bug tertentu pada perpustakaan, harap ajukan masalah di pelacak masalah GitHub, termasuk contoh kode yang gagal dan kesalahan spesifik apa pun yang diambil. Permintaan fitur juga dapat diajukan, selama permintaan tersebut merupakan permintaan pustaka inti, dan bukan khusus API: untuk permintaan tersebut, lihat dokumentasi untuk masing-masing API untuk mengetahui tempat terbaik untuk mengajukan permintaan. Silakan coba memberikan pernyataan yang jelas tentang masalah yang akan diatasi oleh fitur tersebut.
Jika X adalah fitur perpustakaan, simpanlah! Jika X adalah contoh penggunaan layanan tertentu, tempat terbaik untuk pergi adalah ke tim untuk API spesifik tersebut - preferensi kami adalah menautkan ke contoh mereka daripada menambahkannya ke perpustakaan, karena mereka kemudian dapat menyematkan ke versi tertentu dari layanan tersebut. perpustakaan. Jika Anda memiliki contoh untuk API lainnya, beri tahu kami dan kami akan dengan senang hati menambahkan tautan ke README di atas!
Kelas GoogleLayanan umumnya dibuat secara otomatis dari dokumen penemuan API: https://developers.google.com/discovery/. Terkadang fitur baru ditambahkan ke API dengan nama yang tidak biasa, yang dapat menyebabkan beberapa gaya penamaan yang tidak terduga atau tidak standar di kelas PHP.
Beberapa layanan mengembalikan XML atau sejenisnya secara default, bukan JSON, yang didukung perpustakaan. Anda dapat meminta respons JSON dengan menambahkan argumen 'alt' ke parameter opsional yang biasanya merupakan argumen terakhir pada pemanggilan metode:
$ opt_params = array (
' alt ' => " json "
); Pustaka menghapus null dari objek yang dikirim ke Google API karena ini adalah nilai default dari semua properti yang tidak diinisialisasi. Untuk mengatasinya, setel bidang yang ingin Anda null ke GoogleModel::NULL_VALUE . Ini adalah pengganti yang akan diganti dengan null yang sebenarnya saat dikirim melalui kabel.
Jalankan tes PHPUnit dengan PHPUnit. Anda dapat mengonfigurasi kunci dan token API di BaseTest.php untuk menjalankan semua panggilan, namun hal ini memerlukan beberapa penyiapan di Google Developer Console.
phpunit tests/
Untuk memeriksa pelanggaran gaya pengkodean, jalankan
vendor/bin/phpcs src --standard=style/ruleset.xml -np
Untuk memperbaiki pelanggaran gaya pengkodean (yang dapat diperbaiki) secara otomatis, jalankan
vendor/bin/phpcbf src --standard=style/ruleset.xml
