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ó thêm các lượt đặt trước mới, yêu cầu huỷ và thay đổi về lịch biểu từ 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 đối với tình trạng còn hàng của khoảng không quảng cáo. 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ờ.

Cập nhật và cấp dữ liệu API theo thời gian thực

Tính năng cập nhật API theo thời gian thực được dùng để thông báo cho Google về những thay đổi gia tăng đối với tình trạng còn hàng và lượt đặt trước của kho hàng khi những thay đổi này xảy ra theo thời gian thực. Ngoài việc 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 hoàn chỉnh hằng ngày để đảm bảo rằng Google có được thông tin chính xác nhất 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 hoàn chỉnh đóng vai trò là thông tin tổng quan nhanh về tình trạng còn hàng hiện tại của kho hàng trong hệ thống của bạn.

Mặc dù bản cập nhật API có thể dùng để cập nhật bất kỳ thông tin nào 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 bản cập nhật 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 bắt buộc theo thời gian thực

API cập nhật theo thời gian thực (RTU)
BookingNotification	Bắt buộc	Gửi RTU của thông báo đặt phòng bất cứ khi nào có thay đổi về việc đặt phòng (ví dụ: sửa đổi hoặc huỷ).
Khả năng sử dụng thay thế RTU	Bắt buộc có điều kiện[1]	Gửi 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. Các thay đổi có thể mất vài phút để có hiệu lực và áp dụng.
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 người bán theo thời gian thực. Các thay đổi có thể mất vài giờ để có hiệu lực và bắt đầu có hiệu lực.
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 mạnh trong ngày, bạn nên triển khai RTU dịch vụ để tránh lỗi đơn đặt hàng do giá không khớp. Có thể mất vài giờ để các thay đổ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 người liên hệ của Google để xác định xem cần có điểm cuối nào.

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

Sử dụng API thay thế cho tình trạng còn hàng để cập nhật 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ờ này không còn trống 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 nên tình trạng còn hàng không còn nữa.
• Một giao dịch đặt trước thực hiện qua Google sẽ bị huỷ ở phía bạn, chẳng hạn như do người bán trực tiếp huỷ. Bạn cần cập nhật thông tin đặt vé cũng như tình trạng còn phòng, vì khung giờ ban đầu đã có thể sử dụng trở 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 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 xây dựng cấu trúc cho 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 tài liệu tham khảo API cập nhật kho hàng

RTU API thông báo đặt phòng

Đặt phòng API sẽ thông báo cho Google về nội dung cập nhật đối với các lượt đặt phòng hiện có. Khi bạn gửi thông tin cập nhật về các lượt huỷ, bạn chỉ cần gửi thông tin thiết yếu 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ụ

Hãy 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 phòng 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 phòng của 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 bằng API đặt phòng của Maps.

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 phòng của 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 dành cho ứng dụng Java.

Bạn có thể tải thêm các thư viện hỗ trợ xuống để xử lý việc uỷ quyền cũng như các khía cạnh khác của lệnh gọi đến các 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 qua Ruby, hãy truy cập các đường liên kết sau: Ứng dụng API Ruby và Thư viện xác thực của 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 để cấp quyền cho tài khoản dịch vụ của bạn bằng khoá riêng tư và phạm vi OAuth sau đây: 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 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 Google Cloud vào Cổng đố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ý việc này, hãy thử gọi lại với những 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.

Thiết bị đầu cuối chính thức và hộp cá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 đảm bảo rằng bạn đã bật cả hai API trong dự án Google Cloud của mình. 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 sản xuất: https://mapsbooking.googleapis.com/

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

Sau đây là một 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()