שלב 5: עדכוני API בזמן אמת

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

עדכונים ופידים בזמן אמת ב-API

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

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

ממשקי API נדרשים לעדכונים בזמן אמת

ממשקי API של עדכונים בזמן אמת (RTU)
BookingNotification	חובה	שולחים יחידות RTU של BookingNotification בכל פעם שיש שינוי בהזמנה (למשל שינויים או ביטולים).
זמינות של החלפת RTU	חובה בתנאים מסוימים[1]	כדי לשלוח עדכונים לגבי זמינות מלאי, צריך לשלוח RTU מסוג החלפה באצווה או החלפה בודדת. יכול להיות שיחלפו כמה דקות עד שהשינויים יופצו ויוצגו.
Merchant RTU	אופציונלי	אם רוצים לבצע שינויים בפרטי המוכר בזמן אמת, צריך לשלוח RTU של המוכר. יכול להיות שיעברו כמה שעות עד שהשינויים יופצו ויופיעו.
Service RTU	אופציונלי	אם רוצים לבצע שינויים בפרטי השירות בזמן אמת, צריך לשלוח יחידות RTU של השירות. מקרה שימוש נפוץ הוא אם מחירי השירות משתנים באופן משמעותי במהלך היום. במקרה כזה, מומלץ להטמיע יחידות RTU של שירות כדי למנוע כשלים בהזמנות בגלל חוסר התאמה במחירים. יכול להיות שיחלפו כמה שעות עד שהשינויים יופצו ויופיעו.

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

Availability Replace API RTU

אתם יכולים להשתמש ב-Availability Replace API כדי לספק עדכוני זמינות בתרחישי השימוש הבאים:

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

מידע נוסף זמין במקורות המידע הבאים:

• הדרכה: איך יוצרים עדכונים בזמן אמת
• דוגמה ללקוח Java לעדכונים בזמן אמת באמצעות קריאות RESTful
• דף ההפניה של Inventory Update API

Booking Notification API RTU

ממשקי Booking Notification APIs שולחים ל-Google הודעות על עדכונים בהזמנות קיימות. כששולחים עדכון לגבי ביטולים, צריך לשלוח רק את המידע החיוני בבקשה עם פרמטר השאילתה updateMask. לדוגמה:

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"CANCELED"}

גישה ל-API

יצירה של חשבון שירות

משתמשים בכרטיסייה Credentials ב-Google API Console כדי ליצור חשבון שירות. שומרים את המפתח הפרטי בפורמט JSON במקום בטוח. כשיוצרים את החשבון, אפשר להגדיר את התפקיד כ'בעלים'.

אימות של ממשקי Google Maps Booking APIs

אחרי שיוצרים חשבון שירות, מאמתים את הממשקי ה-API הבאים:

• Google Maps Booking API
• ‫Google Maps Booking API (פיתוח)

מדריך מפורט בנושא אימות באמצעות Maps Booking API

שימוש בקריאות RESTful או הורדה של ספריית הלקוח

מומלץ לשלוח קריאות RESTful ישירות ל-Maps Booking API עם מטען ייעודי (payload) בפורמט JSON. מידע נוסף מופיע במאמרי העזרה של REST API.

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

שפה	קישור להורדה
Java	ספריית לקוח Java. מידע נוסף זמין במאמר הוראות ללקוח Java.

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

אחזור מסמך הגילוי

בספריות לקוח מסוימות, כמו Ruby, צריך לאחזר את מסמך הגילוי של ה-API, שמתאר את השיטות והפרמטרים שלו.

משתמשים בפקודה הבאה כדי לאחזר את מסמך הגילוי:

curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'

למידע נוסף על גישה ל-API מ-Ruby, אפשר לעיין בקישורים הבאים: Ruby API Client ו-Ruby Auth Library.

ביצוע קריאות מורשות ל-API

כשמבצעים קריאות ל-API, צריך לעיין במאמר הכנה לביצוע קריאה מורשית ל-API כדי לתת הרשאה לחשבון השירות באמצעות המפתח הפרטי והיקף OAuth הבא: https://www.googleapis.com/auth/mapsbooking.

מכסות ל-API

לעדכוני API יש מכסה של 1,500 בקשות כל 60 שניות, או 25 בקשות בממוצע לשנייה. אם חרגתם מהמכסה (מה שיכול לקרות אם לא הוספתם את מספר הפרויקט הנכון ב-Google Cloud בפורטל השותפים), Google תשלח לכם את הודעת השגיאה הבאה:

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

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

נקודות קצה (endpoints) של ארגז חול ושל סביבת ייצור

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

נקודת הקצה של סביבת הייצור: https://mapsbooking.googleapis.com/

נקודת קצה של ארגז חול: https://partnerdev-mapsbooking.googleapis.com/

הדוגמה הבאה ב-Java מראה איך להחליף נקודות קצה:

    // This block of code is for OAuth and is the same for prod and sandbox.
    GoogleCredential
      .fromStream(new FileInputStream(...))
      .createScoped(Collections.singleton("https://www.googleapis.com/auth/mapsbooking"))

    // This block of code sets the endpoint. This is what you'd change to connect to the sandbox.
    new GoogleMapsBookingAPI.Builder(...)
      .setApplicationName(...)
      .setRootUrl("https://partnerdev-mapsbooking.googleapis.com/") // you add this to change the endpoint to use partnerdev.
      .build()