الخطوة 5: تحديثات واجهة برمجة التطبيقات في الوقت الفعلي

تتفاوت المستودعات في نظامك على مدار اليوم بسبب الحجوزات الجديدة والإلغاءات والتغييرات في الجداول الزمنية التي يجريها التجّار. توفّر واجهة برمجة التطبيقات الخاصة بالتعديل في الوقت الفعلي آلية لإعلام Google بهذه التغييرات في مدى توفّر المستودع. يمكنك أيضًا استخدام تحديثات واجهة برمجة التطبيقات في الوقت الفعلي لإعلام Google بالتغييرات التي يتم إجراؤها على الحجوزات الحالية.

التحديثات والخلاصات في الوقت الفعلي لواجهة برمجة التطبيقات

تُستخدَم التعديلات في الوقت الفعلي التي يتم إجراؤها من خلال واجهة برمجة التطبيقات لإعلام Google بالتغييرات التدريجية في مدى توفّر المستودع والحجوزات فور حدوثها. بالإضافة إلى تعديلات واجهة برمجة التطبيقات في الوقت الفعلي، أرسِل خلاصات "معلومات التوفّر" كاملة يوميًا لضمان حصول Google على معلومات دقيقة وحديثة عن التوفّر كما هي في نظامك. تعمل الخلاصات الكاملة كلقطة لحالة توفّر المستودع الحالية في نظامك.

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

واجهات برمجة التطبيقات المطلوبة لتحديث البيانات في الوقت الفعلي

واجهات برمجة التطبيقات الخاصة بالتحديث في الوقت الفعلي
BookingNotification	إلزامي	أرسِل وحدات وقتية في الوقت الفعلي من نوع BookingNotification كلما حدث تغيير في الحجز (مثل التعديلات أو عمليات الإلغاء).
استبدال رمز وحدة التخزين (RTU) الخاص بمدى التوفّر	مطلوب بشكل مشروط[1]	أرسِل وحدات RTU من نوع استبدال مجمّع أو استبدال فردي لإرسال تعديلات بشأن مدى توفّر المستودع. قد يستغرق نشر التغييرات وظهورها عدة دقائق.
رمز التخزين التعريفي للتاجر	اختياري	أرسِل وحدات RTU الخاصة بالتاجر إذا أردت إجراء تغييرات على معلومات التاجر في الوقت الفعلي. وقد يستغرق نشر التغييرات وظهورها عدّة ساعات.
Service RTU	اختياري	أرسِل وحدات وقت التشغيل الخاصة بالخدمة إذا أردت إجراء تغييرات على معلومات الخدمة في الوقت الفعلي. من الحالات الشائعة التي يُنصح فيها بتنفيذ وحدات RTU للخدمات، تلك التي تتغير فيها أسعار الخدمات بشكل كبير خلال اليوم، وذلك لتجنُّب فشل الطلبات بسبب عدم تطابق الأسعار. وقد يستغرق نشر التغييرات وظهورها عدّة ساعات.

ملاحظة: يتغيّر شرط نقطة النهاية هذه استنادًا إلى عملية الدمج. يُرجى التواصل مع جهة اتصال Google التي تتعامل معها لتحديد نقاط النهاية المطلوبة.

Availability Replace API RTU

استخدِم واجهة برمجة التطبيقات Availability Replace API لتقديم تعديلات على معلومات التوفّر في حالات الاستخدام التالية:

• يحجز المستخدم موعدًا في نظامك، وبالتالي لن يعود خانة المواعيد المتاحة متوفرة.
• يغيّر التاجر مدى توفّره في نظامك.
• يحجز المستخدم موعدًا من خلال Google، وبالتالي لن يعود الموعد متاحًا.
• تم إلغاء حجز تم إجراؤه من خلال Google من جهتك، مثلاً، من قِبل التاجر مباشرةً. عليك تعديل الحجز ومدى التوفّر لأنّ خانة الموعد الأصلية أصبحت متاحة من جديد.
• يؤدي طلب BatchAvailabilityLookup من خادم الحجز إلى عرض مستودع إعلاني لا يتطابق مع المستودع الإعلاني الفعلي.

لمزيد من المعلومات، يُرجى الاطّلاع على المراجع التالية:

• برنامج تعليمي: كيفية تنظيم الإشعارات في الوقت الفعلي
• مثال على عميل Java لتلقّي التعديلات في الوقت الفعلي باستخدام طلبات RESTful
• صفحة مرجع واجهة برمجة التطبيقات لتعديل المستودع الإعلاني

Booking Notification API RTU

