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

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

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

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

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

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

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

الطُرق

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

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

الطريقة	طلب HTTP
HealthCheck	الحصول على /v3/HealthCheck/
BatchGetWaitEstimates	POST /v3/BatchGet تطابقEstimates/
CreateWaitlistEntry	POST /v3/CreatewalklistEntry/
GetWaitlistEntry	POST /v3/GetEventlistEntry/
DeleteWaitlistEntry	POST /v3/DeletesuchlistEntry/

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

Waitlist

يتم استخدام الموارد التالية لإجراء الحجز استنادًا إلى قائمة الانتظار:

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

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

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

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

عندما ينشئ المستخدم إدخالاً في قائمة الانتظار، ترسل Google إليك الاسم الأول واسم العائلة ورقم الهاتف والبريد الإلكتروني. ويكون عنوان البريد الإلكتروني مطابقًا لحساب المستخدم على Google ويتم التعامل معه كمعرّف فريد. ومن وجهة نظرك، يجب التعامل مع قائمة الانتظار هذه على أنها عملية دفع ضيف، لأنّ ميزة "الحجز عبر 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.

ملاحظة: لدمج قوائم انتظار الحجوزات، عليك تغيير طرق REST إلى الطرق المطلوبة لقوائم انتظار الحجوزات.

المتطلّبات

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

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

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

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

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

العجزية

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

• CreateWaitlistEntry
• DeleteWaitlistEntry

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

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

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

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

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