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

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

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

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

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

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

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

لتمكين واجهة برمجة تطبيقات لمشروعك، قم بما يلي:

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

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

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

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

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

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

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

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

إذا قررت عدم استخدام مكتبات العملاء، عليك فهم أساسيات 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 في واجهات برمجة تطبيقات الملف التجاري

ترتبط عمليات Business Profile API مباشرةً بأفعال HTTP التي تتضمّن REST.

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

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

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

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

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

accounts/accountId

يظهر مسار المورد لموقع ما بالشكل التالي:

locations/locationId

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

تعرض Business Profile API البيانات بتنسيق JSON.

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

إجراء طلب HTTP بسيط

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

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

    3. أضف ما يلي باعتباره عنوان URL صالحًا لإعادة التوجيه:

       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 وظائف واجهات برمجة تطبيقات الملفات التجارية. وهي توفر وظائف مشتركة بين جميع واجهات Google APIs، مثل نقل HTTP ومعالجة الأخطاء والمصادقة وتحليل JSON.

لتنزيل مكتبات العملاء، راجع المكتبات.