الإعداد الأساسي

للمتابعة، تأكَّد من إكمال الخطوات في المتطلبات الأساسية وموافقتنا على مشروعك في "الملف التجاري على Google" الوصول إلى واجهات برمجة التطبيقات.

تفعيل واجهات برمجة التطبيقات

هناك ثمانية واجهات برمجة تطبيقات مرتبطة بالملف التجاري يجب تفعيلها في Google API. وحدة التحكم:

• Google My Business API
• واجهة برمجة التطبيقات لإدارة حساب نشاطي التجاري
• واجهة برمجة تطبيقات خدمة الإقامة في "نشاطي التجاري"
• واجهة برمجة تطبيقات إجراءات الأماكن في نشاطي التجاري
• My Business Notifications API
• واجهة برمجة تطبيقات التحقّق من نشاطي التجاري
• واجهة برمجة تطبيقات معلومات نشاطي التجاري
• واجهة برمجة تطبيقات الأسئلة والأجوبة في نشاطي التجاري

تفعيل واجهة برمجة تطبيقات

إذا كنت قد أكملت جميع الشروط الأساسية وتم منحها إمكانية الوصول إلى واجهة برمجة التطبيقات، ولكن لا تزال غير قادرة على ذلك لاستخدام الاختصار المقدَّم، يمكنك تفعيل واجهة برمجة التطبيقات يدويًا من خلال الخطوات التالية.

لتفعيل واجهة برمجة تطبيقات لمشروعك، اتّبِع الخطوات التالية:

1. افتح مكتبة واجهة برمجة التطبيقات في وحدة التحكم في واجهة Google API. إذا طُلب منك، اختَر أو إنشاء مشروع جديد. تسرد مكتبة واجهة برمجة التطبيقات جميع البيانات المتاحة واجهات برمجة التطبيقات، مجمّعة حسب مجموعة المنتجات ومدى رواجها
2. إذا لم تكن واجهة برمجة التطبيقات التي تريد تفعيلها ظاهرة في القائمة، استخدِم ميزة البحث من أجل العثور عليها.
3. اختَر واجهة برمجة التطبيقات التي تريد تفعيلها، ثم انقر على تفعيل. .
4. فعِّل الفوترة إذا طُلب منك ذلك.
5. اقبل بنود خدمة واجهة برمجة التطبيقات إذا طُلب منك ذلك.

إذا كنت أحد مستخدمي Google Workspace، تأكَّد من أنّ الملف التجاري على Google مفعَّل لحسابك في مؤسستك على Google Workspace. ستظهر لك "الخطأ 403 - Permission DENIED" عند استخدام واجهات برمجة تطبيقات "الملف التجاري على Google" في حال إيقاف "الملف التجاري على Google" لحسابك في مؤسستك على Google Workspace.

طلب معرِّف عميل OAuth 2.0

بما أنّ تطبيقك يصل إلى بيانات محمية وغير علنية، يجب أن يكون لديك معرِّف عميل OAuth 2.0. يسمح هذا الإجراء لتطبيقك بطلب تفويض للوصول إلى بيانات الموقع الجغرافي لمؤسستك نيابةً عن مستخدمي تطبيقك.

يجب أن يرسل تطبيقك رمز OAuth 2.0 المميز مع أي طلب من واجهات برمجة التطبيقات في "الملف التجاري على Google" الذي يصل إلى بيانات المستخدم الخاصة.

انتقِل إلى "بيانات الاعتماد" إذا لم يسبق لك ذلك. في وحدة التحكم في واجهة Google API وانقر على إنشاء بيانات الاعتماد > معرِّف عميل OAuth لإنشاء بيانات اعتماد OAuth 2.0. بعد إنشاء بيانات الاعتماد، يمكنك الاطلاع على معرِّف العميل في صفحة بيانات الاعتماد. انقر على معرِّف العميل للاطّلاع على التفاصيل، مثل سر العميل ومُعرّفات الموارد المنتظمة (URI) لإعادة التوجيه وعنوان مصادر JavaScript والبريد الإلكتروني الخاص بك.

التعرُّف على أساسيات REST

هناك طريقتان لاستدعاء واجهات برمجة التطبيقات:

• إرسال طلب HTTP وتحليل الاستجابات.
• استخدام مكتبات البرامج

إذا قررت عدم استخدام مكتبات العملاء، فستحتاج إلى فهم أساسيات REST.

REST هو نمط من بنية البرامج التي توفر نهجًا مناسبًا ومتسقًا طلب البيانات وتعديلها.

الاختصار REST هو اختصار "نقل الحالة التمثيلية" في سياق Google APIs، يشير إلى استخدام أفعال HTTP لاسترداد تمثيلات البيانات التي تخزنها Google وتعديلها.

يخزن نظام REST الموارد في مخزن بيانات. يرسل العميل طلبًا تنفيذ إجراء معين مثل إنشاء مورد أو استرداده أو تحديثه أو حذفه وينفذ الخادم الإجراء ويرسل ردًا. غالبًا ما يكون هذا الرد في شكل تمثيل للمورد المحدد.

