تنفيذ خادم الحجز

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

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

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

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

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

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

الطُرق

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

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

الطريقة	طلب HTTP
HealthCheck	GET ‎ /v3/HealthCheck/
BatchAvailabilityLookup	POST ‎ /v3/BatchAvailabilityLookup/
CreateBooking	POST ‎ /v3/CreateBooking/
UpdateBooking	POST ‎ /v3/UpdateBooking/
GetBookingStatus	POST /v3/GetBookingStatus/
ListBookings	POST ‎ /v3/ListBookings/

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

الحجز

يتم استخدام أنواع الموارد التالية في التنفيذ العادي:

• الخانة: خانة مستودع.
• الحجز: موعد لحجز خانة مستودع إعلاني.

المسار: إنشاء حجز

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

الشكل 1: سير العمل لإنشاء حجز من خانة

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

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

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

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

ملاحظة: يجب ضبط اسم المستخدم وكلمة المرور لكل من Sandbox و"الإنتاج" بشكل منفصل باستخدام مبدِّل البيئات.

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

للبدء، اطّلِع على نماذج الهياكل التالية لخادم الحجز المكتوبة لإطارَي عمل 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. النشاط التجاري قد تحدث أخطاء منطقية عند إنشاء مورد أو تعديله. على سبيل المثال، عند معالجة الطريقتَين CreateBooking أو UpdatingBooking. وتشمل الأمثلة على سبيل المثال لا الحصر: ما يلي:

• يتم استخدام SLOT_UNAVAILABLE إذا لم تعُد الفتحة المطلوبة متاحة.
• يتم استخدام PAYMENT_ERROR_CARD_TYPE_REJECTED إذا لم يتم قبول نوع بطاقة الائتمان الذي تم تقديمه

الثبات

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

• CreateBooking
• UpdateBooking

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

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

• تتضمّن استجابة HTTP CreateBooking الناجحة الحجز الذي تم إنشاؤه. في بعض الحالات، تتم معالجة الدفعة كجزء من عملية الحجز. إذا تم استلام CreateBookingRequest نفسه للمرة الثانية (مع idempotency_token نفسه)، يجب إرجاع CreateBookingResponse نفسه. لا يتم إنشاء حجز ثانٍ، ويتم تحصيل رسوم من المستخدم مرة واحدة فقط، إذا كان ذلك منطبقًا.

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

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