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

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

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

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

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

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

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

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

مدى التوفّر استبدال 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 Maps Booking API (إصدار مطوّري البرامج)

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

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

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

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

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

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

استرجاع مستند "اقتراحات"

بالنسبة إلى بعض مكتبات البرامج، مثل 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()