עדכונים בזמן אמת מיועדים בעיקר לעדכונים שלא ניתן לצפות מראש, כמו סגירות חירום, או מטא-נתונים שמשתנים מעת לעת (כמו זמני הגעה משוערים). אם השינוי לא צריך להשתקף באופן מיידי, אפשר להשתמש במקום זאת בהעלאה של פידים באצווה. העדכונים בזמן אמת מעובדים תוך חמש דקות לכל היותר.
הגדרה של Google Cloud Platform
- מגדירים פרויקט ב-GCP. כדי לגשת ל-RTU API, צריך פרויקט GCP.
- מתן גישת עריכה food-support@google.com
- צריך להודיע לאיש הקשר ב-Google על מספר פרויקט GCP.כדי שהעדכונים בזמן אמת יפעלו, פרויקט GCP צריך להיות משויך לחשבון שלכם במרכז הפעולות.
- מפעילים את Maps Booking API:
- ב-GCP, עוברים אל APIs & Services > Library (ממשקי API ושירותים > ספרייה).
- מחפשים את Google Maps Booking API.
- מאתרים את מופע ארגז החול (Google Maps Booking API (Dev)) ולוחצים על הפעלה.
- מחפשים את מופע הייצור (Google Maps Booking API) ולוחצים על הפעלה.
- יוצרים חשבון שירות עם תפקיד עריכה בפרויקט GCP. פרטים נוספים זמינים במאמר בנושא הגדרת חשבון שירות.
- חשוב להקפיד להעלות פידים של קבוצות מוצרים לסביבה שבה אתם עובדים על עדכונים בזמן אמת.
- לצורך אימות API, מומלץ להתקין את ספריית הלקוח של Google בשפה הרצויה. משתמשים ב-https://www.googleapis.com/auth/mapsbooking כהיקף OAuth. דוגמאות הקוד שבהמשך משתמשות בספריות האלה. אחרת, תצטרכו לטפל בהחלפות אסימונים באופן ידני, כמו שמתואר במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.
הגדרת חשבון שירות
כדי לשלוח בקשות HTTPS מאומתות ל-Google APIs, כמו real-time updates API, צריך חשבון שירות.
כדי להגדיר חשבון שירות, צריך לבצע את הפעולות הבאות:
- נכנסים למסוף Google Cloud Platform.
- לחשבון שלכם במרכז הפעולות משויך גם פרויקט ב-Google Cloud. בוחרים את הפרויקט הזה, אם הוא עוד לא נבחר.
- בתפריט הימני, לוחצים על חשבונות שירות.
- לוחצים על יצירת חשבון שירות.
- מזינים שם לחשבון השירות ולוחצים על יצירה.
- בשדה Select a role (בחירת תפקיד), בוחרים באפשרות Project > Editor (פרויקט > עריכה).
- לוחצים על המשך.
- אופציונלי: מוסיפים משתמשים כדי להעניק להם גישה לחשבון השירות ולוחצים על Done.
- לוחצים על סמל האפשרויות הנוספות > יצירת מפתח בחשבון השירות שיצרתם.
- בוחרים באפשרות JSON כפורמט ולוחצים על Create.
- אחרי שנוצר זוג המפתחות הציבורי/פרטי החדש, מורידים אותו למחשב.
עבודה עם ה-API
ממשק ה-API של עדכונים בזמן אמת תומך בשני סוגי פעולות: עדכון ומחיקה. אי אפשר להוסיף ישויות חדשות באמצעות ה-API לעדכון בזמן אמת. אפשר לשלוח עדכונים בזמן אמת באצווה אם כוללים כמה עדכונים בבקשת API אחת. אפשר לשלוח עד 1,000 עדכונים בקריאה אחת ל-API. אם אפשר, מומלץ להשתמש בגישה מבוססת-טריגר לשליחת עדכונים באמצעות RTU (כלומר, אם יש שינוי בנתונים במערכת, מופעל טריגר לעדכון בזמן אמת ב-Google) ולא בגישה מבוססת-תדירות (כלומר, כל X דקות המערכת נסרקת כדי לזהות שינויים).
ממשק ה-API לעדכונים בזמן אמת פועל בסביבות ארגז חול וייצור. סביבת ארגז החול משמשת לבדיקת בקשות ה-API, וסביבת הייצור משמשת לעדכון התוכן שגלוי למשתמשי הקצה של התכונה 'הזמנה מקצה לקצה'.
- ארגז חול –
partnerdev-mapsbooking.googleapis.com - ייצור –
mapsbooking.googleapis.com
נקודות קצה
ממשק ה-API לעדכונים בזמן אמת חושף שתי נקודות קצה לטיפול בבקשות הנכנסות לעדכוני מלאי:
- עדכון –
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - מחיקה –
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
הפרמטר PARTNER_ID מופיע במרכז הפעולות בדף חשבון ומשתמשים, כמו שמוצג בצילום המסך שלמטה.
אם ניקח את הערך 10000001 כדוגמה ל-PARTNER_ID מצילום המסך שלמעלה, כתובות ה-URL המלאות לשליחת בקשות API בסביבת ארגז חול ובסביבת ייצור ייראו כמו בדוגמאות שלמטה.
עדכון ארגז חול
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
מחיקה של ארגז חול
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
עדכון לגבי הפקה
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Production DELETE
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
עדכון ישויות
כדי לעדכן ישויות במלאי, משתמשים בנקודת הקצה update בבקשת HTTP POST. כל בקשת POST חייבת לכלול את הפרמטר 10000001, יחד עם מטען ייעודי (payload) בפורמט JSON שמכיל את הישות שרוצים לעדכן.
הערה: חשוב לוודא שפידי הנתונים היומיים כוללים גם את השינויים שנשלחו באמצעות API לעדכונים בזמן אמת. אחרת, יכול להיות שהנתונים לא יהיו עדכניים או שהם יהיו מיושנים.
עדכון מטען ייעודי (payload) של בקשה
גוף הבקשה הוא אובייקט JSON עם רשימה של רשומות. כל רשומה מתאימה לישות שעוברת עדכון. הוא כולל את השדה proto_record ואת השדה generation_timestamp שמציין את השעה שבה בוצע עדכון של הישות:
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}-
ServiceData PROTO: התרגום ל-proto או ל-JSON של הישות ServiceData שאתם מעדכנים. -
UPDATE_TIMESTAMP: הקפידו לכלול את חותמת הזמן של מועד יצירת הישות במערכות העורפיות שלכם. אם השדה הזה לא נכלל, הוא יוגדר לזמן שבו Google מקבלת את הבקשה. כשמעדכנים ישות באמצעות בקשתbatchPush, השדהgeneration_timestampמשמש לניהול גרסאות של ישויות. בסכימת המלאי הרלציונית מפורט הפורמט הצפוי של ערכי הזמן.
- גודל הגוף של המטען הייעודי (payload) לא יכול להיות גדול מ-5MB.
- הסרת רווחים לבנים כדי להקטין את הגודל.
- אפשר לכלול עד 1,000 עדכונים בבקשה
batchPush.
דוגמאות
עדכון של מודעת טקסט מורחבת
נניח שאתם צריכים לעדכן בדחיפות את זמן ההגעה המשוער של שירות משלוחים מ-30-60 דקות ל-60-90 דקות. העדכון צריך לכלול את ה-JSON של כל ישות השירות.
נבחן ישות שירות שנראית כך:
{ "service": { "service_id": "service/entity002", "service_type": "DELIVERY", "parent_entity_id": "entity002", "lead_time": { "min_lead_time_duration": "600s", "max_lead_time_duration": "1800s" }, "action_link_id": "delivery_link/entity002" } }
העדכון בזמן אמת באמצעות HTTP POST הוא כדלקמן (גופי הבקשות מודפסים בצורה נוחה לקריאה):
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "3600" }, "max_lead_time_duration" : { "seconds": "5400" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }] }
עדכון של כמה ישויות
כדי לעדכן כמה ישויות של מסעדות בקריאה אחת ל-API, צריך לכלול כמה רשומות בשדה proto_record של גוף הבקשה.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "1800" }, "max_lead_time_duration" : { "seconds": "3600" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee", "fee_type" : "DELIVERY", "fixed_amount" : { "currency_code" : "USD", "units" : "10", "nanos" : "0" }, "service_ids": ["service/entity002"] } }, "generation_timestamp" : "2023-09-13T17:11:10.750Z" }] }
מחיקת ישויות
כדי למחוק ישויות מהמלאי, משתמשים בנקודת הקצה DELETE בבקשת HTTP POST. כל בקשת POST חייבת לכלול את הפרמטר PARTNER_ID יחד עם מטען ה-JSON שמכיל את המזהה של הישות שרוצים למחוק.
הערה: חשוב לוודא שפידי הנתונים היומיים כוללים גם את השינויים שנשלחו באמצעות ה-API לעדכון בזמן אמת. אחרת, הטמעת הנתונים היומית תדרוס את השינויים שביצעתם בזמן אמת.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery" } }, "delete_time": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee" } }, "delete_time" : "2023-09-13T17:11:10.750Z" }] }
הוספת ישויות
אל תשתמשו בעדכונים בזמן אמת כדי להוסיף ישויות חדשות, כי זה עלול לגרום לחוסר עקביות בנתונים. במקום זאת, אפשר להשתמש בפידים של קבוצות מוצרים.
אימות וקודי תגובה של API
יש שני סוגי אימותים שמתבצעים בקריאות ל-API של עדכונים בזמן אמת:
- ברמת הבקשה – האימותים האלה בודקים שהמטען הייעודי (payload) תואם לסכימה וכל
proto_recordמכיל את השדותidו-type. הבדיקות האלה סינכרוניות והתוצאות מוחזרות בגוף התגובה של ה-API. קוד תגובה 200 וגוף JSON ריק{}מציינים שהאימותים האלה עברו בהצלחה והישויות בבקשה הזו הוכנסו לתור לעיבוד. קוד תשובה שאינו 200 מציין שאחד או יותר מהאימותים האלה נכשלו, ושהבקשה כולה נדחית (כולל כל הישויות במטען הייעודי). לדוגמה, אם חסר@typeב-proto_record, תוחזר תגובת השגיאה הבאה:
{ "error": { "code": 400, "message": "Record:{...}", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.DebugInfo", "detail": "[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:... The entity type could not be extracted from the entity value." } ] }
- ברמת הישות: כל ישות (proto_record) במטען הייעודי (payload) עוברת אימות מול הסכימה. בעיות שנתקלים בהן בשלב הזה של האימות לא מדווחות בתגובת ה-API. הן מדווחות רק בלוח הבקרה RTU Reporting במרכז הפעולות.
הערה: קוד תגובה 200 לא אומר שכל הישויות נקלטו בהצלחה.
מכסות ל-API
לעדכונים בזמן אמת של API יש מכסה של 1,500 בקשות כל 60 שניות, או 25 בקשות לשנייה בממוצע. כשחורגים ממכסה, Google מגיבה בהודעת השגיאה הבאה:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}כדי לטפל בבעיה הזו, צריך לנסות שוב להתקשר במרווחי זמן גדולים יותר באופן מעריכי עד שהשיחה תתבצע. אם אתם מגיעים למכסה באופן קבוע, כדאי לכלול יותר ישויות בבקשת API אחת. אפשר לכלול עד 1,000 ישויות בקריאה אחת ל-API.
עדכונים בזמן אמת לגבי משך הטיפול
עיבוד של ישות שעודכנה באמצעות עדכון בזמן אמת מתבצע תוך 5 דקות.