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

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

• التنفيذ العادي: يتيح ذلك لميزة "الحجز عبر Google" إنشاء مواعيد وحجوزات وحجوزات معك نيابةً عن المستخدم.

يمكنك الرجوع إلى مستندات بوابة الشريك لمعرفة كيفية ضبط الاتصال بخوادم وضع الحماية وحجز الإنتاج.

تنفيذ واجهة REST API

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

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

الطُرق

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

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

الطريقة	طلب HTTP
التحقق من الصحة	GET /v3/HealthCheck/
BatchAvailabilityLookup	POST /v3/BatchAvailabilityLookup/
إنشاء حجز	POST /v3/CreateBooking/
تحديث الحجز	POST /v3/UpdateBooking/
GetBookingStatus	POST /الإصدار 3/GetBookingStatus/
حجوزات الكتب	POST /الإصدار 3/ListBookings/

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

الحجز

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

• خانة: شريحة مستودع.
• الحجز: موعد مخصّص لشريحة من المستودع.

التدفق: إنشاء حجز

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

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

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

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

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

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

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

نماذج من تنفيذ هياكل عظمية

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

• Node.js هيكل عظمي js-maps-booking-rest-server-v3-skeleton
• هيكل عظمي بلغة جافا java-maps-booking-rest-server-v3-skeleton

هذه الخزائن قد استرقت طرق REST.

المتطلّبات

أخطاء HTTP وأخطاء منطق تسلسل العمل

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

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

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

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

عدم القدرة

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

• CreateBooking
• UpdateBooking

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

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

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

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

ينطبق شرط الاستقلالية على جميع الطرق التي تؤدي إلى تبديل الحالة.