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

הערה: הדרישה לנקודת הקצה הזו משתנה בהתאם לשילוב. עליך לברר עם איש הקשר שלך ב-Google מהן נקודות הקצה (endpoint) הנדרשות.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

למידע נוסף על הגישה ל-API מ-Ruby, אפשר להיכנס לקישורים הבאים: לקוח Ruby API ו-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) של Sandbox וסביבת הייצור

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

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

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