שלב 4: מטמיעים את שרת ההזמנות

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

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

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

הטמעה של ממשק API ל-REST

מטמיעים ממשק API שמבוסס על REST. כך Google יכולה לשלוח בקשות משרת הזמנות באמצעות HTTP.

כדי להתחיל, צריך להגדיר שרת הזמנות של פיתוח או ארגז חול שאפשר לחבר לסביבת ארגז החול של מרכז הפעולות. צריך לעבור לסביבת ייצור רק אחרי ששרת ה-Sandbox נבדק בצורה מלאה.

שיטות

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

יישום סטנדרטי
הגדרת שירות רגילה הורד את קובץ הגדרת השירות של proto.

שיטה	בקשת HTTP
HealthCheck	GET /v3/HealthCheck/
BatchAvailabilityLookup	POST /v3/BatchAvailabilityLookup/
CreateBooking	POST /v3/CreateBooking/
UpdateBooking	POST /v3/UpdateBooking/
GetBookingStatus	POST /v3/GetBookingStatus/
ListBookings	POST /v3/ListBookings/

משאבי API

הזמנה

בהטמעה הרגילה נעשה שימוש בסוגי המשאבים הבאים:

• משבצת: משבצת מלאי.
• קביעת פגישה: פגישה למשבצת מלאי.

תהליך עבודה: יצירת הזמנה

בקטע הזה מוסבר איך ליצור הזמנה להטמעה הרגילה.

איור 1: תהליך עבודה ליצירת הזמנה ממשבצת זמן מסוימת

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

אבטחה ואימות

כל התקשורת לשרת ההזמנות מתבצעת באמצעות HTTPS, לכן חשוב שלשרת יהיה אישור TLS חוקי שתואם לשם ה-DNS שלו. כדי לעזור בהגדרת השרת, מומלץ להשתמש בכלי לאימות SSL/TLS שזמין באופן ציבורי, כמו בדיקת שרת SSL של Qualys.

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

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

הטמעות של שלד לדוגמה

כדי להתחיל, כדאי לבדוק את השלדים לדוגמה הבאים של שרת הזמנות, שנכתבו עבור Node.js ו-Java frameworks:

• שלד של Node.js js-maps-booking-rest-server-v3-skeleton
• שלד של Java java-maps-booking-rest-server-v3-skeleton

השרתים האלה מצמצמים את שיטות ה-REST.

דרישות

שגיאות HTTP ושגיאות לוגיקה עסקית

כשהקצה העורפי מטפל בבקשות HTTP, עשויות להתרחש שגיאות משני סוגים.

• שגיאות שקשורות לתשתית או לנתונים שגויים
  • מחזירים את השגיאות האלה ללקוח עם קודים רגילים של שגיאות HTTP. כאן תוכלו לקרוא את הרשימה המלאה של קודי המצב של HTTP.
• שגיאות שקשורות ללוגיקה העסקית
  • החזרת קוד סטטוס HTTP המוגדר ל-200 OK, וציון הכשל בלוגיקה העסקית בגוף התגובה. יש סוגים שונים של שגיאות לוגיקה עסקיות שעשויות להופיע בהתאם לסוגים השונים של הטמעות שרתים.

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

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

אי-ספיקות

התקשורת ברשת לא תמיד מהימנה, ו-Google עשויה לנסות שוב בקשות HTTP אם לא מתקבלת תשובה. מסיבה זו, כל השיטות שמשנים את המצב חייבות להיות אידמפונטיות:

• CreateBooking
• UpdateBooking

לכל הודעת בקשה פרט ל-UpdateBooking, נכללים אסימוני זהות כדי לזהות את הבקשה באופן ייחודי. כך ניתן להבחין בין קריאה חוזרת ל-REST מתוך כוונה ליצור בקשה אחת לבין שתי בקשות נפרדות. המזהה UpdateBooking מזוהה באופן ייחודי לפי מזהי רשומות ההזמנות שלו, בהתאמה, ולכן לא נכלל אסימון זהות בבקשות שלו.

בהמשך מפורטות כמה דוגמאות לאופן שבו שרתי הזמנות מטפלים בהעברת נתונים:

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

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

הדרישה של יכולת הזיהוי חלה על כל השיטות שמשתנות מצב.