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

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

Availability Replace API RTU

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

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

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

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

Booking Notification API RTU

ממשקי ה-API של Booking Notification שולחים ל-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.

נקודות קצה של ארגז חול וייצור

אפשר לבצע קריאות גם לסביבת ארגז החול וגם לסביבת הייצור דרך ה-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()