راهاندازی یک سرور رزرو در سمت شما، به مرکز عملیات اجازه میدهد تا از طرف کاربر، قرار ملاقاتها/رزروها/رزروها را با شما ایجاد کند.
پیادهسازی رابط API مبتنی بر gRPC
لطفا توجه داشته باشید: همه شرکای جدید باید از رابط REST API به جای gRPC API استفاده کنند.
یک رابط API مبتنی بر gRPC پیادهسازی کنید. این به گوگل اجازه میدهد درخواستهای رزرو ارسال کند. سطح API با استفاده از IDL مبتنی بر protobuf در gRPC تعریف میشود.
ما از شرکای جدید خود میخواهیم که مجموعهای از API نسخه ۲ پیشنهادی را پیادهسازی کنند. شرکا میتوانند هر URL و PORT که برای زیرساخت آنها بهتر عمل میکند را انتخاب کنند.
این بخش مجموعهای از API نسخه ۲ پیشنهادی را معرفی میکند. این مجموعه برای شرکایی که API نسخه ۰ را پیادهسازی نکردهاند، اعمال میشود. برای شرکای فعلی ما که API نسخه ۰ را پیادهسازی کردهاند، لطفاً برای کسب اطلاعات بیشتر با مرکز اقدامات تماس بگیرید.
برای شروع پیادهسازی API، تعریف سرویس را با فرمت proto از زیر دانلود کنید.
منابع API
لطفا با انواع منابع زیر که در این پیادهسازی مورد استفاده قرار خواهند گرفت، آشنا شوید:
روشها
متدهای API زیر باید از سمت شما برای سرور gRPC پیادهسازی شوند:
این 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) {}
}
جریان: ایجاد رزرو
هنگام ایجاد رزرو، گوگل نام، نام خانوادگی، شماره تلفن و ایمیل کاربر را برای شریک ارسال میکند. این باید از دیدگاه شریک به عنوان پرداخت مهمان در نظر گرفته شود زیرا مرکز عملیات هیچ راهی برای جستجوی حساب کاربر در سیستم شریک ندارد. رزرو نهایی باید درست مانند رزروهایی که برای سیستم رزرو شریک ارسال میشوند، به فروشندگان شریک در سیستم آنها نشان داده شود.
پیادهسازی اسکلت در جاوا
برای شروع، ما یک سرور gRPC اسکلتبندی شده به زبان جاوا ارائه میدهیم که قابل کامپایل و نصب است. آن را در بخش نمونهها > پیادهسازی مرجع gRPC بررسی کنید. این سرور، متدهای gRPC مورد نیاز برای پشتیبانی از ادغام، از جمله احراز هویت و سرویس سلامت، را ارائه میدهد.
الزامات
خطای gRPC و خطای منطق کسب و کار
دو نوع خطا ممکن است هنگام مدیریت درخواستهای gRPC توسط یک شریک رخ دهد: خطاهای غیرمنتظرهای که از دادههای نادرست ناشی میشوند؛ و خطاهای منطق کسبوکار که نشاندهنده عدم توانایی در ایجاد یا بهروزرسانی رزرو هستند (به بخش «شکست رزرو » مراجعه کنید)، مثلاً اگر اسلات درخواستی در دسترس نباشد.
در صورت بروز خطاهای غیرمنتظره، باید با استفاده از کدهای خطای استاندارد gRPC به کلاینت گزارش شوند. مثالها شامل موارد زیر هستند اما محدود به آنها نیستند:
- INVALID_ARGUMENT در RPCهایی مانند CheckAvailability و CreateLease استفاده میشود و اگر اسلات ارائه شده حاوی اطلاعات نامعتبر باشد، باید برگردانده شود.
- NOT_FOUND در RPCهایی مانند CreateBooking و ListBookings استفاده میشود و اگر شناسه ارائه شده برای همکار ناشناخته باشد، باید برگردانده شود.
برای کدهای خطای gRPC متعارف هر روش، به مرجع آن مراجعه کنید یا لیست کامل کدهای وضعیت را ببینید.
برعکس، خطاهای منطق کسب و کار باید در خطای رزرو ثبت شوند و در پاسخ RPC بازگردانده شوند. خطاهای منطق کسب و کار ممکن است هنگام ایجاد یا بهروزرسانی یک منبع، یعنی در مدیریت RPCهای CreateBooking و UpdatetingBooking، رخ دهند. مثالها شامل موارد زیر هستند اما محدود به آنها نیستند:
- اگر اسلات درخواستی دیگر در دسترس نباشد، از SLOT_UNAVAILABLE استفاده میشود.
- اگر نوع کارت اعتباری ارائه شده پذیرفته نشود، از PAYMENT_ERROR_CARD_TYPE_REJECTED استفاده میشود.
خودتوانی
ارتباط از طریق شبکه همیشه قابل اعتماد نیست و Google Reserve ممکن است در صورت عدم دریافت پاسخ، RPCها را دوباره امتحان کند. به همین دلیل، تمام RPCهایی که حالت خود را تغییر میدهند (CreateBooking، UpdateBooking) باید خودتوان باشند. پیامهای درخواست برای این RPCها شامل توکنهای خودتوان هستند تا درخواست را به طور منحصر به فرد شناسایی کنند و به شریک اجازه دهند بین یک RPC دوباره امتحان شده (با هدف ایجاد یک رزرو واحد) و دو رزرو جداگانه تمایز قائل شود.
مثالها شامل موارد زیر میشوند اما محدود به آنها نیستند:
- یک پاسخ موفق CreateBooking RPC شامل رزرو ایجاد شده است و در برخی موارد، پرداخت به عنوان بخشی از جریان رزرو پردازش میشود. اگر دقیقاً همان CreateBookingRequest برای بار دوم دریافت شود (شامل
idempotency_token)، باید همان CreateBookingResponse برگردانده شود. رزرو دومی ایجاد نمیشود و در صورت لزوم، هزینه دقیقاً یک بار از کاربر دریافت میشود. توجه داشته باشید که اگر تلاش CreateBooking با شکست مواجه شود، در صورت ارسال مجدد همان درخواست، backend همکار باید دوباره تلاش کند.
الزام خودتوانی (Idempotency) برای تمام متدهایی که حاوی توکنهای خودتوانی هستند، اعمال میشود.
امنیت و احراز هویت سرور gRPC
تماسها از مرکز عملیات به backend شما باید با استفاده از SSL/TLS با احراز هویت متقابل کلاینت/سرور مبتنی بر گواهی ایمن شوند. این امر مستلزم استفاده از یک گواهی سرور معتبر برای پیادهسازی gRPC شما و پذیرش یک گواهی کلاینت معتبر است.
گواهی سرور: سرور همکار باید به یک گواهی سرور معتبر مرتبط با نام دامنه سرور مجهز باشد (به این لیست از CA های ریشه پذیرفته شده مراجعه کنید). پیادهسازیهای سرور GRPC انتظار دارند یک زنجیره گواهی ارائه دهند که به گواهی ریشه منتهی میشود. سادهترین راه برای انجام این کار، اضافه کردن گواهی (های) میانی ارائه شده توسط میزبان وب همکار با فرمت PEM به گواهی سرور (همچنین با فرمت PEM) است.
گواهی سرور در زمان اتصال تأیید میشود و گواهیهای خودامضا پذیرفته نمیشوند. تا زمانی که گواهی معتبر باشد، محتوای واقعی گواهی بررسی نمیشود. میتوانید اعتبار گواهی خود را از طریق دستور زیر بررسی کنید:
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
گواهی مشتری: برای احراز هویت ما (به عنوان گوگل) برای شریک، ما یک گواهی مشتری صادر شده توسط Google Internet Authority G2 ( گواهی CA ) با مشخصات زیر ارائه میدهیم:
| میدان | ارزش |
|---|---|
CN | mapsbooking.businesslink-3.net |
SAN | DNS: mapsbooking.businesslink-3.net |
تلاشهای اتصال بدون این گواهی کلاینت باید توسط سرور همکار رد شوند.
برای اعتبارسنجی گواهی کلاینت، سرور به مجموعهای از گواهیهای ریشه کلاینت معتبر متکی است. میتوانید این مجموعه از ریشههای معتبر را از مرجعی مانند موزیلا دریافت کنید یا مجموعه ریشههایی را که در حال حاضر توسط مرجع اینترنتی گوگل G2 توصیه شده است، نصب کنید. در هر دو مورد، ممکن است مجبور شوید گواهیهای ریشه را گاهی اوقات به صورت دستی بهروزرسانی کنید.
پیادهسازی پروتکل بررسی سلامت gRPC
پروتکل بررسی سلامت GRPC را پیادهسازی کنید. این پروتکل به گوگل امکان میدهد وضعیت backend پیادهسازی gRPC شما را رصد کند. مشخصات سرویس بخشی از توزیع GRPC است. طبق قرارداد نامگذاری GRPC، نام سرویس در فراخوانیهای بررسی سلامت برای API نسخه ۲، ext.maps.booking.partner.v2.BookingService یا برای API نسخه ۰، ext.maps.booking.partner.v0.BookingService است. بررسی سلامت باید روی همان URL و PORT سایر نقاط پایانی اجرا شود.
نسخههای دیگر
برای مستندات سایر نسخههای API، به صفحات زیر مراجعه کنید: * API نسخه ۳ * API نسخه ۰