يجب توفير خادم حجز للسماح لـ "مركز الإجراءات" بإجراء استدعاءات لإنشاء الحجوزات وتعديلها نيابةً عنك.
- تنفيذ قوائم انتظار الحجوزات: يتم استخدام هذا الاسم عند المشاركة في البرنامج التجريبي لقوائم الانتظار الخاصة بالحجوزات. ويتيح ذلك لمركز الإجراءات إمكانية استرداد تقديرات الانتظار وإنشاء إدخالات في قائمة الانتظار نيابةً عن المستخدم.
- طريقة التنفيذ العادية: يسمح هذا الإجراء لـ "مركز الإجراءات" بإنشاء مواعيد وحجوزات وحجوزات معك نيابةً عن المستخدم. لتنفيذ خادم حجز من أجل الدمج الشامل للحجوزات، يُرجى الرجوع إلى تنفيذ خادم الحجز.
راجع مستندات بوابة الشريك لمعرفة كيفية إعداد الاتصال بخوادم حجز وضع الحماية والإنتاج.
تنفيذ واجهة واجهة برمجة تطبيقات 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: سير العمل لإنشاء إدخال قائمة الانتظار](https://developers-dot-devsite-v2-prod.appspot.com/static/actions-center/images/waitlists/rest_api_v3_waitlist_flow.png?authuser=8&hl=ar)
عندما ينشئ المستخدم إدخالاً في قائمة الانتظار، ترسل 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.
المتطلّبات
أخطاء HTTP وأخطاء منطق العمل
عندما تتعامل الخلفية مع طلبات HTTP، قد يحدث نوعان من الأخطاء.
- الأخطاء المتعلقة بالبنية الأساسية أو البيانات غير الصحيحة
- عرض هذه الأخطاء على العميل باستخدام رموز خطأ HTTP القياسية. راجِع القائمة الكاملة لرموز حالة HTTP.
- الأخطاء المتعلقة بمنطق العمل
- اعرض رمز حالة HTTP الذي تم ضبطه على
200
حسنًا، وحدِّد الخطأ المنطقي للنشاط التجاري في نص الاستجابة. تختلف أنواع أخطاء منطق الأعمال التي يمكن أن تواجهها باختلاف الأنواع المختلفة من عمليات تنفيذ الخادم.
- اعرض رمز حالة HTTP الذي تم ضبطه على
في عملية دمج قوائم انتظار الحجوزات، يتم تسجيل الأخطاء المنطقية للنشاط التجاري في تعذُّر منطق النشاط التجاري في قائمة الانتظار ويتم عرضها في استجابة HTTP. قد تحدث أخطاء في منطق الأعمال عند إنشاء مورد، على سبيل المثال عند التعامل مع طريقة CreateWaitlistEntry
. وتشمل الأمثلة على سبيل المثال لا الحصر:
- يتم استخدام السمة
ABOVE_MAX_PARTY_SIZE
عندما يتجاوز إدخال قائمة الانتظار المطلوب الحد الأقصى لحجم الحفل لدى التاجر. - يتم استخدام السمة
MERCHANT_CLOSED
عندما لا تكون قائمة الانتظار مفتوحة لأنّ التاجر مغلق حاليًا.
العجزية
لا يمكن الاعتماد على الاتصال عبر الشبكة في بعض الأحيان وقد يعيد محرّك بحث Google محاولة إرسال طلبات HTTP في حال عدم تلقّي أي استجابة. ولهذا السبب، يجب أن تكون جميع الطرق التي تشير إلى حالة التبديل عازلة:
CreateWaitlistEntry
DeleteWaitlistEntry
بالنسبة إلى كل رسالة طلب باستثناء DeleteWaitlistEntry
، يتم تضمين الرموز المميّزة لتحديد الهوية لتحديد الطلب بشكل فريد. ويسمح لك ذلك بالتمييز بين طلب REST
الذي تمت إعادة محاولة إجراءه، والهدف منه إنشاء طلب واحد، وطلبَين منفصلَين.
يتم تحديد DeleteWaitlistEntry
بشكل فريد من خلال أرقام تعريف الإدخال في قائمة الانتظار الخاصة به على التوالي، لذلك لا يتم تضمين أي رمز مميّز لتحديد الهوية في طلبات المستخدم.
وفي ما يلي بعض الأمثلة على كيفية تعامل خوادم الحجز مع عدم الهوية:
وتتضمّن استجابة HTTP
CreateWaitlistEntry
الناجحة رقم تعريف إدخال قائمة الانتظار الذي تم إنشاؤه. إذا تم استلامCreateWaitlistEntryRequest
نفسه مرة ثانية (باستخدامidempotency_token
نفسه)، يجب عرضCreateWaitlistEntryResponse
نفسها. لا يتم إنشاء إدخال ثانٍ لقائمة الانتظار ولا يتم عرض أي خطأ.تجدر الإشارة إلى أنّه في حال تعذّر محاولة
CreateWaitlistEntry
وتمت إعادة إرسال الطلب نفسه، يجب إعادة المحاولة في هذه الحالة من خلال الخلفية.
ينطبق شرط عدم القدرة على الفاعلية على جميع الطرق التي تؤدي إلى تبديل الحالة.