ساختار به روز رسانی های زمان واقعی

موارد استفاده برای به‌روزرسانی‌های بلادرنگ

به‌روزرسانی‌های بلادرنگ (Real-Time Updates) همیشه باید در سناریوهای زیر صادر شوند:

• وقتی کاربری رزرو خود را در سیستم شما لغو می‌کند و آن جایگاه خالی می‌شود.
• وقتی کاربری از طریق مرکز عملیات رزرو انجام می‌دهد و دیگر آن بازه زمانی در دسترس نیست.
• وقتی رزروی که از طریق مرکز عملیات انجام شده است، مثلاً مستقیماً توسط فروشنده لغو می‌شود، باید رزرو و همچنین موجودی را به‌روزرسانی کنید زیرا جایگاه اصلی اکنون دوباره در دسترس است.

علاوه بر این، اگر Availability Replace RTU را پیاده‌سازی کنید، به‌روزرسانی‌های بلادرنگ باید در سناریوهای زیر صادر شوند:

• وقتی یک فروشنده برنامه (در دسترس بودن) خود را در سیستم شما تغییر می‌دهد.
• وقتی کاربری در سیستم شما رزروی انجام می‌دهد و دیگر آن بازه زمانی خالی نیست.
• اگر از یکپارچه‌سازی قدیمی با CheckAvailability استفاده می‌کنید، وقتی فراخوانی CheckAvailability سرور رزرو، موجودی را برمی‌گرداند که با موجودی واقعی مطابقت ندارد.

همه فراخوانی‌های API رزرو نقشه‌ها الزامی نیستند. موارد زیر اجباری هستند:

• notification.partners.bookings.patch ( BookingNotification.UpdateBooking )

بسته به نوع ادغام، موارد زیر نیز ممکن است در دسترس یا مورد نیاز باشند:

• inventory.partners.availability.replace ( InventoryUpdate.BatchServiceAvailability ) یا inventory.partners.merchants.services.availability.replace ( InventoryUpdate.ReplaceServiceAvailability )

به‌روزرسانی رزرو 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": "2025-01-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

جایگزینی RTU در دسترس بودن

دو نوع روش جایگزینی برای به‌روزرسانی در دسترس بودن شما وجود دارد:

• جایگزینی دسته‌ای ( InventoryUpdate.BatchServiceAvailability ): داده‌های در دسترس بودن را برای چندین فروشنده و سرویس به طور کامل جایگزین می‌کند.
  • توجه: این فراخوانی دسته‌ای، اتمی بودن را تضمین نمی‌کند. فقط اسلات‌های در دسترس با موفقیت به‌روزرسانی شده، بازگردانده می‌شوند.
• جایگزینی واحد ( InventoryUpdate.ReplaceServiceAvailability ): به طور کامل جایگزین موجودی برای یک فروشنده و سرویس می‌شود.

برای جزئیات بیشتر لطفا از مرجع زیر استفاده کنید.

به‌روزرسانی‌های بلادرنگ باید از همان ساختار دسترسی‌پذیری داده‌هایی که از طریق فیدها ارسال می‌شوند، استفاده کنند. آن‌ها باید از یکی از موارد زیر استفاده کنند:

• spotsOpen
• recurrence

انتخاب یک متد Replace برای فراخوانی

از راهنمای زیر برای تعیین اینکه کدام روش جایگزینی مناسب‌تر است، استفاده کنید:

• آیا چندین فروشنده تحت تأثیر قرار گرفته‌اند؟ برای مثال، در یک درخواست، در دسترس بودن برای چندین فروشنده را جایگزین کنید.
  • جایگزینی دسته‌ای
• سیستم شما هر از گاهی با ارسال تمام تغییرات در دسترس بودن از آخرین به‌روزرسانی، با گوگل همگام‌سازی می‌شود (توصیه نمی‌شود).
  • جایگزینی دسته‌ای
  • توجه: ما انتظار داریم که RTU موجودی ظرف ۵ دقیقه پس از به‌روزرسانی از طرف شما ارسال شود. بنابراین شما باید حداقل هر ۵ دقیقه یکبار به‌روزرسانی‌ها را بررسی و ارسال کنید.
• هیچ کدام از این موارد صدق نمی‌کند یا فقط باید یک فروشنده و سرویس را به‌روزرسانی کنید؟
  • جایگزینی تکی
  • نکته: می‌توانید از چندین فراخوانی جایگزینی تکی برای شبیه‌سازی فراخوانی جایگزینی دسته‌ای استفاده کنید، اما استفاده از یک فراخوانی جایگزینی دسته‌ای واحد کارآمدتر خواهد بود.

به‌روزرسانی‌های بلادرنگ: قالب باز Spots

استفاده از فرمت یکسان در فیدها، سرور رزرو و به‌روزرسانی‌های بلادرنگ بسیار مهم است.

یک قطعه کد فید 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 به‌روزرسانی موجودی، قالب بدنه درخواست جایگزینی برای زمانی که یک بازه زمانی ساعت ۳:۳۰ بعد از ظهر رزرو می‌شود:

جایگزینی قطعه کد به‌روزرسانی‌های بلادرنگ

  {
    "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"
          }
        ]
      }
    ]
  }

در اینجا مثالی از آنچه در فید روزانه بعدی انتظار داریم، در صورت رزرو شدن یک جایگاه جدید در ساعت ۳:۳۰ بعد از ظهر، آورده شده است:

قطعه کد فید

"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
              }
            }
          ],
        }
      ]

برای API به‌روزرسانی موجودی، قالب بدنه درخواست جایگزینی برای زمانی که یک بازه زمانی ساعت ۳:۳۰ بعد از ظهر رزرو می‌شود، به شکل زیر است:

  {
    "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
              }
            }
          ],
        }
      ]

چه زمانی به‌روزرسانی‌های بلادرنگ را ارسال کنیم؟

به‌روزرسانی‌های بلادرنگ باید به‌طور مداوم و در هر زمان که وضعیت دسترسی تغییر می‌کند، ارسال شوند. این علاوه بر یک فید جامع در مورد وضعیت دسترسی است که باید روزی یک‌بار ارسال شود تا از همگام‌سازی وضعیت دسترسی بین سیستم‌های شما و گوگل اطمینان حاصل شود.