Thông tin cập nhật theo thời gian thực về API

Khoảng không quảng cáo trong hệ thống của bạn biến động trong suốt cả ngày do các yêu cầu đặt phòng mới, lượt huỷ và thay đổi lịch biểu của người bán. API cập nhật theo thời gian thực là một cơ chế để thông báo cho Google về những thay đổi này về tình trạng còn hàng. Bạn cũng có thể sử dụng tính năng cập nhật API theo thời gian thực để thông báo cho Google về những thay đổi đối với các lượt đặt phòng hiện có.

Bạn không cần cập nhật theo thời gian thực nếu tất cả người bán của bạn đều sử dụng tính năng danh sách chờ.

Nguồn cấp dữ liệu và thông tin cập nhật theo thời gian thực của API

Thông tin cập nhật theo thời gian thực của API được dùng để thông báo cho Google về các thay đổi gia tăng đối với tình trạng còn hàng và lượt đặt phòng khi các thay đổi đó xảy ra theo thời gian thực. Ngoài các bản cập nhật API theo thời gian thực, hãy gửi nguồn cấp dữ liệu Tình trạng còn hàng đầy đủ hằng ngày để đảm bảo rằng Google có thông tin chính xác và mới nhất về tình trạng còn hàng trong hệ thống của bạn. Nguồn cấp dữ liệu đầy đủ đóng vai trò là ảnh chụp nhanh về trạng thái hiện tại của tình trạng còn hàng trong hệ thống của bạn.

Mặc dù bạn có thể dùng nội dung cập nhật API để cập nhật mọi thông tin do nguồn cấp dữ liệu cung cấp, chẳng hạn như thông tin về người bán và dịch vụ, nhưng thông tin cập nhật API thường chỉ được dùng để cập nhật thông tin về tình trạng còn hàng.

API cập nhật theo thời gian thực bắt buộc

API cập nhật theo thời gian thực (RTU)
BookingNotification	Bắt buộc	Gửi RTU BookingNotification bất cứ khi nào có thay đổi đối với yêu cầu đặt phòng (ví dụ: sửa đổi hoặc huỷ).
Tình trạng còn hàng Thay thế RTU	Bắt buộc trong một số điều kiện[1]	Gửi RTU thay thế hàng loạt hoặc thay thế đơn lẻ để gửi thông tin cập nhật về tình trạng còn hàng. Có thể mất vài phút để các thay đổi có hiệu lực.
RTU của người bán	Không bắt buộc	Gửi yêu cầu thay đổi thông tin người bán nếu bạn muốn thay đổi thông tin người bán theo thời gian thực. Có thể mất vài giờ để các thay đổi được áp dụng và phản ánh.
Dịch vụ RTU	Không bắt buộc	Gửi RTU dịch vụ nếu bạn muốn thay đổi thông tin dịch vụ theo thời gian thực. Một trường hợp sử dụng phổ biến là nếu giá dịch vụ biến động mạnh trong ngày, bạn nên triển khai RTU dịch vụ để tránh trường hợp đơn đặt hàng không thành công do giá không khớp. Có thể mất vài giờ để các thay đổi được áp dụng và phản ánh.

Lưu ý: Yêu cầu đối với điểm cuối này thay đổi dựa trên cách tích hợp của bạn. Vui lòng liên hệ với người liên hệ của bạn tại Google để xác định xem bạn cần có những điểm cuối nào.

Khả năng thay thế API RTU

Sử dụng API Thay thế tình trạng còn hàng để cung cấp thông tin cập nhật về tình trạng còn hàng trong các trường hợp sử dụng sau:

• Một người dùng đặt chỗ trên hệ thống của bạn, vì vậy, khung giờ trống đó không còn nữa.
• Người bán thay đổi tình trạng còn hàng trong hệ thống của bạn.
• Một người dùng đặt chỗ thông qua Google, vì vậy, khung giờ trống đó không còn nữa.
• Lượt đặt trước được thực hiện thông qua Google bị huỷ ở phía bạn, ví dụ: do người bán trực tiếp huỷ. Bạn cần cập nhật yêu cầu đặt chỗ cũng như tình trạng còn chỗ vì giờ ban đầu hiện đã có chỗ trống trở lại.
• Lệnh gọi BatchAvailabilityLookup 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ế.

Để biết thêm thông tin, hãy tham khảo các tài nguyên sau:

• Hướng dẫn: cách sắp xếp thông tin cập nhật theo thời gian thực
• Ví dụ về ứng dụng Java để cập nhật theo thời gian thực bằng các lệnh gọi RESTful
• Trang tham khảo API cập nhật khoảng không quảng cáo

Booking Notification API RTU

