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

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

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

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

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

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

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

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

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

משאבי API

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

  • Slot: משבצת מלאי
  • הזמנה: הזמנה למשבצת מלאי

שיטות

חובה להטמיע בצד שלכם את שיטות ה-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 תשלח לשותף את השם הפרטי, שם המשפחה, מספר הטלפון וכתובת האימייל של המשתמש. צריך להתייחס למצב הזה כתשלום כאורח מנקודת המבט של השותף, כי למרכז הפעולות אין דרך לחפש את חשבון המשתמש במערכת של השותף. ההזמנה הסופית צריכה להיות מוצגת למוכרים של השותף, בדיוק כמו הזמנות שמגיעות למערכת ההזמנות של השותף.

הטמעת שלד ב-Java

כדי להתחיל, אנחנו מספקים שרת gRPC שלד ב-Java שניתן להדר אותו ולהתקין אותו. אפשר לראות אותו בקטע Samples > gRPC Reference Implementation. השרת הזה מצמצם את שיטות gRPC שנדרשות כדי לתמוך בשילוב, כולל האימות ושירות הבריאות.

דרישות

שגיאת gRPC ושגיאה בלוגיקה העסקית

יש שני סוגים של שגיאות בצד העורפי של השותף שמטפלים בבקשות gRPC: שגיאות לא צפויות שנובעות מנתונים שגויים; ושגיאות לוגיקה עסקיות שגורמות לחוסר יכולת ליצור הזמנה או לעדכן אותה (ראו כישלון של הזמנות), למשל, אם יחידת הקיבולת הרצויה לא זמינה.

אם יתגלו שגיאות לא צפויות, צריך להחזיר אותן ללקוח באמצעות קודי שגיאה קנוניים של gRPC. הדוגמאות לשימוש כזה כוללות, בין השאר:

  • הערך INVALID_ARGUMENT משמש בקריאות RPC, כגון CheckAvailability ו-CreateLease, ויש להחזיר אותו אם מיקום המשבצת שסופק מכיל מידע לא חוקי.
  • NOT_FOUND משמש בקריאות RPC כמו CreateBooking ו-ListBookings, ויש להחזיר אותו אם המזהה שסופק לא ידוע לשותף.

אפשר לעיין בחומרי העזר של כל שיטה כדי לראות את קודי השגיאה הקנוניים של gRPC, או לעיין ברשימת קודי הסטטוס המלאה.

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

  • נעשה שימוש ב-SLOT_UNAVAILABLE אם המיקום המבוקש לא זמין יותר.
  • נעשה שימוש ב-PAYMENT_ERROR_CARD_TYPE_REJECTED אם סוג כרטיס האשראי שצוין לא מתקבל.

אי-ספיקות

התקשורת ברשת לא תמיד מהימנה, ו-Google Reserve עשויה לנסות לקרוא קריאה נוספת לקריאות RPC אם לא תתקבל תשובה. לכן, כל קריאות ה-RPC שמשתנות מצב (CreateBooking או UpdateBooking) צריכות להיות זהות. הודעות הבקשה בקריאות ה-RPC האלה כוללות אסימוני זהות שמאפשרים לזהות באופן ייחודי את הבקשה, וכך לאפשר לשותף להבחין בין RPC עם ניסיון חוזר (עם כוונה ליצור הזמנה יחידה) לבין שתי הזמנות נפרדות.

הדוגמאות לשימוש כזה כוללות, בין השאר:

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

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

אבטחה ואימות של שרת gRPC

קריאות ממרכז הפעולות לקצה העורפי צריכות להיות מאובטחות באמצעות SSL/TLS, שמבוסס על אימות הדדי של שרת/לקוח. לשם כך, אתם צריכים להשתמש באישור שרת תקף להטמעת ה-gRPC, ולקבל אישור לקוח תקף.

אישור השרת:השרת של השותף צריך להיות מצויד באישור שרת חוקי שמשויך לשם הדומיין של השרת (כאן אפשר למצוא רשימה של רשויות האישורים ברמה הבסיסית). הטמעות של שרתי GRPC אמורות להציג שרשרת אישורים שמובילה לאישור הבסיס. הדרך הקלה ביותר לעשות זאת היא להוסיף לאישור השרת (גם את אישורי הביניים) שסופקו על ידי מארח אתרי האינטרנט של השותף בפורמט PEM.

אישור השרת מאומת בזמן החיבור, ולא מתקבלים אישורים בחתימה עצמית. תוכן האישור בפועל לא נבדק כל עוד האישור בתוקף. תוכלו לבדוק את תוקף האישור באמצעות הפקודה הבאה:

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

אישור לקוח: כדי לאמת אותנו (כ-Google) מול השותף, אנחנו מספקים אישור לקוח שהונפק על ידי G2 של רשות האינטרנט של Google (אישור CA) עם המאפיינים הבאים:

שדה Value
CN mapsbooking.businesslink-3.net
SAN DNS:mapsbooking.businesslink-3.net

השרת של השותף אמור לדחות ניסיונות התחברות ללא אישור הלקוח הזה.

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

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

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

גרסאות אחרות

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