الخطوة 4: تطبيق خادم الحجز

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

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

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

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

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

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

الطُرق

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

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

الطريقة	طلب HTTP
HealthCheck	الحصول على /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) صالحة تتطابق مع اسم نظام أسماء النطاقات الخاص به. للمساعدة في إعداد الخادم، ننصحك باستخدام أداة تحقُّق متاحة للجميع باستخدام طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل (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 حسنًا، وحدِّد الخطأ المنطقي للنشاط التجاري في نص الاستجابة. تختلف أنواع أخطاء منطق الأعمال التي يمكن أن تواجهها باختلاف الأنواع المختلفة من عمليات تنفيذ الخادم.

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

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

العجزية

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

• CreateBooking
• UpdateBooking

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

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

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

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

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