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

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

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

ملاحظة: لا تظهر واجهة برمجة تطبيقات "نشاطي التجاري على Google" في وحدة التحكم في واجهة Google API إلا للمستخدمين الذين يرسلون موافقات على حساباتهم على 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 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) المستخدَمة لكل عملية متوافقة في واجهات برمجة التطبيقات في المستند المرجعي الخاص بواجهات برمجة تطبيقات الملف التجاري.

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

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

accounts/accountId

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

locations/locationId

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

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

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

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

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

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" في الردّ.

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

ملاحظة: لا تتوفّر بيئة وضع الحماية لواجهات برمجة تطبيقات الملف التجاري. وتسمح بعض الطلبات باستخدام معلَمة طلب بحث validateOnly تعمل على التحقّق من صحة الطلب بدون إجراء أي تغييرات عند ضبطه على القيمة true.

ملاحظة: يضيف ملعب OAuth 2.0 عناوين تصحيح الأخطاء تلقائيًا. إذا كنت تستخدم برنامجًا مختلفًا وأردت عرض رسائل خطأ مفصّلة في الردّ، أضِف العنوان التالي إلى الطلب: X-GOOG-API-FORMAT-VERSION: 2

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

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

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