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

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

הטמעת ממשק API על סמך gRPC

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

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

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

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

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

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

משאבי API

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

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

שיטות

חובה להטמיע את שיטות ה-API הבאות בצד שלכם עבור שרת gRPC:

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

דרישות

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

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

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

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

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

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

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

האידמפוטנטיות

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

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

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

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

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

שיחות מ-Actions Center (מרכז הפעולות) לקצה העורפי צריכות להיות מאובטחות באמצעות 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 רשות 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