الخطوة 3: تنفيذ خادم الحجز في قوائم الانتظار

عليك إعداد خادم حجوزات للسماح لـ "مركز الإجراءات" بإجراء عمليات معاودة الاتصال لإنشاء الحجوزات وتعديلها نيابةً عنك.

• تنفيذ قوائم انتظار الحجوزات: يتم استخدام هذا عند المشاركة في برنامج "قوائم الانتظار للحجز" التجريبي. يتيح ذلك لتطبيق "مركز الإجراءات" استرجاع تقديرات وقت الانتظار وإنشاء إدخالات في قائمة الانتظار نيابةً عن المستخدم.
• التنفيذ العادي: يتيح ذلك لتطبيق "مركز الإجراءات" إنشاء مواعيد وحجوزات معك نيابةً عن العميل. لتنفيذ خادم حجوزات لدمج ميزة "الحجوزات الشاملة"، يُرجى الرجوع إلى مقالة تنفيذ خادم الحجوزات.

يُرجى الرجوع إلى مستندات Partner Portal للتعرّف على كيفية ضبط عملية الربط بخادمَي الحجز في الوضع التجريبي والوضع العلني.

تنفيذ واجهة برمجة تطبيقات REST

تنفيذ واجهة برمجة تطبيقات استنادًا إلى REST: يتيح ذلك لـ Google إرسال طلبات خادم الحجز عبر HTTP.

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

الطُرق

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

تنفيذ قائمة الانتظار
تعريف خدمة قائمة الانتظار نزِّل ملف تعريف خدمة proto.

الطريقة	طلب HTTP
HealthCheck	GET ‎ /v3/HealthCheck/
BatchGetWaitEstimates	POST ‎ /v3/BatchGetWaitEstimates/
CreateWaitlistEntry	POST ‎ /v3/CreateWaitlistEntry/
GetWaitlistEntry	POST ‎ /v3/GetWaitlistEntry/
DeleteWaitlistEntry	POST /v3/DeleteWaitlistEntry/

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

Waitlist

تُستخدَم المراجع التالية لتنفيذ الحجز المستنِد إلى قائمة الانتظار:

• WaitEstimate: تقدير وقت الانتظار لحجم منتدى معيّن وتاجر معيّن.
• ‫WaitlistEntry: إدخال المستخدم في قائمة الانتظار

المسار: إنشاء إدخال في قائمة الانتظار

يتناول هذا القسم كيفية إنشاء حجز لدمج قوائم الانتظار للحجوزات.

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

الأمان والمصادقة

تتم جميع عمليات التواصل مع خادم الحجز من خلال بروتوكول HTTPS، لذا يجب أن يكون لدى خادمك شهادة بروتوكول أمان طبقة النقل (TLS) صالحة تتطابق مع اسم نظام أسماء النطاقات. للمساعدة في إعداد الخادم، ننصحك باستخدام أداة مجانية للتحقّق من بروتوكول أمان طبقة النقل أو طبقة المقابس الآمنة، مثل اختبار خادم بروتوكول أمان طبقة النقل من Qualys.

سيتم مصادقة كل الطلبات التي ترسلها Google إلى خادم الحجز باستخدام مصادقة HTTP الأساسية. يمكن إدخال بيانات اعتماد المصادقة الأساسية (اسم المستخدم وكلمة المرور) لخادم الحجز في صفحة "إعدادات خادم الحجز" ضمن بوابة الشركاء. يجب تغيير كلمات المرور كل ستة أشهر.

أمثلة على عمليات تنفيذ الهيكل

للبدء، اطّلِع على نماذج الهياكل التالية لخادم الحجز المكتوبة لإطارَي عمل Node.js وJava:

• هيكل Node.js js-maps-booking-rest-server-v3-skeleton
• هيكل Java java-maps-booking-rest-server-v3-skeleton

تم إيقاف طرق REST في هذه الخوادم.

المتطلبات

أخطاء HTTP وأخطاء منطق النشاط التجاري

عند معالجة طلبات HTTP من خلال الخلفية، قد يحدث نوعان من الأخطاء.

• الأخطاء المرتبطة بالبنية الأساسية أو البيانات غير الصحيحة
  • عرض هذه الأخطاء على العميل باستخدام رموز أخطاء HTTP العادية يمكنك الاطّلاع على قائمة رموز حالة HTTP الكاملة.
• الأخطاء المرتبطة بمنطق النشاط التجاري
  • يجب عرض رمز حالة HTTP على القيمة 200 OK، وتحديد خطأ منطق النشاط التجاري في نص الاستجابة. تختلف أنواع أخطاء منطق النشاط التجاري التي يمكنك مواجهتها حسب الأنواع المختلفة لعمليات تنفيذ الخادم.

بالنسبة إلى عملية دمج قوائم الانتظار للحجز، يتم تسجيل أخطاء منطق النشاط التجاري في تعذُّر منطق قائمة الانتظار ويتم عرضها في استجابة HTTP. قد تحدث أخطاء في منطق النشاط التجاري عند إنشاء موارد ، على سبيل المثال عند التعامل مع الإجراء CreateWaitlistEntry. وتشمل الأمثلة على سبيل المثال لا الحصر:

• يتم استخدام القيمة ABOVE_MAX_PARTY_SIZE عندما يكون الإدخال المطلوب في قائمة الانتظار أكبر من الحد الأقصى لعدد أفراد المجموعة لدى التاجر.
• يتم استخدام القيمة MERCHANT_CLOSED عندما تكون قائمة الانتظار غير مفتوحة لأنّه تم إغلاق حساب التاجر.

الثبات

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

• CreateWaitlistEntry
• DeleteWaitlistEntry

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

في ما يلي بعض الأمثلة على كيفية تعامل خوادم الحجز مع الثبات:

• تتضمّن استجابة HTTP الناجحة CreateWaitlistEntry رقم تعريف إدخال قائمة الانتظار الذي تم إنشاؤه. إذا تم تلقّي CreateWaitlistEntryRequest نفسه للمرة الثانية (مع idempotency_token نفسه)، يجب إرجاع CreateWaitlistEntryResponse نفسه. لا يتم إنشاء إدخال ثانٍ في قائمة الانتظار ولا يتم عرض أي خطأ.

  يُرجى العِلم أنّه في حال تعذّر إتمام محاولة CreateWaitlistEntry وتمت إعادة إرسال الطلب نفسه، من المفترض أن تعيد الخلفية المحاولة في هذه الحالة.

ينطبق شرط الثبات على جميع الطرق التي تغيّر الحالة.