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

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

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

يُرجى العِلم أنّه على جميع الشركاء الجدد استخدام واجهة REST API بدلاً من واجهة gRPC API.

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

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

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

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

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

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

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

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

الطُرق

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

تحدّد هذه الطرق الخمس المجموعة المطلوبة من طلبات استدعاء الإجراء عن بُعد (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) {}
}

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

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

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

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

المتطلبات

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

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

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

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

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

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

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

التكرار

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

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

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

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

أمان خادم 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`	DNS:mapsbooking.businesslink-3.net

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

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

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

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

إصدارات أخرى

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