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

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

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

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

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

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

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

RTU של API להחלפת זמינות

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

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

יש לך אפשרות להיעזר במשאבים הבאים כדי לקבל מידע נוסף:

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

RTU של ממשק API להתראות על הזמנות

ממשקי ה-API של התראות הזמנה מיידעים את 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

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

היכנסו לכרטיסייה פרטי כניסה במסוף Google API כדי ליצור חשבון שירות. יש לאחסן את המפתח הפרטי בפורמט JSON בצורה בטוחה במקום. כשיוצרים את החשבון, אפשר להגדיר את התפקיד בתור 'Owner' (בעלים).

אימות ממשקי ה-API להזמנות במפות Google

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

• Google Maps Booking API
• ממשק ה-API של מפות Google להזמנה (פיתוח)

למדריך מפורט איך לעשות זאת, אפשר לעיין המדריך לאימות באמצעות Maps Booking API.

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

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

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

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

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

אחזור מסמך Discovery

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

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

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

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

ביצוע קריאות מורשות ל-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) של Sandbox וייצור

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

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

נקודת קצה (endpoint) של Sandbox: 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()