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

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

• הטמעת Reservations Waitlists האפשרות הזו משמשת כשאתם משתתפים בתוכנית הפיילוט של רשימות ההמתנה להזמנות. כך אפשר לאחזר ב-Actions Center אומדני זמן המתנה וליצור רשומות ברשימת ההמתנה בשם המשתמש.
• הטמעה רגילה כך מרכז הפעולות יוכל ליצור איתכם פגישות, הזמנות ורשימות 'לעשות' בשם המשתמש. כדי להטמיע שרת הזמנות לשילוב Reservations End-to-End, אפשר לעיין במאמר הטמעת שרת ההזמנות.

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

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

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

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

Methods

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

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

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

משאבי API

רשימת המתנה

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

• WaitEstimate: אומדן זמן ההמתנה למוכרים ולקבוצות ספציפיות.
• WaitlistEntry: הרשמה של משתמש ברשימת ההמתנה.

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

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

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

אבטחה ואימות

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

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

דוגמאות להטמעות של שלדים

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

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

בשרתים האלה יש stubs של שיטות REST.

דרישות

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

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

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

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

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

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

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

• CreateWaitlistEntry
• DeleteWaitlistEntry

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

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

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

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

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