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