הטמעת שרת ההזמנות: API v2

הגדרת שרת לקביעת פגישות אצלכם תאפשר למרכז הפעולות ליצור פגישות / הזמנות / שולחנות איתכם מטעם המשתמש.

הטמעת ממשק API שמבוסס על gRPC

לתשומת ליבכם: כל השותפים החדשים צריכים להשתמש בממשק API ל-REST במקום ב-API ל-gRPC.

הטמעת ממשק API שמבוסס על gRPC. כך Google תוכל לשלוח בקשות להזמנה. ממשק ה-API מוגדר באמצעות IDL שמבוסס על protobuf של gRPC.

אנחנו מבקשים מהשותפים החדשים שלנו להטמיע קבוצה מומלצת של API v2. השותפים יכולים לבחור את כתובת ה-URL ואת היציאה שמתאימים ביותר לתשתית שלהם.

בקטע הזה נספק לכם המלצה לגבי קבוצה של ממשקי API v2. היא חלה על שותפים שלא הטמיעו את API v0. השותפים הנוכחיים שלנו שהטמיעו את API v0 יכולים לפנות למרכז הפעולות כדי לקבל מידע נוסף.

כדי להתחיל בהטמעת ה-API, מורידים את הגדרת השירות בפורמט proto שבהמשך.

הורדת הגדרת השירות

משאבי API

כדאי להכיר את סוגי המשאבים הבאים, שיעזרו לכם לבצע את ההטמעה הזו:

  • Slot: משבצת במלאי שטחי הפרסום
  • הזמנה: קביעת פגישה לשימוש במקום במלאי שטחי הפרסום

Methods

חובה להטמיע את שיטות ה-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) {}
}

תהליך: יצירת הזמנה

איור 1: יצירת הזמנה מחלון זמנים

כשיוצרים הזמנה, Google שולחת לשותף את השם הפרטי, שם המשפחה, מספר הטלפון וכתובת האימייל של המשתמש. מבחינת השותף, צריך להתייחס לכך כאל תשלום של אורח, כי ל-Actions Center אין אפשרות לחפש את החשבון של המשתמש במערכת של השותף. ההזמנה הסופית אמורה להופיע אצל המוכרים של השותף במערכת שלהם, בדיוק כמו הזמנות שמגיעות ממערכת ההזמנות של השותף.

הטמעת שלד ב-Java

כדי להתחיל, אנחנו מספקים שרת gRPC ב-Java שאפשר לקמפל ולהתקין. אפשר למצוא אותו בקטע Samples > gRPC Reference Implementation. בשרת הזה יש stubs של שיטות 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) צריכות להיות חד-פעמיות (idempotent). הודעות הבקשה של RPCs האלה כוללות אסימונים של חד-פעמיות (idempotency) כדי לזהות את הבקשה באופן ייחודי ולאפשר לשותף להבדיל בין ניסיון חוזר ל-RPC (בכוונת ליצור הזמנה אחת) לבין שתי הזמנות נפרדות.

הנה כמה דוגמאות:

  • תגובה מוצלחת של קריאה חוזרת ל-RPC מסוג CreateBooking כוללת את ההזמנה שנוצרה, ובמקרים מסוימים התשלום מעובד כחלק מתהליך ההזמנה. אם תקבלו את אותה בקשה ליצירת הזמנה בדיוק בפעם השנייה (כולל idempotency_token), תצטרכו להחזיר את אותה תשובה ליצירת הזמנה. לא נוצרת הזמנה שנייה והמשתמש, במקרה הרלוונטי, יחויב רק פעם אחת. חשוב לזכור: אם הניסיון ליצור הזמנה נכשל, הצד העורפי של השותף צריך לנסות שוב אם אותה בקשה נשלחת שוב.

הדרישה לפעולה חד-פעמית חלה על כל השיטות שמכילות אסימונים של פעולה חד-פעמית.

אבטחה ואימות של שרת 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‏ (אישור CA) עם המאפיינים הבאים:

שדה ערך
CN mapsbooking.businesslink-3.net
SAN DNS:mapsbooking.businesslink-3.net

ניסיונות קישור ללא אישור הלקוח הזה צריכים להידחות על ידי שרת השותף.

כדי לאמת את אישור הלקוח, השרת מסתמך על קבוצה של אישורי root מהימנים של לקוחות. אפשר לקבל את קבוצת הרשומות הבסיסיות המהימנה הזו מרשויות כמו Mozilla, או להתקין את קבוצת הרשומות הבסיסיות המומלצת כרגע על ידי Google Internet Authority G2. בשני המקרים, יכול להיות שתצטרכו לעדכן את אישורי הבסיס באופן ידני מדי פעם.

הטמעת פרוטוקול בדיקת התקינות של gRPC

מטמיעים את פרוטוקול בדיקת התקינות של GRPC. הפרוטוקול הזה מאפשר ל-Google לעקוב אחרי סטטוס הקצה העורפי של הטמעת ה-gRPC. מפרט השירות הוא חלק מההפצה של GRPC. בהתאם למוסכמת השמות של GRPC, השם של השירות בקריאות לבדיקת תקינות הוא ext.maps.booking.partner.v2.BookingService לגרסה 2 של ה-API או ext.maps.booking.partner.v0.BookingService לגרסה 0 של ה-API. בדיקת התקינות צריכה לפעול באותה כתובת URL ובאותו יציאה (port) כמו נקודות הקצה האחרות.

גרסאות אחרות

למסמכי תיעוד לגרסאות אחרות של ה-API, אפשר לעיין בדפים הבאים: * API v3 * API v0