API Thông báo đặt phòng sẽ thông báo cho Google về các nội dung cập nhật đối với các lượt đặt phòng hiện có. Khi gửi thông tin cập nhật về việc huỷ, chỉ gửi thông tin cần thiết trong yêu cầu bằng tham số truy vấn updateMask. Dưới đây là ví dụ:

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

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"CANCELED"}

Truy cập API

Tạo một tài khoản dịch vụ

Sử dụng thẻ Thông tin xác thực trong Bảng điều khiển API của Google để tạo tài khoản dịch vụ. Lưu trữ khoá riêng tư ở định dạng JSON ở một nơi an toàn. Khi tạo tài khoản, bạn có thể đặt vai trò thành "Chủ sở hữu".

Xác thực API Đặt chỗ trên Maps

Sau khi tạo tài khoản dịch vụ, hãy xác thực các API sau:

• API Đặt chỗ trên Google Maps
• API Đặt chỗ trên Google Maps (Nhà phát triển)

Để biết hướng dẫn từng bước về cách thực hiện việc này, hãy tham khảo hướng dẫn Xác thực bằng Maps Booking API.

Sử dụng lệnh gọi RESTful hoặc tải thư viện ứng dụng xuống

Bạn nên thực hiện lệnh gọi RESTful trực tiếp đến API Đặt chỗ trên Maps bằng tải trọng JSON. Để biết thêm thông tin, hãy xem tài liệu về API REST.

Bạn cũng có thể sử dụng thư viện ứng dụng để kết nối với API.

Ngôn ngữ	Đường liên kết để tải xuống
Java	Thư viện ứng dụng Java. Để biết thêm thông tin, hãy xem hướng dẫn về ứng dụng Java.

Bạn có thể tải thêm thư viện hỗ trợ xuống để xử lý việc uỷ quyền và các khía cạnh khác của lệnh gọi đến API của Google. Nếu cần, hãy xem các mẫu này.

Tìm nạp tài liệu Khám phá

Đối với một số thư viện ứng dụng, chẳng hạn như Ruby, bạn cần tìm nạp tài liệu Khám phá cho API. Tài liệu này mô tả các phương thức và tham số của API.

Sử dụng lệnh sau để tìm nạp tài liệu Khám phá:

curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'

Để biết thêm thông tin về cách truy cập API từ Ruby, hãy truy cập vào các đường liên kết sau: Ứng dụng API Ruby và Thư viện xác thực Ruby.

Thực hiện lệnh gọi được uỷ quyền đến API

Khi bạn thực hiện lệnh gọi đến API, hãy tham khảo phần Chuẩn bị thực hiện lệnh gọi API được uỷ quyền để uỷ quyền tài khoản dịch vụ bằng khoá riêng tư và phạm vi OAuth sau: https://www.googleapis.com/auth/mapsbooking.

Hạn mức API

Các bản cập nhật API có hạn mức là 1.500 yêu cầu mỗi 60 giây, tức là trung bình 25 yêu cầu mỗi giây. Khi bạn vượt quá hạn mức (điều này có thể xảy ra khi bạn chưa thêm đúng Số dự án trên Google Cloud trong Partner Portal), Google sẽ phản hồi bằng thông báo lỗi sau:

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

Để xử lý vấn đề này, hãy thử lại lệnh gọi ở khoảng thời gian lớn hơn theo cấp số nhân cho đến khi thành công. Nếu bạn thường xuyên sử dụng hết hạn mức với ReplaceServiceAvailability, hãy chuyển sang BatchReplaceServiceAvailabily để giảm số lượng lệnh gọi API. Phương thức này cho phép bạn cập nhật nhiều dịch vụ trong một lệnh gọi API.

Hộp cát và điểm cuối sản xuất

Bạn có thể thực hiện lệnh gọi đến cả môi trường hộp cát và môi trường sản xuất thông qua API. Hãy nhớ bật cả hai API trong dự án Google Cloud. Cả hai API này đều sử dụng cùng một phạm vi, nhưng có các điểm cuối khác nhau.

Điểm cuối chính thức: https://mapsbooking.googleapis.com/

Điểm cuối của hộp cát: https://partnerdev-mapsbooking.googleapis.com/

Sau đây là ví dụ về cách chuyển đổi điểm cuối trong Java:

    // This block of code is for OAuth and is the same for prod and sandbox.
    GoogleCredential
      .fromStream(new FileInputStream(...))
      .createScoped(Collections.singleton("https://www.googleapis.com/auth/mapsbooking"))

    // This block of code sets the endpoint. This is what you'd change to connect to the sandbox.
    new GoogleMapsBookingAPI.Builder(...)
      .setApplicationName(...)
      .setRootUrl("https://partnerdev-mapsbooking.googleapis.com/") // you add this to change the endpoint to use partnerdev.
      .build()