עדכון בזמן אמת

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

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

הגדרה של Google Cloud Platform

  1. מגדירים פרויקט GCP. כדי לגשת ל-RTU API, נדרש פרויקט GCP.
    • הענקת הרשאת עריכה food-support@google.com
    • עליכם להודיע לנציג התמיכה של Google על מספר הפרויקט ב-GCP.הפרויקט ב-GCP צריך להיות משויך לחשבון שלכם ב-Actions Center כדי שהעדכונים בזמן אמת יפעלו.
    • מפעילים את Maps Booking API:
      • ב-GCP, עוברים אל APIs & Services (ממשקי API ושירותים) > Library (ספרייה).
      • מחפשים את 'Google Maps Booking API'.
        איתור ממשקי Google Maps Booking API
      • מאתרים את המכונה בארגז החול (Google Maps Booking API (Dev)) ולוחצים על Enable (הפעלה).
      • מחפשים את המכונה בסביבת הייצור (Google Maps Booking API) ולוחצים על Enable (הפעלה).
        הפעלת Google Maps Booking API
      • יוצרים חשבון שירות עם תפקיד עריכה בפרויקט GCP. פרטים נוספים זמינים במאמר הגדרת חשבון שירות.
      • חשוב להעלות פידים של קבוצות נתונים לסביבה שבה אתם עובדים על עדכונים בזמן אמת.
      • לאימות API, מומלץ להתקין את ספריית הלקוח של Google בשפה הרצויה. צריך להשתמש ב-'https://www.googleapis.com/auth/mapsbooking' בתור היקף הרשאת OAuth. בדוגמאות הקוד שמפורטות בהמשך נעשה שימוש בספריות האלה. אחרת, תצטרכו לטפל בהחלפות האסימונים באופן ידני, כפי שמתואר במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

הגדרת חשבון שירות

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

כדי להגדיר חשבון שירות:

  1. נכנסים למסוף Google Cloud Platform.
  2. לחשבון שלכם במרכז הפעולות משויך גם פרויקט ב-Google Cloud. בוחרים את הפרויקט הזה, אם הוא עדיין לא נבחר.
  3. לוחצים על חשבונות שירות בתפריט שמימין.
  4. לוחצים על Create Service Account.
  5. מזינים שם לחשבון השירות ולוחצים על Create.
  6. בשדה Select a role (בחירת תפקיד), בוחרים באפשרות Project > Editor.
  7. לוחצים על המשך.
  8. אופציונלי: מוסיפים משתמשים כדי להעניק להם גישה לחשבון השירות ולוחצים על Done.
  9. לוחצים על סמל האפשרויות הנוספות > יצירת מפתח עבור חשבון השירות שיצרתם.
  10. בוחרים בפורמט JSON ולוחצים על Create.
  11. אחרי שיוצרים את זוג המפתחות החדש – ציבורי ופרטי – מורידים אותו למחשב.

עבודה עם ה-API

ממשק ה-API של עדכונים בזמן אמת תומך בשני סוגים של פעולות: עדכון ומחיקה. אין תמיכה בהוספת ישויות חדשות באמצעות ממשק ה-API לעדכון בזמן אמת. אפשר לשלוח עדכונים בזמן אמת באצווה אם כוללים כמה עדכונים בבקשת API אחת. אפשר לשלוח עד 1,000 עדכונים באצווה בקריאה אחת ל-API. אם אפשר, מומלץ להשתמש בגישה מבוססת-טריגר כדי לשלוח עדכונים באמצעות RTU (כלומר, כשיש שינוי בנתונים במערכת, מפעילים עדכון בזמן אמת ל-Google) במקום בגישה מבוססת-תדירות (כלומר, סורקים את המערכת כל X דקות כדי לזהות שינויים).

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

  • ארגז חול – partnerdev-mapsbooking.googleapis.com
  • ייצור – mapsbooking.googleapis.com

נקודות קצה

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

  • עדכון – /v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
  • DELETE –‏ /v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete

הפרמטר PARTNER_ID מופיע במרכז הפעולות בדף חשבון ומשתמשים, כפי שמוצג בצילום המסך שבהמשך.

מזהה השותף בפורטל השותפים

אם ניקח את הערך 10000001 כערך של PARTNER_ID כדוגמה מתוך צילום המסך שלמעלה, כתובות ה-URL המלאות לשליחת בקשות API בסביבת Sandbox ובייצור ייראו כמו בדוגמאות הבאות.

עדכון של ארגז החול 

https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush

Sandbox DELETE 

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 בבקשת POST של HTTP. כל בקשת POST חייבת לכלול את הפרמטר 10000001 יחד עם מטען נתונים בפורמט 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 בבקשת POST ב-HTTP. כל בקשת POST חייבת לכלול את הפרמטר PARTNER_ID יחד עם המטען הייעודי (payload) בפורמט 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 לעדכון בזמן אמת:

  • ברמת הבקשה – הבדיקות האלה בודקות שהמטען הייעודי עומד בסכימה ושכל proto_record מכיל את השדות id ו-type. הבדיקות האלה הן סינכרוניות והתוצאות מוצגות בגוף התשובה של ה-API. קוד תגובה 200 וגוף JSON ריק {} משמעותם שהאימותים האלה עברו והישויות שבבקשה הזו הוכנסו לתור לעיבוד. קוד תשובה שאינו 200 מציין שאחד או יותר מהאימותים האלה נכשלו והבקשה כולה נדחית (כולל כל הישויות בתוכן הייעודי). לדוגמה, אם ב-proto_record חסר @type, תוחזר הודעת השגיאה הבאה:
  {
      "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) במטען הייעודי מאומתת בהתאם לסכימה. בעיות שנמצאות בשלב הזה של האימות לא מדווחות בתשובה של ה-API. הן מדווחות רק בלוח הבקרה דיווח על RTU במרכז הפעולות.

הערה: קוד תגובה 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 דקות.

הקודם
מעקב המרות