سرور رزرو را پیاده سازی کنید: API v2

توجه: در این صفحه نحوه پیاده سازی سرور رزرو با API v2 توضیح داده شده است. برای دستورالعمل‌های استفاده با آخرین نسخه ، به اجرای سرور رزرو مراجعه کنید.

راه اندازی یک سرور رزرو در انتهای خود به مرکز اقدامات اجازه می دهد تا از طرف کاربر قرار ملاقات / رزرو / رزرو با شما ایجاد کند.

یک رابط API بر اساس gRPC پیاده سازی کنید

لطفاً توجه داشته باشید: همه شرکای جدید باید از رابط REST API به جای gRPC API استفاده کنند.

یک رابط API بر اساس gRPC پیاده سازی کنید. این به Google امکان می‌دهد درخواست‌های رزرو ارسال کند. سطح API با استفاده از IDL مبتنی بر پروتوباف gRPC تعریف می شود.

ما از شرکای جدید خود می خواهیم که مجموعه توصیه شده ای از API v2 را پیاده سازی کنند. شرکا ممکن است URL و PORT را برای زیرساخت آنها انتخاب کنند.

این بخش یک مجموعه توصیه شده از API v2 را معرفی می کند. برای شرکای که API v0 را پیاده سازی نکرده اند اعمال می شود. برای شرکای فعلی ما که API v0 را پیاده‌سازی کرده‌اند، لطفاً برای کسب اطلاعات بیشتر با مرکز اقدامات تماس بگیرید.

برای شروع اجرای API، تعریف سرویس را در قالب پروتو زیر دانلود کنید.

تعریف سرویس را دانلود کنید

منابع API

لطفاً با انواع منابع زیر که در این پیاده سازی استفاده خواهند شد آشنا شوید:

• اسلات : یک شکاف موجودی
• رزرو : قرار ملاقات برای اسلات موجودی

روش ها

متدهای API زیر برای اجرای سرور gRPC در انتهای شما لازم است:

• بررسی در دسترس بودن
• ایجاد رزرو
• به روز رسانی رزرو
• GetBookingStatus
• لیست رزرو

این 5 روش مجموعه مورد نیاز 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 نام، نام خانوادگی، شماره تلفن و ایمیل کاربر را برای شریک ارسال می‌کند. این باید از نظر شریک به عنوان تسویه حساب مهمان تلقی شود زیرا مرکز اقدامات راهی برای جستجوی حساب کاربر در سیستم شریک ندارد. رزرو نهایی باید به تاجران شریک در سیستم آنها نشان داده شود، درست مانند رزروهایی که برای سیستم رزرو شریک انجام می شود.

پیاده سازی اسکلت در جاوا

برای شروع، ما یک سرور اسکلتی gRPC در جاوا ارائه می کنیم که می تواند کامپایل و نصب شود. آن را در بخش Samples > gRPC Reference Implementation بررسی کنید. این سرور روش‌های gRPC را که برای پشتیبانی از یکپارچه‌سازی مورد نیاز است، از جمله احراز هویت و خدمات بهداشتی را حذف کرده است.

الزامات

خطای gRPC و خطای منطق تجاری

هنگامی که یک باطن شریک درخواست‌های gRPC را رسیدگی می‌کند، ممکن است دو نوع خطا رخ دهد: خطاهای غیرمنتظره که از داده‌های نادرست ناشی می‌شوند. و خطاهای منطقی کسب و کار که نشان دهنده ناتوانی در ایجاد یا به روز رسانی رزرو هستند (به شکست رزرو مراجعه کنید)، به عنوان مثال، اگر اسلات درخواستی در دسترس نباشد.

خطاهای غیرمنتظره، در صورت مواجه شدن، باید با استفاده از کدهای خطای متعارف gRPC به مشتری بازگردانده شوند. به عنوان مثال می توان به موارد زیر اشاره کرد:

• INVALID_ARGUMENT در RPC هایی مانند CheckAvailability و CreateLease استفاده می شود و اگر اسلات ارائه شده حاوی اطلاعات نامعتبر باشد، باید بازگردانده شود.
• NOT_FOUND در RPCها مانند CreateBooking و ListBookings استفاده می شود و اگر شناسه ارائه شده برای شریک ناشناخته باشد، باید بازگردانده شود.

مرجع هر روش برای کدهای خطای متعارف gRPC یا لیست کامل کد وضعیت را ببینید.

برعکس، خطاهای منطق تجاری باید در Booking Failure ثبت شوند و در پاسخ RPC برگردانده شوند. ممکن است هنگام ایجاد یا به روز رسانی یک منبع، به عنوان مثال، در مدیریت RPCهای CreateBooking و UpdatingBooking، با خطاهای منطق تجاری مواجه شوید. به عنوان مثال می توان به موارد زیر اشاره کرد:

• اگر اسلات درخواستی دیگر در دسترس نباشد، از SLOT_UNAVAILABLE استفاده می شود.
• اگر نوع کارت اعتباری ارائه شده پذیرفته نشود، از PAYMENT_ERROR_CARD_TYPE_REJECTED استفاده می شود.

