Cấu trúc nội dung cập nhật theo thời gian thực

Các trường hợp sử dụng thông tin cập nhật theo thời gian thực

Bạn phải luôn đưa ra thông tin cập nhật theo thời gian thực trong các trường hợp sau:

  • Khi người dùng huỷ một lượt đặt chỗ trên hệ thống của bạn và khung giờ đó trở thành khung giờ trống.
  • Khi người dùng đặt chỗ qua Trung tâm hành động và khung giờ còn trống không còn nữa.
  • Khi một lượt đặt phòng được thực hiện thông qua Trung tâm hành động bị huỷ ở phía bạn, ví dụ: do người bán huỷ trực tiếp. Bạn cũng cần phải cập nhật thông tin đặt chỗ cũng như tình trạng còn chỗ vì giờ hẹn ban đầu hiện đã có thể đặt lại.

Ngoài ra, nếu bạn triển khai Availability Replace RTU, thì bạn phải phát hành Thông tin cập nhật theo thời gian thực trong các trường hợp sau:

  • Khi người bán thay đổi lịch biểu (tình trạng còn hàng) trên hệ thống của bạn.
  • Khi người dùng đặt chỗ trên hệ thống của bạn và khung giờ còn trống không còn nữa.
  • Nếu bạn đang sử dụng chế độ tích hợp cũ với CheckAvailability, khi lệnh gọi CheckAvailability của máy chủ đặt phòng trả về khoảng không quảng cáo không khớp với khoảng không quảng cáo thực tế.

Không phải tất cả lệnh gọi Maps Booking API đều là bắt buộc. Bạn bắt buộc phải cung cấp những thông tin sau:

Tuỳ thuộc vào loại tích hợp, bạn cũng có thể cần hoặc phải có những thông tin sau:

Cập nhật RTU đặt phòng

Trong trường hợp bạn đã cập nhật một yêu cầu đặt phòng trên Actions Center (ví dụ: đã huỷ hoặc sửa đổi) trên hệ thống của mình, bạn phải gửi notification.partners.bookings.patch (BookingNotification.UpdateBooking).

Các trường có thể sửa đổi

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

Ví dụ về việc huỷ

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

Thay thế RTU khi có hàng

Có 2 loại phương thức thay thế để cập nhật tình trạng còn hàng:

  • Thay thế hàng loạt (InventoryUpdate.BatchServiceAvailability): Thay thế hoàn toàn dữ liệu về tình trạng còn hàng của nhiều người bán và dịch vụ.
    • Lưu ý: Lệnh gọi hàng loạt này không đảm bảo tính nguyên tử. Chỉ những khung giờ có thể đặt lịch hẹn đã được cập nhật thành công mới được trả về.
  • Thay thế một lần (InventoryUpdate.ReplaceServiceAvailability): Thay thế hoàn toàn tình trạng còn hàng của một người bán và dịch vụ.

Vui lòng sử dụng tài liệu tham khảo sau đây để biết thêm thông tin chi tiết.

Thông tin cập nhật theo thời gian thực phải sử dụng cùng một cấu trúc tình trạng còn hàng như dữ liệu được gửi qua nguồn cấp dữ liệu. Họ phải sử dụng một trong những cách sau:

  • spotsOpen
  • recurrence

Chọn phương thức thay thế để gọi

Hãy tham khảo hướng dẫn sau để xác định phương thức thay thế nào phù hợp hơn:

  • Có nhiều người bán chịu ảnh hưởng không? Ví dụ: thay thế tình trạng còn hàng của nhiều người bán trong một yêu cầu.
  • Hệ thống của bạn sẽ đồng bộ hoá với Google theo định kỳ bằng cách gửi tất cả các thay đổi về tình trạng còn phòng kể từ lần cập nhật gần nhất (không nên dùng).
    • Thay thế hàng loạt
    • Lưu ý: Chúng tôi dự kiến bạn sẽ gửi RTU về khoảng không quảng cáo trong vòng 5 phút kể từ khi có thông tin cập nhật về phía bạn. Vì vậy, bạn nên kiểm tra và gửi mọi thông tin cập nhật ít nhất 5 phút một lần.
  • Không có trường hợp nào trong số này áp dụng hoặc bạn chỉ cần cập nhật một người bán và dịch vụ?
    • Thay thế một lần
    • Lưu ý: Bạn có thể sử dụng nhiều lệnh gọi thay thế đơn lẻ để mô phỏng một lệnh gọi thay thế hàng loạt, nhưng sẽ hiệu quả hơn nếu sử dụng một lệnh gọi thay thế hàng loạt

Thông tin cập nhật theo thời gian thực: Định dạng mở của Spots

Bạn cần sử dụng cùng một định dạng trên các nguồn cấp dữ liệu, máy chủ đặt phòng và thông tin cập nhật theo thời gian thực.

Đoạn mã nguồn cấp dữ liệu spots_open có dạng như sau:

Đoạn trích từ nguồn cấp dữ liệu

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

Đối với Inventory Update API, định dạng nội dung yêu cầu thay thế khi một khung giờ 15:30 được đặt:

Thay thế đoạn mã thông tin cập nhật theo thời gian thực

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

Dưới đây là ví dụ về những gì chúng tôi dự kiến sẽ thấy trong nguồn cấp dữ liệu hằng ngày tiếp theo, nếu có một khung giờ mới lúc 15:30 được đặt:

Đoạn trích từ nguồn cấp dữ liệu

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

Thông tin cập nhật theo thời gian thực: Định dạng định kỳ

Bạn cần sử dụng cùng một định dạng trên các nguồn cấp dữ liệu, máy chủ đặt phòng và thông tin cập nhật theo thời gian thực.

Nguồn cấp dữ liệu sử dụng tần suất định kỳ sẽ có dạng như sau:

Đoạn trích từ nguồn cấp dữ liệu

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

Đối với Inventory Update API, định dạng nội dung yêu cầu thay thế khi một khung giờ 15:30 được đặt sẽ có dạng như sau:

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

Sau đây là ví dụ về nội dung dự kiến trong nguồn cấp dữ liệu hằng ngày tiếp theo. Xin lưu ý rằng đây là toàn bộ phạm vi cung cấp dịch vụ của người bán đó, cũng như tất cả schedule_exceptions trước đây và hiện tại của người bán đó:

Đoạn trích từ nguồn cấp dữ liệu

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

Thời điểm gửi thông tin cập nhật theo thời gian thực

Bạn nên liên tục gửi thông tin cập nhật theo thời gian thực mỗi khi tình trạng phòng thay đổi. Ngoài ra, bạn phải gửi một nguồn cấp dữ liệu toàn diện về tình trạng còn hàng mỗi ngày một lần để đảm bảo rằng tình trạng còn hàng được đồng bộ hoá giữa hệ thống của bạn và hệ thống của Google.