כדי ליצור ולעדכן הזמנות בשמכם, צריך ליצור שרת הזמנות כדי לאפשר למרכז הפעולות לבצע קריאות חוזרות (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: תהליך עבודה ליצירת הזמנה ממשבצת זמן מסוימת](https://developers.google.cn/static/actions-center/images/rest_api_v3_booking_flow_1.png?authuser=8&hl=he)
כשמשתמש יוצר הזמנה, Google שולחת לך את השם הפרטי, שם המשפחה, מספר הטלפון וכתובת האימייל של המשתמש. מנקודת המבט שלך, יש להתייחס להזמנה הזו כאל תשלום כאורח, כי מרכז הפעולות לא יכול לחפש במערכת את חשבון המשתמש. צריך לוודא שההזמנה הסופית זהה להזמנות של המוכרים שמגיעות ממערכת ההזמנות שלך.
אבטחה ואימות
כל התקשורת לשרת ההזמנות מתבצעת באמצעות HTTPS, לכן חשוב שלשרת יהיה אישור TLS חוקי שתואם לשם ה-DNS שלו. כדי לעזור בהגדרת השרת, מומלץ להשתמש בכלי לאימות SSL/TLS שזמין באופן ציבורי, כמו בדיקת שרת SSL של Qualys.
כל הבקשות ש-Google שולחת לשרת ההזמנות יאומתו באמצעות אימות בסיסי של HTTP. אפשר להזין את פרטי הכניסה הבסיסיים לאימות (שם משתמש וסיסמה) עבור שרת ההזמנות בדף ההגדרה של שרת ההזמנות בפורטל השותפים. יש להחליף סיסמאות כל שישה חודשים.
הטמעות של שלד לדוגמה
כדי להתחיל, כדאי לבדוק את השלדים לדוגמה הבאים של שרת הזמנות, שנכתבו עבור 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, וציון הכשל בלוגיקה העסקית בגוף התגובה. יש סוגים שונים של שגיאות לוגיקה עסקיות שעשויות להופיע בהתאם לסוגים השונים של הטמעות שרתים.
- החזרת קוד סטטוס HTTP המוגדר ל-
בהטמעה של 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
נכשל ואותה הבקשה נשלחת מחדש, הקצה העורפי צריך לנסות שוב במקרה הזה.
הדרישה של יכולת הזיהוי חלה על כל השיטות שמשתנות מצב.