ناتوانی

ارتباط از طریق شبکه همیشه قابل اعتماد نیست و در صورت عدم دریافت پاسخ، Google Reserve ممکن است RPCها را دوباره امتحان کند. به همین دلیل، تمام RPCهایی که حالت جهش پیدا می کنند (CreateBooking، UpdateBooking) باید فاقد قدرت باشند. پیام‌های درخواستی برای این RPCها شامل نشانه‌های عدم توانایی برای شناسایی منحصربه‌فرد درخواست و اجازه دادن به شریک برای تمایز بین یک RPC مجدد (با قصد ایجاد یک رزرو واحد) و دو رزرو جداگانه است.

به عنوان مثال می توان به موارد زیر اشاره کرد:

• یک پاسخ موفق CreateBooking RPC شامل رزرو ایجاد شده می شود و در برخی موارد، پرداخت به عنوان بخشی از جریان رزرو پردازش می شود. اگر دقیقاً همان CreateBookingRequest برای بار دوم دریافت شود (از جمله idempotency_token )، همان CreateBookingResponse باید برگردانده شود. هیچ رزرو دومی ایجاد نمی شود و کاربر، در صورت وجود، دقیقاً یک بار شارژ می شود. توجه داشته باشید که اگر تلاش CreateBooking با شکست مواجه شد، اگر همان درخواست دوباره ارسال شد، پشتیبان شریک باید دوباره تلاش کند.

شرط عدم توانایی در تمام روش هایی که حاوی نشانه های عدم توانایی هستند اعمال می شود.

امنیت و احراز هویت سرور gRPC

تماس‌ها از «مرکز اقدامات» به بخش پشتیبان شما باید با استفاده از SSL/TLS با تأیید اعتبار مشتری/سرور متقابل مبتنی بر گواهی، ایمن شوند. این مستلزم استفاده از گواهی سرور معتبر برای اجرای gRPC شما و پذیرش گواهی مشتری معتبر است.

گواهی سرور: سرور شریک باید به یک گواهی سرور معتبر مرتبط با نام دامنه سرور مجهز باشد (به این لیست از CAهای ریشه پذیرفته شده مراجعه کنید). اجراهای سرور GRPC انتظار دارند یک زنجیره گواهی را ارائه دهند که به گواهی ریشه منتهی می شود. ساده ترین راه برای انجام این کار، الحاق گواهی(های) میانی ارائه شده توسط میزبان وب شریک در قالب PEM به گواهی سرور (همچنین در قالب PEM) است.

گواهی سرور در زمان اتصال تأیید می‌شود و گواهی‌های خودامضا پذیرفته نمی‌شوند. محتوای گواهی واقعی تا زمانی که گواهی معتبر است بررسی نمی شود. از طریق دستور زیر می توانید اعتبار گواهینامه خود را بررسی کنید:

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

توجه: گواهینامه ها دارای تاریخ انقضا هستند. این مسئولیت شریک است که مطمئن شود گواهینامه آنها قبل از انقضا به روز می شود تا از هرگونه قطع سرویس در مرکز اقدامات جلوگیری شود.

گواهی مشتری: برای احراز هویت ما (به عنوان Google) برای شریک، گواهی مشتری صادر شده توسط Google Internet Authority G2 ( گواهی CA ) با ویژگی های زیر ارائه می کنیم:

میدان	ارزش
CN	mapsbooking.businesslink-3.net
SAN	DNS:mapsbooking.businesslink-3.net

تلاش برای اتصال بدون این گواهی مشتری باید توسط سرور شریک رد شود.

برای تأیید اعتبار گواهی مشتری، سرور به مجموعه ای از گواهی های ریشه مشتری قابل اعتماد متکی است. می‌توانید این مجموعه از ریشه‌های قابل اعتماد را از مرجعی مانند موزیلا دریافت کنید یا مجموعه ریشه‌هایی را که در حال حاضر توسط Google Internet Authority G2 توصیه می‌شود نصب کنید. در هر دو مورد، ممکن است مجبور شوید گاهی اوقات گواهی های ریشه را به صورت دستی به روز کنید.

پروتکل gRPC Health Checking را اجرا کنید

پروتکل GRPC Health Checking را اجرا کنید. این پروتکل به Google امکان می دهد تا وضعیت backend پیاده سازی gRPC شما را نظارت کند. مشخصات سرویس بخشی از توزیع GRPC است. به دنبال قرارداد نام‌گذاری GRPC، نام سرویس در تماس‌های بررسی سلامت ext.maps.booking.partner.v2.BookingService برای API v2 یا ext.maps.booking.partner.v0.BookingService برای API v0 است. بررسی سلامت باید روی همان URL و PORT مانند سایر نقاط پایانی اجرا شود.

توجه: پیاده سازی های مرجع را در Ruby بررسی کنید.

نسخه های دیگر

برای اسناد سایر نسخه‌های API، به صفحات زیر مراجعه کنید: * API v3 * API v0