تُعلم واجهات برمجة التطبيقات الخاصة بإشعارات الحجز Google بالتعديلات التي يتم إجراؤها على الحجوزات الحالية. عند إرسال إشعار بشأن عمليات الإلغاء، أرسِل المعلومات الأساسية فقط في الطلب باستخدام مَعلمة طلب البحث updateMask. يُرجى الاطّلاع على المثال أدناه:

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"CANCELED"}

الوصول إلى واجهة برمجة التطبيقات

إنشاء حساب خدمة

استخدِم علامة التبويب بيانات الاعتماد في "وحدة تحكّم Google API" من أجل إنشاء حساب خدمة. احفظ المفتاح الخاص بتنسيق JSON في مكان آمن. عند إنشاء الحساب، يمكنك ضبط الدور على "المالك".

مصادقة واجهات Maps Booking API

بعد إنشاء حساب خدمة، عليك المصادقة على واجهات برمجة التطبيقات التالية:

• Google Maps Booking API
• Google Maps Booking API (Dev)

للحصول على دليل مفصّل حول كيفية إجراء ذلك، يُرجى الرجوع إلى البرنامج التعليمي المصادقة باستخدام Maps Booking API.

استخدام طلبات RESTful أو تنزيل مكتبة البرامج

ننصحك بإجراء طلبات RESTful مباشرةً إلى Maps Booking API باستخدام حمولات JSON. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات REST API.

يمكنك أيضًا استخدام مكتبات برامج العميل للاتصال بواجهة برمجة التطبيقات.

اللغة	رابط التنزيل
Java	مكتبة برامج Java لمزيد من المعلومات، يُرجى الاطّلاع على تعليمات عميل Java.

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

استرجاع مستند Discovery

بالنسبة إلى بعض مكتبات البرامج، مثل Ruby، من الضروري استرداد مستند Discovery الخاص بواجهة برمجة التطبيقات، والذي يصف طرقها ومَعلماتها.

استخدِم الأمر التالي لجلب مستند Discovery:

curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'

للحصول على مزيد من المعلومات حول الوصول إلى واجهة برمجة التطبيقات من Ruby، يُرجى اتّباع الروابط التالية: Ruby API Client و Ruby Auth Library.

إجراء طلبات معتمَدة إلى واجهة برمجة التطبيقات

عند إجراء طلبات إلى واجهة برمجة التطبيقات، يُرجى الرجوع إلى الاستعداد لإجراء طلب بيانات معتمد من واجهة برمجة التطبيقات لتفويض حساب الخدمة باستخدام مفتاحك الخاص ونطاق OAuth التالي: https://www.googleapis.com/auth/mapsbooking.

حصص واجهة برمجة التطبيقات

يبلغ الحدّ الأقصى لطلبات التعديل في واجهة برمجة التطبيقات 1,500 طلب كل 60 ثانية، أو 25 طلبًا في الثانية في المتوسط. عند تجاوز الحصة (وهو ما يمكن أن يحدث عندما لا تضيف رقم مشروع Google Cloud الصحيح في "بوابة الشريك")، ستردّ Google برسالة الخطأ التالية:

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

للتعامل مع هذه المشكلة، أعِد محاولة إجراء المكالمة مرة أخرى على فترات زمنية أكبر بشكل مضاعف إلى أن تنجح. إذا كنت تستنفد الحصة بانتظام باستخدام ReplaceServiceAvailability، انتقِل إلى BatchReplaceServiceAvailabily لتقليل عدد طلبات البيانات من واجهة برمجة التطبيقات. تتيح لك هذه الطريقة تعديل خدمات متعددة في طلب واحد لواجهة برمجة التطبيقات.

نقاط نهاية وضع الحماية والإنتاج

يمكنك إجراء طلبات إلى كلّ من بيئة وضع الحماية وبيئة الإنتاج من خلال واجهة برمجة التطبيقات. تأكَّد من تفعيل كلتا واجهتَي برمجة التطبيقات في مشروعك على Google Cloud. تستخدم كلتا واجهتَي برمجة التطبيقات هذه النطاق نفسه، ولكن لديهما نقاط نهاية مختلفة.

نقطة النهاية الخاصة بالإنتاج: https://mapsbooking.googleapis.com/

نقطة نهاية وضع الحماية: https://partnerdev-mapsbooking.googleapis.com/

في ما يلي مثال بلغة Java على كيفية تبديل نقاط النهاية:

    // This block of code is for OAuth and is the same for prod and sandbox.
    GoogleCredential
      .fromStream(new FileInputStream(...))
      .createScoped(Collections.singleton("https://www.googleapis.com/auth/mapsbooking"))

    // This block of code sets the endpoint. This is what you'd change to connect to the sandbox.
    new GoogleMapsBookingAPI.Builder(...)
      .setApplicationName(...)
      .setRootUrl("https://partnerdev-mapsbooking.googleapis.com/") // you add this to change the endpoint to use partnerdev.
      .build()