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

Khoảng không quảng cáo trong hệ thống của bạn biến động trong ngày do có các lượt đặt trước, huỷ và lịch thay đổi mới 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 trong tình trạng sẵn có của khoảng không quảng cáo. Bạn cũng có thể 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 trước hiện có.

Cập nhật và nguồn cấp dữ liệu 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ề những thay đổi dần dần đối với tình trạng còn hàng và lượt đặt trước khoảng không quảng cáo khi chúng 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 về tình trạng còn hàng đầy đủ hằng ngày để đảm bảo Google có được thông tin chính xác và mới nhất về tình trạng còn hàng hiện có trong hệ thống của bạn. Nguồn cấp dữ liệu hoàn chỉnh đóng vai trò như là thông tin tổng quan 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ể sử 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 các thông tin này 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)
Thông báo đặt trước	Bắt buộc	Gửi RTU thông báo đặt phòng bất cứ khi nào có thay đổi với lượt đặt phòng (ví dụ: sửa đổi hoặc hủy).
Tình trạng còn hàng thay thế RTU	Bắt buộc có điều kiện[1]	Gửi các RTU thay thế hàng loạt hoặc thay thế một lần để gửi thông tin cập nhật về tình trạng còn hàng của khoảng không quảng cáo. Nội dung thay đổi có thể mất vài phút để áp dụng và phản ánh.
RTU của người bán	Không bắt buộc	Gửi RTU của người bán nếu bạn muốn thay đổi thông tin của người bán theo thời gian thực. Nội dung thay đổi có thể mất vài giờ mới có hiệu lực và được áp dụng.
RTU dịch vụ	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 đáng kể trong ngày, thì bạn nên triển khai RTU dịch vụ để tránh bị lỗi đơn đặt hàng do thông tin về giá không khớp. Nội dung thay đổi có thể mất vài giờ mới có hiệu lực và được áp dụng.

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

Tính khả dụng thay thế RTU API

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:

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

API thông báo đặt trước RTU

API Thông báo đặt trước thông báo cho Google về các nội dung cập nhật đối với yêu cầu đặt phòng hiện có. Khi bạn gửi thông tin cập nhật về việc huỷ, hãy chỉ gửi thông tin thiết yếu trong yêu cầu bằng thông 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ẻ Credentials (Thông tin xác thực) trong Google API Console để 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 một 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)

Để xem 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 với API Đặt chỗ trên Maps.

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

Bạn nên trực tiếp thực hiện lệnh gọi RESTful tới API Đặt chỗ trên Maps bằng các gói dữ liệu 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 tới API 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à thông 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 qua Ruby, hãy nhấp vào các đường liên kết sau: Ruby API Client và Ruby Auth Library.

Thực hiện lệnh gọi được ủy quyền cho API

Khi bạn thực hiện lệnh gọi đến API, hãy tham khảo nội dung Chuẩn bị thực hiện lệnh gọi API được uỷ quyền để uỷ quyền cho tài khoản dịch vụ bằng khoá riêng tư của bạn 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 1.500 yêu cầu mỗi 60 giây, hoặc trung bình 25 yêu cầu mỗi giây. Khi vượt quá hạn mức (có thể xảy ra khi bạn chưa thêm đúng số dự án trên Google Cloud trong Cổng thông tin dành cho đối tác), 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ý điều này, hãy thử gọi lạ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 duy nhất.

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 thực 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 chúng có các điểm cuối khác nhau.

Phiên bản chính thức: https://mapsbooking.googleapis.com/

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

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

    // 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()