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

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

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

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

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

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

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

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

עדכון Booking RTU

אם בוצע עדכון בהזמנה ב-Actions Center (למשל, ביטול או שינוי) במערכת שלכם, עליכם לשלוח 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": "2014-10-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

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

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

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

למידע נוסף, אפשר לעיין במאמר הזה.

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

  • spotsOpen
  • recurrence

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

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

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

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

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

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

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

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

ב-Inventory Update API, הפורמט של גוף הבקשה להחלפה כשמזמינים זמן פרסום בשעה 15:30:

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

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
        "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2014-10-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": 1412263800, # October 02, 2014 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.