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

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

لا تكون التعديلات في الوقت الفعلي ضرورية إذا كان جميع التجّار يستخدمون ميزة "قائمة الانتظار".

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

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

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

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

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

Availability Replace API RTU

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

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

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

إصدار نهائي من واجهة برمجة التطبيقات Booking Notification API

تُرسِل Booking Notification APIs إشعارًا إلى 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" لإنشاء حساب خدمة. احفظ المفتاح الخاص بتنسيق JSON في مكان آمن. عند إنشاء الحساب، يمكنك ضبط الدور على "مالك".

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

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

  • Google Maps Booking API
  • Google Maps Booking API (للمطوّرين)

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

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

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

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

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

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

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

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

استخدِم الأمر التالي لتحميل مستند "الاستكشاف":

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