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

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

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

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

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

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

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

Availability Replace API RTU

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

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

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

Booking Notification API RTU

ממשקי ה-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

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

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

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

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

  • Google Maps Booking API
  • Google Maps Booking API (Dev)

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

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

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

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

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

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

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

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

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

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. בעזרת ה-method הזה אפשר לעדכן כמה שירותים בקריאה אחת ל-API.

נקודות קצה (endpoints) בסביבת Sandbox ובסביבה ייצור

אפשר לבצע קריאות לסביבת ה-sandbox ולסביבת הייצור דרך ה-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()
הקודם
שלב 4: הטמעת שרת ההזמנות
הבא
שלב 6: בדיקה מקיפה (end-to-end)