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

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

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

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

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

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

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

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

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

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

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

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

• מדריך: איך לבנות עדכונים בזמן אמת
• דוגמה ללקוח Java לצורך עדכונים בזמן אמת באמצעות קריאות ל-REST
• דף הפנייה לממשק 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

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

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

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

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

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

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

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

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

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

נקודות קצה ב-Sandbox ובסביבת ייצור

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

נקודת סיום הפקה: 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()