שלב 3: הטמעת שרת ההזמנות של רשימות ההמתנה

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

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

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

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

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

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

שיטות

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

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

שיטה	בקשת HTTP
HealthCheck	GET /v3/HealthCheck/
BatchGetWaitEstimates	POST /v3/BatchGetPendingEstimates/
CreateWaitlistEntry	POST /v3/CreateWaitlistEntry/
GetWaitlistEntry	POST /v3/GetWaitlistEntry/
DeleteWaitlistEntry	POST /v3/DeletewaitlistEntry/

משאבי API

רשימת המתנה

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

• WaitEstimate: הערכת המתנה לפי מספר סועדים ספציפי ולמוכר ספציפי.
• WaitlistEntry: הצטרפות של משתמש לרשימת ההמתנה.

תהליך: יצירת רשומה של רשימת המתנה

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

איור 2: תהליך עבודה ליצירת רשומה ברשימת המתנה

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

הערה: כדי לשלב רשימות המתנה של הזמנות, צריך לשנות את שיטות ה-REST ל-methods הנדרשים של Orderlists.

דרישות

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

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

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

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

• המספר ABOVE_MAX_PARTY_SIZE משמש כשהמספר המבוקש של רשימת ההמתנה חורג מהגודל המקסימלי שנקבע למוכר על ידי המוכר.
• MERCHANT_CLOSED נמצא בשימוש כשרשימת ההמתנה לא פתוחה כי המוכר כבר סגור.

אי-ספיקות

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

• CreateWaitlistEntry
• DeleteWaitlistEntry

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

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

• תגובת HTTP של CreateWaitlistEntry שבוצעה בהצלחה כוללת את מזהה הרשומה שנוצר לרשימת ההמתנה. אם אותו CreateWaitlistEntryRequest מתקבל פעם שנייה (עם אותו idempotency_token), יש להחזיר את אותו CreateWaitlistEntryResponse. לא נוצרה רשומה שנייה לרשימת ההמתנה ולא מוחזרת שגיאה.

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

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