דף זה תורגם על ידי Cloud Translation API.

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

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

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

הגדרת Google Cloud Platform

מגדירים פרויקט GCP. כדי לקבל גישה ל-RTU API צריך פרויקט GCP.
- אפשר לתת הרשאת עריכה בכתובת food-support@google.com
- עליכם לציין בפני איש הקשר של Google את מספר הפרויקט ב-GCP.כדי שהעדכונים בזמן אמת יפעלו, הפרויקט ב-GCP צריך להיות משויך לחשבון 'מרכז הפעולות' שלכם.
- מפעילים את ממשק ה-API של מפות Google להזמנה:
  - ב-GCP, יש לעבור אל APIs & שירותים > ספרייה.
  - מחפשים את 'Google Maps Booking API' (ממשק ה-API של מפות Google להזמנה).
  - מאתרים את המופע של Sandbox ("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, כמו ה-API של העדכונים בזמן אמת.

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

נכנסים למסוף Google Cloud Platform.
לחשבון שלכם ב-Actions Center משויך גם פרויקט ב-Google Cloud. בוחרים את הפרויקט, אם הוא עדיין לא נבחר.
בתפריט הימני, לוחצים על חשבונות שירות.
לוחצים על Create Service Account.
מזינים שם לחשבון השירות ולוחצים על Create.
בקטע Select a role, בוחרים Project > עריכה.
לוחצים על המשך.
אופציונלי: מוסיפים משתמשים כדי להעניק להם גישה לחשבון השירות ולוחצים על Done (סיום).
לוחצים על עוד > יוצרים מפתח לחשבון השירות שיצרתם.
בוחרים את הפורמט JSON ולוחצים על יצירה.
אחרי שיוצרים את זוג המפתחות הציבוריים/הפרטיים, מורידים אותו למחשב.

עבודה עם ממשק ה-API

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

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

Sandbox – partnerdev-mapsbooking.googleapis.com
הפקה – mapsbooking.googleapis.com

נקודות קצה (endpoints)

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

עדכון – /v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
מחיקה - /v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete

הפרמטר PARTNER_ID נמצא ב-Actions Center בדף חשבון ומשתמשים, כפי שמוצג בצילום המסך בהמשך.

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

עדכון Sandbox

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

מחיקה ב-Sandbox

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

מקש DELETE

https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete

עדכון ישויות

כדי לעדכן ישויות במלאי שטחי הפרסום שלכם, משתמשים בנקודת הקצה עדכון בבקשת HTTP POST. כל בקשת POST חייבת לכלול את הפרמטר 10000001, יחד עם מטען ייעודי (payload) של JSON שמכיל את הישות שרוצים לעדכן.

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

עדכון המטען הייעודי (payload) של הבקשה

גוף הבקשה הוא אובייקט JSON עם רשימה של רשומות. כל רשומה תואמת לישות שמתעדכנת. השדה מורכב מהשדה proto_record ומה-generation_timestamp שמציין את שעת עדכון הישות:

  {
    "records": [
      {
        "proto_record":"ServiceData PROTO",
        "generation_timestamp":"UPDATE_TIMESTAMP"
      }
    ]
  }

ServiceData PROTO: תרגום האב או התרגום ל-JSON של ישות ה-ServiceData שבכוונתך לעדכן.
UPDATE_TIMESTAMP: חשוב לכלול את חותמת הזמן של מועד יצירת הישות במערכות הקצה העורפי. אם השדה הזה לא כלול, הוא יוגדר לשעה שבה Google תקבל את הבקשה. כשמעדכנים ישות באמצעות בקשת batchPush, השדה generation_timestamp משמש לניהול גרסאות של ישויות. לראות את הפורמט הצפוי של ערכי זמן בסכימת המלאי היחסית.

גודלו של גוף המטען הייעודי (Payload) לא יעלה על 5MB.
אפשר להשמיט רווחים לבנים כדי להקטין את הגודל.
בבקשה של batchPush יכולים להיות עד 1,000 עדכונים.

דוגמאות

עדכון זמן הגעה משוער

נניח שצריך לעדכן בדחיפות את זמן ההגעה המשוער לשירות משלוחים מ-30 ל-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, יחד עם המטען הייעודי (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 לעדכון בזמן אמת:

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

מעקב המרות