في واجهات برمجة تطبيقات RESTful من Google، يحدد العميل إجراءً باستخدام فعل HTTP، مثل GET أو POST أو PUT أو DELETE يحدد العميل مورد من خلال معرّف موارد منتظم (URI) عالمي فريد بالنموذج التالي:

https://apiName.googleapis.com/apiVersion/resourcePath?parameters

نظرًا لأن جميع موارد واجهة برمجة التطبيقات تتضمن معرفات موارد منتظمة (URI) فريدة يمكن الوصول إليها عبر HTTP، فإن REST تمكّن التخزين المؤقت للبيانات بشكل أفضل للعمل مع البنية الأساسية الموزَّعة على الويب.

قد تجد تعريفات الطريقة في مستندات معايير HTTP 1.1 مفيدة. وتشمل مواصفات GET وPOST وPUT و DELETE

وضع REST في واجهات برمجة تطبيقات الملف التجاري

تربط عمليات واجهات برمجة تطبيقات الملف التجاري مباشرةً بأفعال HTTP في REST.

يظهر التنسيق المحدَّد لواجهات برمجة تطبيقات الملف التجاري في معرّف الموارد المنتظم (URI) التالي:

https://apiName.googleapis.com/apiVersion/resourcePath?parameters

تظهر المجموعة الكاملة من معرّفات الموارد المنتظمة (URI) المستخدَمة لكل عملية متوافقة في واجهات برمجة التطبيقات في Business Profile API. المستندات المرجعية

تختلف مسارات الموارد استنادًا إلى نقطة النهاية.

على سبيل المثال، يظهر مسار المورد إلى أحد الحسابات كما في المثال التالي:

accounts/accountId

يظهر مسار المورد لموقع جغرافي في النموذج التالي:

locations/locationId

التعرّف على أساسيات JSON

تعرض واجهات برمجة تطبيقات الملف التجاري البيانات بتنسيق JSON.

JavaScript Object Notation (JSON) هو تنسيق بيانات شائع ومستقل عن اللغة تمثيلاً نصيًا بسيطًا لهياكل البيانات العشوائية. لمزيد من المعلومات، يُرجى مراجعة json.org.

استخدام Oauth Playground لإنشاء طلب HTTP بسيط

يمكنك استخدام صفحة ملعب OAuth 2.0 لإجراء تجارب باستخدام واجهات برمجة تطبيقات Business Profile. وذلك لأنّ واجهات برمجة تطبيقات الملف التجاري ليست واجهات برمجة تطبيقات عامة، فهناك بعض الخطوات الإضافية التي عليك اتخاذها لاستخدامها في "مساحة المرح". إِنْتَ بحاجة إلى معرِّف عميل لتطبيق ويب للمتابعة.

1. انتقِل إلى وحدة التحكم في واجهة Google API. وفتح مشروعك. إذا لم يكن لديك معرِّف عميل OAuth لتطبيقات الويب، عليك إنشاء معرِّف. الآن:
1. من القائمة المنسدلة إنشاء بيانات الاعتماد، اختَر معرِّف عميل OAuth.
2. في نوع التطبيق، انقر على تطبيق الويب.

3. أضِف ما يلي كمعرّف موارد منتظم (URI) صالح لإعادة التوجيه:

    https://developers.google.com/oauthplayground
    

4. انقر على إنشاء.
2. نسخ معرِّف العميل إلى الحافظة
3. انتقِل إلى مساحة بروتوكول OAuth 2.0.
4. انقر على رمز الترس لفتح خيارات الضبط وإجراء التغييرات التالية:
1. اضبط تدفق OAuth على من جهة العميل.
2. اختَر استخدام بيانات اعتماد OAuth.
3. الصِق معرِّف عميل OAuth.
5. أغلق خيارات الضبط.

6. ضمن "الخطوة 1 - تحديد & وتفويض واجهات برمجة التطبيقات"، الصق النطاق التالي واجهات برمجة تطبيقات الملف التجاري في الحقل إدخال النطاقات الخاصة بك:

   https://www.googleapis.com/auth/business.manage
   

7. انقر على تفويض واجهات برمجة التطبيقات.
8. انقر على قبول عندما يُطلب منك ذلك.

9. ضمن "الخطوة 2 - ضبط الطلب لواجهة برمجة التطبيقات"، الصق عنوان URI التالي في حقل عنوان URI للطلب:

   https://mybusinessaccountmanagement.googleapis.com/v1/accounts
   

10. انقر على إرسال الطلب. من المفترض أن تظهر حالة "200 OK" في الردّ.

لمزيد من المعلومات عن كيفية تقديم أنواع مختلفة من الطلبات، يُرجى الاطّلاع على مرجع واجهات برمجة التطبيقات للملف التجاري.

مكتبات العملاء

تتيح مكتبات عملاء "Business Profile API" وظائف واجهات برمجة تطبيقات Business Profile. تقدِّم وظيفة شائعة بين جميع واجهات برمجة تطبيقات Google، مثل نقل HTTP، ومعالجة الأخطاء، والمصادقة، وتحليل JSON.

لتنزيل مكتبات العملاء، يُرجى الاطّلاع على المكتبات.