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

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

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

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

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

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

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

مدى التوفر لواجهة برمجة تطبيقات استبدال مدى التوفّر

استخدِم واجهة برمجة التطبيقات لاستبدال مدى التوفّر لتقديم تحديثات بشأن مدى التوفّر في حالات الاستخدام التالية:

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

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

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 في مكان آمن. عند إنشاء الحساب، يتوفّر لك خيار ضبط الدور على "مالك".

مصادقة واجهات برمجة تطبيقات الحجز على "خرائط Google"

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

  • Google Maps Booking API
  • واجهة برمجة تطبيقات الحجز في "خرائط Google" (إصدار داخلي للتطوير)

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

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

ننصحك بإجراء طلبات RESTful مباشرةً في "واجهة برمجة تطبيقات الحجز" في "خرائط Google" باستخدام أحمال JSON. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على مستندات REST API.

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

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

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

جلب مستند 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 Project الصحيح في "بوابة الشريك")، تستجيب Google برسالة الخطأ التالية:

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

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

Sandbox والإنتاج بنقاط نهاية

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

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

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

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

    // 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()