للمتابعة، تأكَّد من إكمال الخطوات الواردة في المتطلّبات الأساسية ومن أنّنا وافقنا على مشروعك للوصول إلى واجهات برمجة تطبيقات "الملف التجاري على Google".
تفعيل واجهات برمجة التطبيقات
هناك ثماني واجهات برمجة تطبيقات مرتبطة بـ "الملف التجاري على Google" يجب تفعيلها في وحدة تحكّم Google API:
- Google My Business API
- My Business Account Management API
- واجهة برمجة التطبيقات Lodging API في "نشاطي التجاري على Google"
- My Business Place Actions API
- My Business Notifications API
- My Business Verifications API
- My Business Business Information API
- My Business Q&A API
تفعيل واجهة برمجة تطبيقات
إذا أكملت كل المتطلبات الأساسية وتم منحك إذن الوصول إلى واجهة برمجة التطبيقات، ولكن لا يزال يتعذّر عليك استخدام الاختصار المقدَّم، يمكنك تفعيل واجهة برمجة التطبيقات يدويًا باتّباع الخطوات التالية.
لتفعيل واجهة برمجة تطبيقات لمشروعك، اتّبِع الخطوات التالية:
- افتح "مكتبة واجهات برمجة التطبيقات" في "وحدة تحكّم واجهة Google API". اختَر مشروعًا أو أنشئ مشروعًا جديدًا إذا طُلب منك ذلك. تعرض "مكتبة واجهات برمجة التطبيقات" كلّ واجهات برمجة التطبيقات المتاحة، مجمّعة حسب عائلة المنتجات ومدى رواج استخدامها.
- إذا لم تظهر واجهة برمجة التطبيقات التي تريد تفعيلها في القائمة، استخدِم ميزة البحث للعثور عليها.
- اختَر واجهة برمجة التطبيقات التي تريد تفعيلها، ثم انقر على الزر تفعيل.
- فعِّل ميزة الفوترة إذا طُلب منك ذلك.
- اقبل بنود خدمة واجهة برمجة التطبيقات إذا طُلب منك ذلك.
إذا كنت مستخدمًا في Google Workspace، تأكَّد من تفعيل "الملف التجاري على Google" لحسابك في مؤسستك على Google Workspace. ستظهر لك رسالة الخطأ "الخطأ 403 - تم رفض الإذن" عند استخدام واجهات برمجة التطبيقات في "الملف التجاري على Google" إذا تم إيقاف "الملف التجاري على Google" لحسابك في مؤسستك على Google Workspace.
طلب معرّف عميل OAuth 2.0
بما أنّ تطبيقك يصل إلى بيانات محمية وغير علنية، تحتاج إلى معرّف عميل OAuth 2.0. يتيح ذلك لتطبيقك طلب تفويض للوصول إلى بيانات الموقع الجغرافي لمؤسستك نيابةً عن مستخدمي تطبيقك.
يجب أن يرسل تطبيقك رمز OAuth 2.0 مع أي طلب من واجهة برمجة تطبيقات "الملف التجاري على Google" يؤدي إلى الوصول إلى بيانات المستخدمين الخاصة.
إذا لم يسبق لك ذلك، انتقِل إلى قسم "بيانات الاعتماد" في Google API Console وانقر على إنشاء بيانات اعتماد > معرّف عميل OAuth لإنشاء بيانات اعتماد OAuth 2.0. بعد إنشاء بيانات الاعتماد، يمكنك الاطّلاع على معرّف العميل في صفحة بيانات الاعتماد. انقر على معرّف العميل للاطّلاع على التفاصيل، مثل سر العميل ومعرّفات الموارد المنتظمة (URI) لإعادة التوجيه وعنوان مصادر JavaScript وعنوان البريد الإلكتروني.
التعرّف على أساسيات REST
هناك طريقتان لاستدعاء واجهات برمجة التطبيقات:
- أرسِل طلب HTTP وحلِّل الردود.
- استخدام مكتبات العملاء
إذا قرّرت عدم استخدام مكتبات العملاء، عليك فهم أساسيات REST.
REST هو أسلوب لبنية البرامج يقدّم نهجًا ملائمًا ومتسقًا لطلب البيانات وتعديلها.
يشير اختصار REST إلى "Representational State Transfer". في سياق Google APIs، يشير ذلك إلى استخدام أفعال HTTP لاسترداد وتعديل تمثيلات البيانات التي تخزّنها Google.
يخزِّن نظام RESTful الموارد في مستودع بيانات. يرسل العميل طلبًا إلى الخادم لتنفيذ إجراء معيّن، مثل إنشاء مورد أو استرجاعه أو تعديله أو حذفه، وينفّذ الخادم الإجراء ويرسل ردًا. وغالبًا ما يكون هذا الردّ في شكل تمثيل للمورد المحدّد.
في واجهات برمجة التطبيقات RESTful من Google، يحدّد العميل إجراءً باستخدام فعل HTTP، مثل
GET أو POST أو PUT أو DELETE. يحدّد العميل
موردًا باستخدام معرّف موارد موحّد (URI) فريد عالميًا بالشكل التالي:
https://apiName.googleapis.com/apiVersion/resourcePath?parameters
بما أنّ جميع موارد واجهة برمجة التطبيقات تتضمّن عناوين URL فريدة يمكن الوصول إليها من خلال HTTP، تتيح واجهة برمجة التطبيقات REST ميزة تخزين البيانات مؤقتًا وهي محسَّنة للعمل مع البنية الأساسية الموزّعة للويب.
قد تكون تعريفات الطرق في مستندات معايير HTTP 1.1 مفيدة. وتشمل هذه المواصفات GET وPOST وPUT وDELETE.
واجهة برمجة التطبيقات REST في واجهات برمجة تطبيقات "الملف التجاري على Google"
تتمّ ربط عمليات واجهات برمجة تطبيقات "الملف التجاري على Google" مباشرةً بأفعال REST HTTP.
يظهر التنسيق المحدّد لواجهات برمجة تطبيقات "الملف التجاري على Google" في عنوان URL التالي:
https://apiName.googleapis.com/apiVersion/resourcePath?parameters
تظهر المجموعة الكاملة لمعرّفات الموارد المنتظمة (URI) المستخدَمة لكلّ عملية متاحة في واجهات برمجة التطبيقات في مستندات مرجع واجهات برمجة تطبيقات "الملف التجاري على Google".
تختلف مسارات الموارد حسب نقطة النهاية.
على سبيل المثال، يظهر مسار المورد إلى حساب على النحو الموضّح في المثال التالي:
accounts/accountId
يظهر مسار المرجع لموقع جغرافي على النحو التالي:
locations/locationId
التعرّف على أساسيات تنسيق JSON
تعرض واجهات برمجة تطبيقات "الملف التجاري على Google" البيانات بتنسيق JSON.
JavaScript Object Notation (JSON) هو تنسيق بيانات شائع لا يعتمد على اللغة، ويقدّم تمثيلاً نصيًا بسيطًا لبنى البيانات العشوائية. لمزيد من المعلومات، يُرجى الاطّلاع على json.org.
استخدام Oauth Playground لتقديم طلب HTTP بسيط
يمكنك استخدام مساحة بروتوكول OAuth 2.0 للتجربة واجهات برمجة تطبيقات "الملف التجاري على Google". بما أنّ واجهات برمجة تطبيقات "الملف التجاري على Google" ليست واجهات برمجة تطبيقات عامة، عليك اتّخاذ بعض الخطوات الإضافية لاستخدامها في Playground. تحتاج إلى معرِّف عميل لتطبيق ويب لمتابعة الخطوات.
- انتقِل إلى وحدة تحكّم واجهة برمجة التطبيقات Google وافتح مشروعك. إذا لم يكن لديك معرِّف عميل OAuth لتطبيقات الويب، أنشِئ معرِّفًا الآن:
- من القائمة المنسدلة إنشاء بيانات اعتماد، اختَر معرِّف عميل OAuth.
- في حقل نوع التطبيق، انقر على تطبيق الويب.
أضِف ما يلي بصفته معرّف موارد منتظمًا صالحًا لإعادة التوجيه:
https://developers.google.com/oauthplayground
- انقر على إنشاء.
- انسخ معرّف العميل إلى الحافظة.
- انتقِل إلى مساحة بروتوكول OAuth 2.0.
- انقر على رمز الترس لفتح خيارات الضبط وإجراء التغييرات التالية:
- اضبط مسار OAuth على جانب العميل.
- انقر على استخدام بيانات اعتماد OAuth الخاصة بك.
- الصِق معرِّف عميل OAuth.
- أغلِق خيارات الضبط.
ضمن "الخطوة 1: اختيار واجهات برمجة التطبيقات وتفويضها"، ألصِق النطاق التالي لواجهات برمجة تطبيقات "الملف التجاري على Google" في حقل إدخال النطاقات الخاصة بك:
https://www.googleapis.com/auth/business.manage
- انقر على تفويض واجهات برمجة التطبيقات.
- انقر على قبول عندما يُطلب منك ذلك.
-
ضمن "الخطوة 2: ضبط الطلب المُرسَل إلى واجهة برمجة التطبيقات"، الصِق عنوان URL التالي في الحقل عنوان URL للطلب:
https://mybusinessaccountmanagement.googleapis.com/v1/accounts
- انقر على إرسال الطلب. من المفترض أن يعرض الردّ الحالة
200 OK.
لمزيد من المعلومات عن كيفية تقديم أنواع مختلفة من الطلبات، يُرجى الاطّلاع على مرجع واجهات برمجة تطبيقات "الملف التجاري على Google".
مكتبات العملاء
توفّر مكتبات عملاء واجهات برمجة تطبيقات "الملف التجاري على Google" وظائف هذه الواجهات. وتوفّر هذه الواجهات وظائف مشتركة بين جميع واجهات برمجة تطبيقات Google، مثل نقل HTTP ومعالجة الأخطاء والمصادقة وتحليل JSON.
لتنزيل مكتبات العملاء، اطّلِع على المكتبات.