Xây dựng cấu trúc cho thông tin cập nhật theo thời gian thực

Trường hợp sử dụng để cập nhật theo thời gian thực

Bạn phải luôn phát hành Nội dung 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 yêu cầu đặt chỗ trên hệ thống của bạn và vị trí đó sẽ xuất hiện.
• Khi người dùng đặt trước một yêu cầu đặt chỗ qua Trung tâm hành động và khung giờ nhận đặt phòng sẽ không còn nữa.
• Khi một giao dịch đặt chỗ được thực hiện qua Trung tâm hành động bị huỷ ở phía bạn, chẳng hạn như do người bán trực tiếp huỷ. Bạn sẽ cần cập nhật yêu cầu đặt vé cũng như tình trạng còn phòng vì vị trí ban đầu hiện đã có thể sử dụng trở lại.

Ngoài ra, nếu triển khai RTU thay thế khả năng cung cấp, bạn nên phát hành bản 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ờ này không còn trống nữa.
• Nếu bạn đang sử dụng chế độ tích hợp cũ với CheckAvailability, thì khi lệnh gọi máy chủ đặt phòng CheckAvailability 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ế.

Một số lệnh gọi API đặt phòng trên Maps đều không bắt buộc. Những mục sau đây là bắt buộc:

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

Tuỳ thuộc vào loại tích hợp, bạn cũng có thể sử dụng hoặc bắt buộc các thông tin sau:

• inventory.partners.availability.replace (InventoryUpdate.BatchServiceAvailability) HOẶC inventory.partners.merchants.services.availability.replace (InventoryUpdate.ReplaceServiceAvailability)

Cập nhật RTU đặt vé

Trong trường hợp cập nhật thông tin đặt chỗ cho Trung tâm hành động (ví dụ: bị 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

Lưu ý: Bạn phải chỉ định name, merchant_id, service_id và trường cụ thể đang thay đổi. Tất cả các trường khác là không bắt buộc. Trong một số trường hợp, nhiều trường có thể thay đổi cùng lúc. Trong trường hợp này, hãy phân tách các trường trong updateMask bằng dấu phẩy (ví dụ: updateMask=partySize,startTime).

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": "2014-10-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

Khả năng sử dụng thay thế RTU

Lưu ý: Khả năng thay thế RTU chỉ có sẵn/bắt buộc cho một số loại hình tích hợp. Nếu bạn không chắc chắn, vui lòng xác nhận với đầu mối liên hệ của Google.

Có 2 loại phương thức thay thế để cập nhật tình trạng hoạt động của bạn:

• Thay thế theo lô (InventoryUpdate.BatchServiceAvailability): Thay thế hoàn toàn dữ liệu về tình trạng còn hàng của một người bán và nhiều dịch vụ.
  • Lưu ý: Lệnh gọi lô này không đảm bảo tính nguyên thức. Chỉ những khung thời gian còn trống đượ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 để biết thêm thông tin chi tiết.

Bản cập nhật theo thời gian thực phải sử dụng cùng một cấu trúc có sẵn như dữ liệu gửi qua nguồn cấp dữ liệu. Phải sử dụng một trong:

• spotsOpen
• recurrence

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

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

• Nhiều dịch vụ có bị ảnh hưởng chỉ trong một lượt đặt trước không? Ví dụ: cắt và nhuộm tóc (mỗi dịch vụ là một Dịch vụ riêng biệt) được đặt trước với một nhà tạo mẫu, vì vậy, bạn nên xoá mọi dịch vụ liên kết với nhà tạo mẫu đó trong khung giờ đó.
  • Thay thế hàng loạt
• Tuỳ từng thời điểm, hệ thống của bạn sẽ đồng bộ hoá với Google bằng cách gửi tất cả thay đổi về tình trạng rảnh/bận kể từ lần cập nhật gần nhất (không nên).
  • Thay thế hàng loạt
  • Lưu ý: Chúng tôi dự kiến sẽ gửi RTU khoảng không quảng cáo trong vòng 5 phút kể từ khi quá trình cập nhật diễn ra ở phía bạn. Vì vậy, bạn nên kiểm tra và gửi thông tin cập nhật ít nhất 5 phút một lần.
• Không có lựa chọn nào phù hợp?
  • Thay thế một lần
  • Lưu ý: Bạn có thể sử dụng nhiều lệnh gọi thay thế hàng loạt để 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 bạn sử dụng một lệnh gọi thay thế hàng loạt duy nhất

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

Bạn phải sử dụng cùng một định dạng cho 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 sẽ có dạng như sau:

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

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

Đối với API Cập nhật khoảng không quảng cáo, định dạng nội dung yêu cầu thay thế cho thời điểm đặt trước một khung giờ 3:30 chiều:

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

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

Sau đây là ví dụ về dự kiến trong nguồn cấp dữ liệu hằng ngày tiếp theo, nếu có người đặt một khung giờ mới lúc 3:30 chiều:

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

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

Lưu ý: Trong trường hợp không còn tình trạng còn hàng (spots_open bằng 0), bạn có thể gửi yêu cầu thay thế cho API Kho hàng.

• Thông số kỹ thuật rõ ràng: Đây là phương thức nên dùng nếu bạn có spots_total > 1

    {
      "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": "0",
              "spotsTotal": "2",
              "availabilityTag": "1000001"
            }
          ]
        }
      ]
    }
  

• Thông số kỹ thuật trống: Bạn chỉ nên sử dụng thuộc tính này nếu spots_total = 1 đối với hầu hết người bán và dịch vụ.

    {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
        "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
        "availability": [
          {}
        ]
      }
    ]
  }
  

Cập nhật theo thời gian thực: Định dạng lặp lại

Bạn phải sử dụng cùng một định dạng cho 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.

Một nguồn cấp dữ liệu sử dụng tính năng lặp lại sẽ có dạng như sau:

Đoạn trích 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 API Cập nhật khoảng không quảng cáo, định dạng nội dung yêu cầu thay thế cho thời điểm 3:30 chiều được đặt trước, 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"
                }
              }
            ]
          }
        ]
      }
    ]
  }

Lưu ý: Thông tin cập nhật theo thời gian thực phải chứa tất cả schedule_exceptions của các khung giờ đã đặt trước. Lý do là vì phương thức API thay thế khả năng sử dụng của dịch vụ và người bán cụ thể đó. Nếu bạn định thay thế dịch vụ đó bằng một dịch vụ khác, thì đó phải là thông tin đầy đủ về tình trạng cung cấp của dịch vụ đó và bao gồm tất cả khoảng trống đã đặt trước.

Sau đây là ví dụ về những thông tin có thể xảy ra 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ộ khả năng cung cấp dịch vụ đối với người bán đó, cũng như mọi schedule_exceptions trước đó và mới của dịch vụ:

Đoạn trích 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 nên gửi thông tin cập nhật theo thời gian thực

Thông tin cập nhật theo thời gian thực sẽ được gửi liên tục bất cứ khi nào tình trạng rảnh/bận thay đổi. Ngoài ra, bạn phải gửi nguồn cấp dữ liệu tình trạng còn hàng toàn diện 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à Google.