google api php client
v2.18.0
ملاحظة : يرجى التحقق لمعرفة ما إذا كانت الحزمة التي ترغب في تثبيتها متوفرة في قائمة حزم Google السحابية لدينا أولاً، حيث أن هذه هي المكتبات الموصى بها.
تتيح لك مكتبة عملاء Google API العمل مع Google APIs مثل Gmail أو Drive أو YouTube على خادمك.
يتم دعم مكتبات العملاء هذه رسميًا بواسطة Google. ومع ذلك، تعتبر المكتبات كاملة وهي في وضع الصيانة. وهذا يعني أننا سنعالج الأخطاء الحرجة والمشكلات الأمنية ولكننا لن نضيف أي ميزات جديدة.
بالنسبة إلى واجهات برمجة تطبيقات Google Cloud Platform مثل Datastore وCloud Storage وPub/Sub وCompute Engine، نوصي باستخدام مكتبات عملاء Google Cloud. للحصول على قائمة كاملة بمكتبات عملاء Google Cloud المدعومة، راجع googleapis/google-cloud-php.
يوفر مجلد المستندات إرشادات مفصلة لاستخدام هذه المكتبة.
يمكنك استخدام 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 محدثة لعدد كبير من واجهات برمجة تطبيقات Google. لكي يتمكن المستخدمون من الاستفادة من أحدث عملاء واجهة برمجة التطبيقات، لا يتم تثبيت هذه المكتبة على إصدار محدد من 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 "
]
}
} سيؤدي هذا المثال إلى إزالة جميع الخدمات بخلاف "Drive" و"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 لحزمة تتضمن هذه المكتبة وتوابعها.
قم بفك ضغط الملف المضغوط الذي قمت بتنزيله، وقم بتضمين أداة التحميل التلقائي في مشروعك:
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.
لا تدعم بعض واجهات برمجة التطبيقات (مثل 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 );يتم إنشاء الفئات المستخدمة لاستدعاء واجهة برمجة التطبيقات في خدمات 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 المعتمد، لذا فإن أي طلب يتم تقديمه باستخدام العميل سيحتوي على التفويض المقابل.
// 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 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 Proxying Settings وأضف النطاق الذي ترغب في الحصول عليه. في حالة واجهات برمجة تطبيقات Google، يكون هذا عادةً *.googleapis.com .
يستخدم Google API Client 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، قم بتمرير معلمة querystring لـ 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، بما في ذلك مثال على التعليمات البرمجية الفاشلة وأي أخطاء محددة تم استردادها. يمكن أيضًا تقديم طلبات الميزات، طالما أنها طلبات مكتبة أساسية وليست خاصة بواجهة برمجة التطبيقات: بالنسبة لهؤلاء، راجع الوثائق الخاصة بواجهات برمجة التطبيقات الفردية للحصول على أفضل مكان لتقديم الطلبات. يرجى محاولة تقديم بيان واضح للمشكلة التي ستعالجها هذه الميزة.
إذا كانت X إحدى ميزات المكتبة، فاحفظها بعيدًا! إذا كان X مثالاً لاستخدام خدمة معينة، فإن أفضل مكان للذهاب إليه هو الفرق الخاصة بواجهات برمجة التطبيقات المحددة - نفضل الارتباط بأمثلتها بدلاً من إضافتها إلى المكتبة، حيث يمكنهم بعد ذلك تثبيت إصدارات محددة من المكتبة. إذا كان لديك أي أمثلة لواجهات برمجة التطبيقات الأخرى، فأخبرنا بذلك وسنسعد بإضافة رابط إلى الملف التمهيدي أعلاه!
يتم بشكل عام إنشاء فئات GoogleService تلقائيًا من مستندات اكتشاف واجهة برمجة التطبيقات: https://developers.google.com/discovery/. في بعض الأحيان تتم إضافة ميزات جديدة إلى واجهات برمجة التطبيقات بأسماء غير عادية، مما قد يتسبب في تسمية نمط غير متوقع أو غير قياسي في فئات PHP.
تقوم بعض الخدمات بإرجاع XML أو ما شابه ذلك بشكل افتراضي، بدلاً من JSON، وهو ما تدعمه المكتبة. يمكنك طلب استجابة JSON عن طريق إضافة وسيطة "alt" إلى المعلمات الاختيارية التي عادة ما تكون الوسيطة الأخيرة لاستدعاء الأسلوب:
$ opt_params = array (
' alt ' => " json "
); تقوم المكتبة بإزالة القيم الخالية من الكائنات المرسلة إلى Google APIs لأنها القيمة الافتراضية لجميع الخصائص غير المهيأة. للتغلب على هذه المشكلة، قم بتعيين الحقل الذي تريد إلغاءه إلى GoogleModel::NULL_VALUE . هذا هو العنصر النائب الذي سيتم استبداله بالقيمة الخالية الحقيقية عند إرساله عبر السلك.
قم بإجراء اختبارات PHPUnit باستخدام PHPUnit. يمكنك تكوين مفتاح واجهة برمجة التطبيقات والرمز المميز في BaseTest.php لتشغيل جميع الاستدعاءات، ولكن هذا سيتطلب بعض الإعداد على Google Developer Console.
phpunit tests/
للتحقق من وجود انتهاكات لأسلوب الترميز، قم بتشغيل
vendor/bin/phpcs src --standard=style/ruleset.xml -np
لإصلاح انتهاكات نمط الترميز (القابلة للإصلاح) تلقائيًا، قم بتشغيل
vendor/bin/phpcbf src --standard=style/ruleset.xml
