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

תרחישים לדוגמה לשימוש בעדכונים בזמן אמת

חובה לשלוח עדכונים בזמן אמת בתרחישים הבאים:

  • כשמשתמש מבטל הזמנה במערכת שלכם, והמשבצת הופכת לזמינה.
  • כשמשתמש מזמין הזמנה דרך מרכז הפעולות והמשבצת הזמינה כבר לא פנויה.
  • כשמבטלים הזמנה שבוצעה דרך מרכז הפעולות בצד שלכם, למשל על ידי המוכר ישירות. תצטרכו לעדכן את ההזמנה ואת הזמינות, כי המשבצת המקורית זמינה שוב.

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

  • כשמוֹכר משנה את לוח הזמנים (הזמינות) שלו במערכת שלכם.
  • כשמשתמש מזמין הזמנה במערכת שלכם, והמשבצת הזמינה כבר לא פנויה.
  • אם אתם משתמשים בשילוב מדור קודם עם CheckAvailability, כשקריאה לשרת ההזמנות CheckAvailability מחזירה נתוני מלאי שלא תואמים למלאי בפועל.

לא כל הקריאות ל-Maps Booking API הן חובה. המאפיינים הבאים הם חובה:

בהתאם לסוג השילוב, יכול להיות שיהיו זמינים או נדרשים גם הדברים הבאים:

עדכון הרשאה לשימוש ב-Booking

אם בוצע עדכון להזמנה במרכז הפעולות (למשל, ביטול או שינוי) במערכת שלכם, צריך לשלוח notification.partners.bookings.patch (BookingNotification.UpdateBooking).

שדות שניתן לשנות

  • status
  • startTime
  • duration
  • partySize
  • paymentInformation.prepaymentStatus

דוגמה לביטול

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{
  "name": "partners/<PARTNER_ID>/bookings/<BOOKING_ID>",
  "merchantId": "10001",
  "serviceId": "1001",
  "startTime": "2025-01-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

זמינות החלפת RTU

יש שני סוגים של שיטות החלפה שזמינות לעדכון הזמינות שלכם:

  • החלפה של קבוצת נתונים (InventoryUpdate.BatchServiceAvailability): החלפה מלאה של נתוני הזמינות של כמה סוחרים ושירותים.
    • הערה: לא מובטחת אטומיות בקריאה הזו של קבוצת פקודות. יוחזרו רק משבצות זמינות שעודכנו בהצלחה.
  • החלפה יחידה (InventoryUpdate.ReplaceServiceAvailability): החלפה מלאה של הזמינות של מוכר ושירות יחידים.

פרטים נוספים מופיעים במאמר הזה.

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

  • spotsOpen
  • recurrence

בחירת שיטת החלפה לשיחה

המדריך הבא יעזור לכם להחליט איזו שיטת החלפה מתאימה יותר:

  • האם ההשפעה היא על כמה מוכרים? לדוגמה, אפשר להחליף את נתוני הזמינות של כמה מוכרים בבקשה אחת.
  • המערכת תסתנכרן עם Google מדי פעם על ידי שליחת כל השינויים בזמינות מאז העדכון האחרון (לא מומלץ).
    • החלפה של קבוצת פריטים
    • הערה: אנחנו מצפים שהנתונים על מלאי שטחי הפרסום יועברו תוך 5 דקות מרגע שמתרחש עדכון בצד שלכם. לכן, כדאי לבדוק ולשלוח עדכונים לפחות כל 5 דקות.
  • אף אחת מהאפשרויות האלה לא רלוונטית או שצריך לעדכן רק מוֹכר ושירות אחד?
    • החלפה יחידה
    • הערה: אפשר להשתמש בכמה קריאות להחלפה יחידה כדי לדמות קריאה להחלפה של קבוצה, אבל יהיה יעיל יותר להשתמש בקריאה אחת להחלפה של קבוצה

עדכונים בזמן אמת: פורמט של מקומות פנויים

חשוב להשתמש באותו פורמט בכל הפידים, בשרת ההזמנות ובעדכונים בזמן אמת.

קטע קוד של פיד spots_open נראה כך:

קטע מידע על פיד

   "availability": [
          {
            "merchant_id": "1001",
            "service_id": "12310",
            "spots_open": 2,
            "spots_total": 2,
            "start_sec": 1735831800, # January 02, 2025 15:30:00
            "duration_sec": 1800,
            "availabilityTag": "1000001"
          }
    ]

ב-API לעדכון מלאי, זהו פורמט גוף הבקשה להחלפה כשמשבצת בשעה 15:30 מוזמנת:

החלפת קטע הקוד של עדכונים בזמן אמת

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2025-01-02T15:01:23.045123456Z",
        "endTimeRestrict": "2025-01-02T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2025-01-02T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "spotsTotal": "2",
            "availabilityTag": "1000001"
          }
        ]
      }
    ]
  }

דוגמה למה שאנחנו מצפים לראות בפיד היומי הבא, אם משבצת חדשה בשעה 15:30 תוזמן:

קטע מידע על פיד

"availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 2,
          "start_sec": 1735831800, # January 02, 2025 15:30:00
          "duration_sec": 1800,
          "availabilityTag": "1000001"
        }
      ]

עדכונים בזמן אמת: פורמט של חזרה

חשוב להשתמש באותו פורמט בכל הפידים, בשרת ההזמנות ובעדכונים בזמן אמת.

פיד שמוגדר בו חזרה נראה כך:

קטע מידע על פיד

  "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            }
          ],
        }
      ]

ב-Inventory Update API, פורמט גוף הבקשה להחלפה כשמשבצת בשעה 15:30 נסגרת להזמנה נראה כך:

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2018-10-30T15:01:23.045123456Z",
        "endTimeRestrict": "2018-10-30T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2018-10-30T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "scheduleException": [
             {
                "timeRange": {
                  "startTime": "2018-10-30T12:30:00.00Z",
                  "endTime": "2018-10-30T13:00:00.00Z"
                }
              },
              {
                "timeRange": {
                  "startTime": "2018-10-30T15:30:00.00Z",
                  "endTime": "2018-10-30T16:00:00.00Z"
                }
              }
            ]
          }
        ]
      }
    ]
  }

דוגמה למה שצפוי בפיד היומי הבא. שימו לב שזהו נתון הזמינות של כל השירות עבור אותו מוכר, וכל הנתונים הקודמים והחדשים שלו schedule_exceptions:

קטע מידע על פיד

   "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            },
            {
              "time_range": {
                "begin_sec": 1540913400, # October 30, 2018 3:30:00 PM
                "end_sec": 1540915200 # October 30, 2018 4:00:00 PM
              }
            }
          ],
        }
      ]

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

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