إنّ إعداد خادم حجز من جانبك يتيح لـ "مركز الإجراءات" إنشاء مواعيد / حجوزات / حجوزات معك نيابةً عن المستخدم.
تنفيذ واجهة برمجة تطبيقات استنادًا إلى "مجموعة خدمات التحكّم في الأجهزة الجوّالة" (gRPC)
ملاحظة: على جميع الشركاء الجدد استخدام واجهة REST API بدلاً من gRPC API.
تنفيذ واجهة واجهة برمجة التطبيقات استنادًا إلى gRPC يتيح ذلك لـ Google إرسال طلبات الحجز. يتم تحديد مساحة واجهة برمجة التطبيقات باستخدام IDL المستنِد إلى النموذج الأوّلي gRPC.
نطلب من شركائنا الجدد تنفيذ مجموعة موصى بها من الإصدار الثاني من واجهة برمجة التطبيقات. يمكن للشركاء اختيار عنوان URL و المنفذ الأنسب للبنية الأساسية لديهم.
يتناول هذا القسم مجموعة مُقترَحة من الإصدار الثاني من واجهة برمجة التطبيقات. وتنطبق هذه السياسة على الشركاء الذين لم ينفّذوا الإصدار 0 من واجهة برمجة التطبيقات. بالنسبة إلى شركائنا الحاليين الذين استخدموا الإصدار 0 من واجهة برمجة التطبيقات، يُرجى التواصل مع "مركز الإجراءات" لمعرفة المزيد من المعلومات.
يمكنك تنزيل تعريف الخدمة بتنسيق Proto أدناه لبدء تنفيذ واجهة برمجة التطبيقات.
موارد واجهة برمجة التطبيقات
يُرجى التعرف على أنواع الموارد التالية التي سيتم استخدامها في عملية التنفيذ هذه:
الطُرق
مطلوب تنفيذ طرق واجهة برمجة التطبيقات التالية من جانبك لخادم gRPC:
تحدّد هذه الطرق الخمس المجموعة المطلوبة من رموز استدعاء إجراء عن بُعد في 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 إلى الشريك الاسم الأول واسم العائلة ورقم الهاتف والبريد الإلكتروني للشريك. يجب التعامل مع هذا الإجراء على أنّه إتمام الدفع كضيف من وجهة نظر الشريك، لأنّ "مركز الإجراءات" لا تتوفّر له طريقة للبحث عن حساب المستخدم في نظام الشريك. يجب عرض الحجز النهائي لتجّار الشركاء في نظامهم تمامًا مثل الحجوزات الواردة في نظام الحجز الخاص بالشريك.
تنفيذ الهيكل العظمي في جافا
للبدء، نقدّم خادم gRPC أساسي في لغة Java يمكن تجميعه وتثبيته. يمكنك الاطّلاع على التفاصيل ضمن قسم عيّنات > تنفيذ مرجع gRPC. وقد استبعد هذا الخادم طرق gRPC المطلوبة لدعم عملية الدمج، بما في ذلك المصادقة والخدمات الصحية.
المتطلّبات
خطأ في gRPC وخطأ في منطق النشاط التجاري
قد يحدث نوعان من الأخطاء عندما تعالج الواجهة الخلفية لأحد الشركاء طلبات gRPC: الأخطاء غير المتوقّعة الناتجة عن البيانات غير الصحيحة، وأخطاء منطق العمل التي تشير إلى عدم القدرة على إنشاء حجز أو تعديله (يُرجى مراجعة تعذُّر الحجز، مثلاً إذا كانت الخانة المطلوبة غير متاحة.
وفي حال حدوث أخطاء غير متوقعة، يجب إرجاعها إلى العميل باستخدام رموز خطأ gRPC الأساسية. وفي ما يلي أمثلة على سبيل المثال لا الحصر:
- يتم استخدام INVALID_وا في طلبات استدعاء إجراء عن بُعد (RPC)، مثل Check مشاهد (مدى التوفّر) وCreateLease، ويجب إرجاعها إذا كانت الخانة المتوفّرة تحتوي على معلومات غير صالحة.
- يتم استخدام NOT_FOUND في عمليات استدعاء إجراء عن بُعد (RPC) مثل CreateBooking وListBookings، ويجب إرجاعه إذا كان المعرف المقدم غير معروف للشريك.
راجِع كل طريقة للاطّلاع على رموز خطأ gRPC الأساسية أو راجِع قائمة رموز الحالة الكاملة.
وعلى العكس من ذلك، يجب تسجيل أخطاء منطق العمل في تعذّر الحجز، وعرضها في استجابة استدعاء إجراء عن بُعد (RPC). قد تحدث أخطاء في منطق العمل عند إنشاء مورد أو تحديثه، أي عند التعامل مع إنشاء الحجز لاستدعاء إجراء عن بُعد (RPC) وحجز المواعيد. وفي ما يلي أمثلة على سبيل المثال لا الحصر:
- يتم استخدام SLOT_UNAVAILABLE إذا لم تعُد الخانة المطلوبة متاحة.
- يتم استخدام PAYMENT_ERROR_CARD_TYPE_REJECTED إذا لم يتم قبول نوع بطاقة الائتمان المقدم.
العجزية
لا يمكن الاعتماد على الاتصال عبر الشبكة دائمًا وقد يعيد Google Reserve محاولة إعادة توجيه استدعاء إجراء عن بُعد (RPC) في حال عدم تلقي أي رد. لهذا السبب، يجب أن تكون جميع استدعاء إجراء عن بُعد (RPC) التي يتم تغييرها حالة التبديل (CreateBooking، UpdateBooking) ثابتة. تتضمّن الرسائل المطلوبة لاستدعاءات استدعاء إجراء عن بُعد (RPC) هذه الرموز المميزة للهوية لتعريف الطلب بشكل فريد والسماح للشريك بالتمييز بين استدعاء إجراء عن بُعد (RPC) تمت إعادة تجربته (بهدف إنشاء حجز واحد) وحجزين منفصلين.
وفي ما يلي أمثلة على سبيل المثال لا الحصر:
- ويشمل الرد الناجح لاستدعاء الإجراء عن بُعد
CreateBooking الحجز الذي تم إنشاؤه، وفي بعض الحالات، تتم معالجة الدفعة
كجزء من عملية الحجز. في حال تلقّي CreateBookingRequest نفسه للمرة الثانية (بما في ذلك
idempotency_token)، يجب عرض CreateBookingResponse نفسه. لا يتم إنشاء حجز ثانٍ ويتم تحصيل رسوم من المستخدم، إن أمكن، مرة واحدة فقط. يُرجى العِلم أنّه في حال تعذّرت محاولة إنشاء حجز، يجب على الواجهة الخلفية للشريك إعادة المحاولة في حال إرسال الطلب نفسه مرة أخرى.
تنطبق متطلبات إثبات الهوية على جميع الطرق التي تحتوي على رموز إثبات الهوية.
أمان ومصادقة خادم gRPC
يجب تأمين المكالمات الواردة من "مركز الإجراءات" إلى الخلفية باستخدام طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل (TLS) والمصادقة المتبادلة للعميل/الخادم على أساس الشهادة. يتطلب هذا استخدام شهادة خادم صالحة لتنفيذ gRPC وقبول شهادة عميل صالحة.
شهادة الخادم: يجب أن يكون خادم الشريك مجهزًا بشهادة خادم صالحة مرتبطة باسم نطاق الخادم (راجع قائمة مراجع التصديق الجذر المقبولة هذه). من المتوقع أن تعرض عمليات تنفيذ خادم GRPC سلسلة شهادات تؤدي إلى شهادة الجذر. وتتمثل أسهل طريقة لتحقيق ذلك في إلحاق الشهادة(الشهادات) المتوسطة التي قدمها مضيف الويب للشريك بتنسيق PEM بشهادة الخادم (بتنسيق PEM أيضًا).
يتم التحقّق من شهادة الخادم في وقت الاتصال ولا يتم قبول الشهادات الموقَّعة ذاتيًا. لا يتم التحقق من محتوى الشهادة الفعلية ما دامت الشهادة صالحة. يمكنك التحقق من صلاحية شهادتك من خلال الأمر التالي:
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
شهادة العميل: من أجل مصادقتنا (مثل Google) على الشريك، نقدّم شهادة عميل صادرة عن G2 من Google Internet Authority G2 (شهادة CA) مع السمات التالية:
| الحقل | القيمة |
|---|---|
CN |
mapsbooking.businesslink-3.net |
SAN |
نظام أسماء النطاقات:mapsbooking.businesslink-3.net |
وسيرفض الخادم الشريك محاولات الاتصال بدون شهادة العميل هذه.
للتحقق من صحة شهادة العميل، يعتمد الخادم على مجموعة من شهادات جذر العميل الموثوق بها. يمكنك اختيار الحصول على هذه المجموعة من الجذور الموثوق بها من هيئة مثل Mozilla أو تثبيت مجموعة الجذور التي تنصح بها "هيئة الإنترنت من Google" G2 حاليًا. وفي كلتا الحالتين، قد تضطر في بعض الأحيان إلى تحديث شهادات الجذر يدويًا.
تنفيذ بروتوكول التحقّق من الصحة (gRPC)
نفِّذ بروتوكول GPC للتحقق من الصحة.
يتيح هذا البروتوكول لـ Google مراقبة حالة الخلفية لتنفيذ "طلب التحكّم الوجهة" (gRPC). تُعد مواصفات الخدمة
جزءًا من توزيع GRPC. وفقًا لاصطلاح تسمية GRPC، يكون اسم الخدمة في طلبات التحقق من الصحة هو ext.maps.booking.partner.v2.BookingService لواجهة برمجة التطبيقات الإصدار 2 أو ext.maps.booking.partner.v0.BookingService لواجهة برمجة التطبيقات الإصدار 0. يجب إجراء التحقق من الصحة على عنوان URL وport نفسيهما مثل نقاط النهاية الأخرى.
إصدارات أخرى
وبالنسبة إلى المستندات الخاصة بالإصدارات الأخرى من واجهة برمجة التطبيقات، يُرجى الاطّلاع على الصفحات التالية: * API v3 * API v0