تنفيذ خادم الحجز: الإصدار 2 من واجهة برمجة التطبيقات

ملاحظة: توضّح هذه الصفحة كيفية تنفيذ خادم الحجز باستخدام الإصدار 2 من واجهة برمجة التطبيقات. اطّلِع على مقالة تنفيذ خادم الحجز للحصول على تعليمات الاستخدام مع أحدث إصدار.

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

تنفيذ واجهة برمجة تطبيقات استنادًا إلى gRPC

ملاحظة: على جميع الشركاء الجدد استخدام واجهة برمجة التطبيقات REST API بدلاً من واجهة برمجة التطبيقات gRPC API.

تنفيذ واجهة برمجة تطبيقات استنادًا إلى gRPC يتيح ذلك لشركة Google إرسال طلبات الحجز. يتم تعريف سطح واجهة برمجة التطبيقات باستخدام ملف IDEL المستنِد إلى protobuf في gRPC.

نطلب من شركائنا الجدد تنفيذ مجموعة مقترَحة من الإصدار 2 من واجهة برمجة التطبيقات. يمكن للشركاء اختيار عنوان URL وPORT الأنسب لبنية الأساس الخاصة بهم.

يقدّم هذا القسم مجموعة مقترَحة من الإصدار 2 من واجهة برمجة التطبيقات. وينطبق ذلك على الشركاء الذين لم ينفّذوا الإصدار 0 من واجهة برمجة التطبيقات. بالنسبة إلى شركائنا الحاليين الذين نفّذوا الإصدار 0 من واجهة برمجة التطبيقات، يُرجى التواصل مع فريق "مركز الإجراءات" للحصول على مزيد من المعلومات.

نزِّل تعريف الخدمة بتنسيق proto أدناه للبدء في تنفيذ واجهة برمجة التطبيقات.

تنزيل ملف تعريف الخدمة

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

يُرجى الاطّلاع على أنواع الموارد التالية التي سيتم استخدامها في عملية التنفيذ هذه:

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

الطُرق

يجب تنفيذ طرق واجهة برمجة التطبيقات التالية من جانبك للخدمة gRPC server:

• CheckAvailability
• CreateBooking
• UpdateBooking
• GetBookingStatus
• ListBookings

تحدِّد هذه الطرق الخمس المجموعة المطلوبة من طلبات بيانات الجلسة (RPC) في BookingService:

// Manages slot availability, leases and bookings for an inventory of
// appointments
service BookingService {
  // Gets availability information for an appointment slot
  rpc CheckAvailability(CheckAvailabilityRequest)
      returns (CheckAvailabilityResponse) {}

  // Creates a booking
  rpc CreateBooking(CreateBookingRequest) returns (CreateBookingResponse) {}

  // Updates an existing booking
  rpc UpdateBooking(UpdateBookingRequest) returns (UpdateBookingResponse) {}

  // Gets status for an existing booking
  rpc GetBookingStatus(GetBookingStatusRequest)
      returns (GetBookingStatusResponse) {}

  // Lists all upcoming bookings for a user
  rpc ListBookings(ListBookingsRequest) returns (ListBookingsResponse) {}
}

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

الشكل 1: إنشاء حجز من خانة

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

تنفيذ الهيكل في Java

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

المتطلبات

خطأ gRPC وخطأ في منطق النشاط التجاري

قد يحدث نوعان من الأخطاء عندما يعالج القسم الخلفي للشريك طلبات gRPC: أخطاء غير متوقّعة ناتجة عن بيانات غير صحيحة، وأخطاء منطق النشاط التجاري التي تشير إلى عدم التمكّن من إنشاء حجز أو تعديله (راجِع تعذُّر الحجز)، مثلاً إذا كانت الفترة الزمنية المطلوبة غير متاحة.

في حال حدوث أخطاء غير متوقّعة، يجب إرسالها إلى العميل باستخدام رمز خطأ gRPC canonical. ويشمل ذلك على سبيل المثال لا الحصر:

• يتم استخدام INVALID_ARGUMENT في طلبات RPC، مثل CheckAvailability وCreateLease، ويجب إرجاعه إذا كانت الفتحة المقدَّمة تحتوي على معلومات غير صالحة.
• يتم استخدام القيمة NOT_FOUND في طلبات RPC، مثل CreateBooking وListBookings، ويجب عرضها إذا كان المعرّف المقدَّم غير معروف للشريك.

اطّلِع على مرجع كل طريقة لمعرفة رموز أخطاء gRPC الأساسية أو اطّلِع على قائمة رموز الحالة الكاملة.

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

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

الثبات

