הגדרת שרת הזמנות בצד שלכם תאפשר ל-Actions Center ליצור פגישות, הזמנות או הזמנות מראש אצלכם בשם המשתמש.
הטמעה של ממשק API שמבוסס על gRPC
הערה: כל השותפים החדשים צריכים להשתמש בממשק REST API ולא ב-gRPC API.
מטמיעים ממשק API שמבוסס על gRPC. כך Google תוכל לשלוח בקשות הזמנה. ממשק ה-API מוגדר באמצעות IDL מבוסס-protobuf של gRPC.
אנחנו מבקשים מהשותפים החדשים שלנו להטמיע קבוצה מומלצת של API v2. השותפים יכולים לבחור את כתובת ה-URL והיציאה שהכי מתאימות לתשתית שלהם.
בקטע הזה מוצג סט מומלץ של API v2. היא חלה על שותפים שלא הטמיעו את API v0. שותפים קיימים שהטמיעו את API v0 יכולים לפנות אל Actions Center כדי לקבל מידע נוסף.
כדי להתחיל בהטמעה של ה-API, מורידים את הגדרת השירות בפורמט proto שבהמשך.
משאבי API
כדאי להכיר את סוגי המשאבים הבאים שבהם נשתמש בהטמעה הזו:
Methods
כדי להשתמש בשרת gRPC, צריך להטמיע את שיטות ה-API הבאות:
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) {}
}
תהליך: יצירת הזמנה
כשיוצרים הזמנה, Google שולחת לשותף את השם הפרטי, שם המשפחה, מספר הטלפון וכתובת האימייל של המשתמש. מנקודת המבט של השותף, צריך להתייחס לזה כאל תשלום כאורח, כי ל-Actions Center אין אפשרות לחפש את החשבון של המשתמש במערכת של השותף. ההזמנה הסופית צריכה להופיע למוכרים של השותף במערכת שלהם בדיוק כמו הזמנות שמגיעות ממערכת ההזמנות של השותף.
הטמעת שלד ב-Java
כדי להתחיל, אנחנו מספקים שרת gRPC בסיסי ב-Java שאפשר לקמפל ולהתקין. אפשר לעיין בו בקטע 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 (במטרה ליצור הזמנה אחת) לבין שתי הזמנות נפרדות.
הנה כמה דוגמאות:
- תגובת RPC מוצלחת של CreateBooking כוללת את ההזמנה שנוצרה, ובמקרים מסוימים, התשלום מעובד כחלק מתהליך ההזמנה. אם מתקבלת בפעם השנייה אותה בקשה בדיוק מסוג CreateBookingRequest (כולל
idempotency_token), צריך להחזיר את אותה תגובה מסוג CreateBookingResponse. לא נוצרת הזמנה שנייה, ואם רלוונטי, המשתמש מחויב בדיוק פעם אחת. שימו לב שאם ניסיון ליצור הזמנה נכשל, מערכת ה-Backend של השותף צריכה לנסות שוב אם אותה בקשה נשלחת שוב.
הדרישה לאידמפוטנטיות חלה על כל השיטות שמכילות טוקנים של אידמפוטנטיות.
אבטחה ואימות בשרת gRPC
הקריאות ממרכז הפעולות אל ה-Backend שלכם צריכות להיות מאובטחות באמצעות SSL/TLS עם אימות דו-צדדי של לקוח/שרת שמבוסס על אישור. כדי לעשות זאת, צריך להשתמש באישור שרת תקף להטמעה של gRPC ולקבל אישור לקוח תקף.
אישור שרת: שרת השותף צריך להיות מצויד באישור שרת תקף שמשויך לשם הדומיין של השרת (אפשר לעיין ברשימה הזו של רשויות אישורים בסיסיות (root) שאושרו). הטמעות של שרת 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 |
ניסיונות חיבור ללא אישור הלקוח הזה צריכים להידחות על ידי השרת של השותף.
כדי לאמת את אישור הלקוח, השרת מסתמך על קבוצה של אישורי לקוח בסיסיים מהימנים. אתם יכולים לבחור לקבל את קבוצת השורשים המהימנים האלה מרשות כמו Mozilla או להתקין את קבוצת השורשים שמומלצת כרגע על ידי Google Internet Authority G2. בשני המקרים, יכול להיות שתצטרכו לעדכן את אישורי הבסיס באופן ידני מדי פעם.
יישום פרוטוקול בדיקת התקינות של gRPC
מטמיעים את פרוטוקול בדיקת התקינות של GRPC.
הפרוטוקול הזה מאפשר ל-Google לעקוב אחרי סטטוס ה-backend של הטמעת gRPC. מפרט השירות הוא חלק מההפצה של GRPC. בהתאם למוסכמת מתן השמות של GRPC, השם של השירות בקריאות לבדיקת תקינות הוא ext.maps.booking.partner.v2.BookingService ל-API גרסה 2, או ext.maps.booking.partner.v0.BookingService ל-API גרסה 0. בדיקת התקינות צריכה לפעול באותה כתובת URL ובאותו יציאה כמו נקודות הקצה האחרות.
גרסאות אחרות
לעיון בתיעוד של גרסאות אחרות של ה-API, אפשר לעבור לדפים הבאים: * API גרסה 3 * API גרסה 0