הטמעה של שרת ההזמנות

עליכם ליצור שרת הזמנות כדי לאפשר ל-'Google הזמנת מקומות' להתקשר חזרה כדי ליצור ולעדכן הזמנות בשמכם.

• הטמעה רגילה. ההרשאה הזו מאפשרת ל-Google הזמנת מקומות ליצור פגישות, הזמנות והזמנות בשם המשתמשים.

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

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

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

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

שיטות

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

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

‏Method	בקשת HTTP
קופת חולים	קבלת /v3/HealthCheck/
BatchAvailabilityLookup	POST /v3/BatchAvailabilityLookup/
יצירת הזמנה	POST /v3/CreateBooking/
UpdateBooking	POST /v3/UpdateBooking/
קבלת סטטוס של BookBooking	POST /v3/GetBookingStatus/
רשימת הזמנות	POST /v3/ListBookings/

משאבי API

הזמנה

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

• חריץ: משבצת מלאי.
• הזמנה: פגישה במשבצת לפגישה.

זרימה: יצירת הזמנה

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

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

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

אבטחה ואימות

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

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

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

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

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

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

השרתים האלה הפסיקו את השימוש בשיטות REST.

דרישות

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

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

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

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

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

אימפוטנציה

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

• CreateBooking
• UpdateBooking

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

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

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

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

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