google api php client
v2.18.0
หมายเหตุ : โปรดตรวจสอบเพื่อดูว่าแพ็คเกจที่คุณต้องการติดตั้งนั้นมีอยู่ในรายการแพ็คเกจ Google Cloud ของเราก่อนหรือไม่ เนื่องจากเป็นไลบรารีที่แนะนำ
ไลบรารีไคลเอ็นต์ 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
โฟลเดอร์เอกสารให้คำแนะนำโดยละเอียดสำหรับการใช้ไลบรารีนี้
คุณสามารถใช้ Composer หรือเพียงแค่ ดาวน์โหลด Release
วิธีที่ต้องการคือผ่านผู้แต่ง ปฏิบัติตามคำแนะนำในการติดตั้งหากคุณยังไม่ได้ติดตั้งผู้แต่ง
เมื่อติดตั้งผู้แต่งแล้ว ให้รันคำสั่งต่อไปนี้ในรูทโปรเจ็กต์ของคุณเพื่อติดตั้งไลบรารีนี้:
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 ไลบรารีนั้นมี Wrapper API ที่ทันสมัยสำหรับ Google API จำนวนมาก เพื่อให้ผู้ใช้สามารถใช้ประโยชน์จากไคลเอ็นต์ API ล่าสุดได้ ไลบรารีนี้จะไม่ปักหมุดไปยังเวอร์ชันเฉพาะของ google/apiclient-services เพื่อป้องกันการติดตั้ง API Wrappers โดยไม่ได้ตั้งใจเนื่องจากการเปลี่ยนแปลงที่เสียหาย ขอแนะนำอย่างยิ่งให้คุณปักหมุดเวอร์ชันล่าสุดด้วยตนเองก่อนที่จะใช้ไลบรารีนี้ในการใช้งานจริง
มีบริการ Google API มากกว่า 200 รายการ โอกาสดีที่คุณจะไม่ต้องการมันทั้งหมด เพื่อหลีกเลี่ยงการพึ่งพาเหล่านี้กับโค้ดของคุณ คุณสามารถรันงาน 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 บางตัว (เช่น YouTube Data API) ไม่รองรับบัญชีบริการ ตรวจสอบกับเอกสารประกอบ 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 และการตอบกลับที่พบใน APIs Explorer
คำขอ JSON ไปยัง Datastore 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 ก่อน ดังนั้นจึงขอแนะนำให้ดู APIs Explorer ก่อนที่จะใช้บริการใดๆ ที่นี่
หากต้องการการรับรองความถูกต้องของ Google สำหรับแอปพลิเคชันภายนอก หรือ Google API ยังไม่มีให้บริการในไลบรารีนี้ คุณสามารถส่งคำขอ HTTP ได้โดยตรง
หากคุณกำลังติดตั้งไคลเอ็นต์นี้เพื่อตรวจสอบสิทธิ์คำขอไคลเอ็นต์ HTTP ของคุณเองเท่านั้น คุณควรใช้ google/auth แทน
วิธี authorize จะส่งคืน Guzzle Client ที่ได้รับอนุญาต ดังนั้นคำขอใด ๆ ที่ทำโดยใช้ไคลเอนต์จะต้องมีการอนุญาตที่เกี่ยวข้อง
// 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
เมื่อใช้โทเค็นการรีเฟรชหรือข้อมูลรับรองบัญชีบริการ อาจมีประโยชน์ในการดำเนินการบางอย่างเมื่อได้รับโทเค็นการเข้าถึงใหม่ เมื่อต้องการทำเช่นนี้ ให้ส่งผ่าน callable ไปยังเมธอด 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 Web Proxy ดาวน์โหลดและเรียกใช้ 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 UI
Charles จำเป็นต้องมีขั้นตอนเพิ่มเติมอีกหนึ่งขั้นตอนเพื่อดูคำขอ SSL ไปที่ Charles > Proxy > การตั้งค่าพร็อกซี SSL และเพิ่มโดเมนที่คุณต้องการบันทึก ในกรณีของ Google API โดยปกติจะเป็น *.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 อื่นๆ เช่น Handlers และ Middleware ช่วยให้ควบคุมได้มากขึ้น
เมื่อใช้ 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 ();ยูทูบ: 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 "
); ไลบรารีจะตัดค่าว่างออกจากออบเจ็กต์ที่ส่งไปยัง Google API เนื่องจากเป็นค่าเริ่มต้นของคุณสมบัติที่ยังไม่ได้เตรียมใช้งานทั้งหมด หากต้องการแก้ไขปัญหานี้ ให้ตั้งค่าฟิลด์ที่คุณต้องการให้เป็นโมฆะเป็น GoogleModel::NULL_VALUE นี่คือตัวยึดตำแหน่งที่จะถูกแทนที่ด้วยค่าว่างจริงเมื่อส่งผ่านสาย
รันการทดสอบ PHPUnit ด้วย PHPUnit คุณสามารถกำหนดค่าคีย์ API และโทเค็นใน BaseTest.php เพื่อเรียกใช้การโทรทั้งหมดได้ แต่จะต้องมีการตั้งค่าบางอย่างบน Google Developer Console
phpunit tests/
หากต้องการตรวจสอบการละเมิดรูปแบบการเขียนโค้ด ให้เรียกใช้
vendor/bin/phpcs src --standard=style/ruleset.xml -np
หากต้องการแก้ไขการละเมิดรูปแบบการเขียนโค้ด (แก้ไขได้) โดยอัตโนมัติ ให้เรียกใช้
vendor/bin/phpcbf src --standard=style/ruleset.xml
