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

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

• הטמעה רגילה כך מרכז הפעולות יוכל ליצור איתכם פגישות, הזמנות ורשימות 'לעשות' בשם המשתמש.

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

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

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

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

Methods

לכל סוג של שרת הזמנות נדרשת קבוצה שונה של שיטות API בצד שלכם. אפשר גם להוריד את הגדרת השירות בפורמט proto כדי להתחיל להטמיע את ה-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

הזמנה

בחלק מהמימושים הרגילים נעשה שימוש בסוגי המשאבים הבאים:

• Slot: משבצת במלאי שטחי הפרסום.
• הזמנה: פגישה לגבי משבצת במלאי שטחי הפרסום.

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

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

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

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

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

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

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

• CreateBooking
• UpdateBooking

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

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

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

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

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