עליכם ליצור שרת הזמנות כדי לאפשר ל-'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
הזמנה
סוגי המשאבים הבאים משמשים בהטמעה הרגילה:
זרימה: יצירת הזמנה
בקטע הזה מוסבר איך ליצור הזמנה להטמעת מודעות רגילה.
כשמשתמש יוצר הזמנה, Google שולחת לכם את השם הפרטי, שם המשפחה, מספר הטלפון והאימייל שלו. מנקודת המבט שלך, צריך לראות את ההזמנה הזו כתשלום כאורח, כי שירות Google הזמנת מקומות לא יכול לחפש את החשבון של המשתמש במערכת שלך. חשוב לוודא שההזמנה הסופית זהה להזמנות של המוכרים שמגיעים ממערכת ההזמנות שלך.
אבטחה ואימות
כל התקשורת עם שרת ההזמנות מתבצעת באמצעות HTTPS, ולכן חשוב מאוד שלשרת יהיה אישור TLS חוקי שתואם לשם ה-DNS שלו. כדי לעזור בהגדרת השרת, מומלץ להשתמש בכלי לאימות SSL/TLS שזמין לציבור, כמו בדיקת שרת SSL של Qualys.
כל הבקשות ש-Google תשלח לשרת ההזמנות שלך יאומתו באמצעות אימות בסיסי של HTTP. אפשר להזין את פרטי הכניסה הבסיסיים (שם משתמש וסיסמה) לשרת ההזמנות שלך בדף 'הגדרות של שרתי הזמנות' בפורטל השותפים. יש לבצע רוטציה לסיסמאות מדי שישה חודשים.
הטמעות של שלדים לדוגמה
כדי להתחיל, כדאי לראות את הדגמים הבאים של שלדים של שרת הזמנות, שנכתבו עבור מסגרות 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 ל-
בהטמעה הרגילה, השגיאות האפשריות בלוגיקה העסקית מתועדות בהזמנה נכשל והן מוחזרות בתגובת ה-HTTP. שגיאות בלוגיקה של העסק עשויות להופיע כשיוצרים או מעדכנים משאב. לדוגמה, אם משתמשים בשיטות CreateBooking
או UpdatingBooking
. דוגמאות לכך כוללות, בין היתר:
SLOT_UNAVAILABLE
ישמש אם המשבצת המבוקשת כבר לא זמינה.- ייעשה שימוש ב-
PAYMENT_ERROR_CARD_TYPE_REJECTED
אם סוג כרטיס האשראי שצוין לא קביל.
אימפוטנציה
התקשורת ברשת לא תמיד מהימנה, ו-Google עשויה לנסות שוב לשלוח בקשות HTTP אם לא תתקבל תגובה. מסיבה זו, כל השיטות המשנות את המצב חייבות להיות ברורות.
CreateBooking
UpdateBooking
עבור כל הודעת בקשה, מלבד UpdateBooking
, אסימוני אישור נכללים כדי לזהות את הבקשה באופן ייחודי. כך אפשר להבדיל בין קריאות חוזרות ל-REST, במטרה ליצור בקשה יחידה, ושתי בקשות נפרדות.
UpdateBooking
מזוהה באופן ייחודי
באמצעות מזהה כניסה של הזמנה, בהתאמה,
ולכן לא מצוינים אסימון ים בבקשות שלו.
ריכזנו כאן כמה דוגמאות לאופן שבו שרתי הזמנות מתמודדים עם ים מעורפל:
תגובת HTTP
CreateBooking
שבוצעה בהצלחה כוללת את ההזמנה שנוצרה. במקרים מסוימים, התשלום מעובד כחלק מתהליך ההזמנה. אם אותוCreateBookingRequest
בדיוק מתקבל בפעם השנייה (עם אותוidempotency_token
), צריך להחזיר את אותוCreateBookingResponse
. לא נוצרת הזמנה שנייה, והמשתמש מחויב פעם אחת בלבד, אם רלוונטי.לידיעתך, אם ניסיון
CreateBooking
ייכשל ואותה בקשה תישלח שוב, הקצה העורפי שלך יצטרך לנסות שוב במקרה הזה.
הדרישה לתיבת האידיאולוגית חלה על כל השיטות המשנות את המצב.