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

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

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

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

הגדרת Google Cloud Platform

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

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

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

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

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

עבודה עם ה-API

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

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

ארגז חול – partnerdev-mapsbooking.googleapis.com
הפקה – mapsbooking.googleapis.com

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

ה-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 ובסביבת הייצור ייראו כמו בדוגמאות הבאות.

עדכון לגבי Sandbox

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

מחיקה 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: תרגום פרוטו או JSON של ישות ServiceData שמעדכנים.
UPDATE_TIMESTAMP: הקפידו לכלול את חותמת הזמן של מועד היצירה של הישות במערכות הקצה העורפי שלכם. אם השדה הזה לא כלול, הוא יוגדר לשעה שבה Google תקבל את הבקשה. כשמעדכנים ישות באמצעות בקשת batchPush, השדה generation_timestamp משמש לניהול גרסאות של ישויות. מחפשים את הפורמט הצפוי של ערכי זמן בסכימת המלאי היחסי.

גודל הגוף של המטען הייעודי לא יכול לחרוג מ-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 עם המטען הייעודי (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 דקות.

מעקב המרות