لا يكون التواصل عبر الشبكة موثوقًا في بعض الأحيان، وقد تتم محاولة إعادة إرسال طلبات RPC من خلال Google Reserve في حال عدم تلقّي أي ردّ. لهذا السبب، يجب أن تكون جميع طلبات RPC التي تغيّر الحالة (CreateBooking وUpdateBooking) idempotent. تتضمّن رسائل الطلبات المتعلّقة بهذه الطلبات المبرمَجة لرموز مميّزة لتحديد الطلب بشكل فريد والسماح للشريك بالتفريق بين طلب مبرمَج تمت إعادة إرساله (بغرض إنشاء حجز واحد) وحجزَين منفصلَين.

ويشمل ذلك على سبيل المثال لا الحصر:

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

ينطبق شرط الثبات على جميع الطرق التي تحتوي على رموز ثبات.

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

يجب تأمين المكالمات الواردة من "مركز الإجراءات" إلى الخلفية باستخدام بروتوكول طبقة المقابس الآمنة (SSL)/بروتوكول أمان طبقة النقل (TLS) مع مصادقة متبادلة بين العميل والخادم تستند إلى الشهادات. يتطلّب ذلك استخدام شهادة خادم صالحة لتنفيذ gRPC وقبول شهادة عميل صالحة.

شهادة الخادم: يجب أن يكون خادم الشريك مزوّدًا بشهادة خادم صالحة مرتبطة باسم نطاق الخادم (راجِع قائمة مراجِع التصديق الجذر المقبولة). تتوقع عمليات تنفيذ خادم GRPC عرض سلسلة شهادة تؤدي إلى الشهادة الجذرية. وأسهل طريقة لإجراء ذلك هي من خلال إلحاق الشهادات الوسيطة التي يقدّمها مضيف الويب الخاص بالشريك بتنسيق PEM بملف شهادة الخادم (بتنسيق PEM أيضًا).

يتم التحقّق من شهادة الخادم في وقت الاتصال ولا يتم قبول الشهادات الموقَّعة ذاتيًا. لا يتم التحقّق من محتوى الشهادة الفعلي ما دامت صالحة. يمكنك التحقّق من صلاحية شهادتك من خلال الأمر التالي:

echo "" | openssl s_client  -connect YOUR_URL:YOUR_PORT  -showcerts -CApath /etc/ssl/certs

ملاحظة: يكون للشهادات تاريخ انتهاء صلاحية. يتحمّل الشريك مسؤولية التأكّد من تعديل شهادته قبل انتهاء صلاحيتها لتجنّب أي انقطاع في الخدمة في "مركز الإجراءات".

شهادة العميل: للمصادقة معنا (بصفتنا Google) مع الشريك، نقدّم شهادة عميل صادرة عن Google Internet Authority G2 (شهادة المرجع المصدق) تتضمّن السمات التالية:

الحقل	القيمة
CN	mapsbooking.businesslink-3.net
SAN	نظام أسماء النطاقات:mapsbooking.businesslink-3.net

من المفترض أن يرفض خادم الشريك محاولات الاتصال بدون شهادة العميل هذه.

للتحقّق من صحة شهادة العميل، يعتمد الخادم على مجموعة من شهادات العميل الجذر الموثوق بها. يمكنك اختيار الحصول على هذه المجموعة من الجذور الموثوق بها من جهة مختصة مثل Mozilla أو تثبيت مجموعة الجذور التي تنصح بها حاليًا هيئة Google Internet Authority G2. في كلا الحالتَين، قد تحتاج إلى تعديل الشهادات الجذر يدويًا في بعض الأحيان.

تنفيذ بروتوكول التحقّق من الصحة في gRPC

نفِّذ بروتوكول التحقّق من الصحة في GRPC. يتيح هذا البروتوكول لشركة Google مراقبة حالة الخلفية لتنفيذ gRPC. مواصفات الخدمة هي جزء من توزيع GRPC. وفقًا لاتفاقية تسمية GRPC، يكون اسم الخدمة في طلبات التحقّق من الصحة هو ext.maps.booking.partner.v2.BookingService للإصدار 2 من واجهة برمجة التطبيقات، أو ext.maps.booking.partner.v0.BookingService للإصدار 0 من واجهة برمجة التطبيقات. يجب أن تتم معالجة عملية التحقّق من الصحة على عنوان URL وPORT نفسهما المستخدَمَين في نقاط النهاية الأخرى.

ملاحظة: يمكنك الاطّلاع على عمليات التنفيذ المرجعية في Ruby.

إصدارات أخرى

للاطّلاع على مستندات الإصدارات الأخرى من واجهة برمجة التطبيقات، يُرجى الاطّلاع على الصفحات التالية: * الإصدار 3 من واجهة برمجة التطبيقات * الإصدار 0 من واجهة برمجة التطبيقات