Bước 5: Cập nhật 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 suốt cả ngày do có các lượt đặt trước mới, việc huỷ và lên lịch thay đổi thông tin từ người bán. Thông tin cập nhật theo thời gian thực API là một cơ chế để thông báo cho Google về những thay đổi này trong kho hàng tình trạng còn hàng. Bạn cũng có thể sử dụng các bản cập nhật API theo thời gian thực để thông báo cho Google về các thay đổi được thực hiện đối với các lượt đặt phòng hiện có.

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

Các bản 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à số lượt đặt trước khoảng không quảng cáo khi chúng diễn ra theo thời gian thực. Ngoài ra cập nhật API theo thời gian thực, gửi nguồn cấp dữ liệu Tình trạng còn hàng hoàn chỉnh 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 mã đó có trong hệ thống của bạn. Nguồn cấp dữ liệu hoàn chỉnh đóng vai trò như một ảnh chụp nhanh của trạng thái của tính sẵn có của khoảng không quảng cáo trong hệ thống của bạn.

Mặc dù bạn có thể dùng bản 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ụ, 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 thông báo đặt chỗ bất cứ lúc nào thay đổi đối với lượt đặt phòng (ví dụ: sửa đổi hoặc huỷ).
Tình trạng sẵn hàng thay thế RTU Bắt buộc có điều kiện[1] Gửi một trong hai thay thế hàng loạt hoặc RTU 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 hàng. Có thể mất vài phút để các thay đổi có hiệu lực và hiệu lực.
RTU của người bán Không bắt buộc Gửi RTU cho người bán nếu bạn muốn thay đổi thông tin người bán thông tin theo thời gian thực. Có thể mất vài giờ để các thay đổi có hiệu lực và suy ngẫm.
RTU dịch vụ Không bắt buộc Gửi RTU dịch vụ nếu bạn muốn thay đổi dịch vụ thông tin 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, việc triển khai RTU Dịch vụ để tránh xảy ra lỗi đơn đặt hàng do giá không khớp. Thay đổi có thể mất vài giờ để tuyên truyền và suy ngẫm.

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

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

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

API thông báo đặt trước sẽ thông báo cho Google về thông tin cập nhật cho các lượt đặt trước hiện có. Khi bạn 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 cùng với 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 vào API

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

Sử dụng thẻ Thông tin đăng nhập trong Bảng điều khiển API của Google để tạo một tài khoản dịch vụ. Lưu trữ khoá riêng tư ở định dạng JSON một cách an toàn địa điểm. Khi tạo tài khoản, bạn có tùy chọn đặ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 về Cách xác thực bằng API Đặt chỗ trên 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 chỗ của Maps với 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 này.

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.

Thông tin khác thư viện hỗ trợ có sẵn để tải 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 các API của Google. Nếu cần, xem thử 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, trong đó mô tả các phương thức và tham số.

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 RubyThư 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 Chuẩn bị thực hiện lệnh gọi API được uỷ quyền để cấp quyền cho dịch vụ của bạn tài khoản với khoá riêng tư của bạn 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 1.500 yêu cầu mỗi 60 giây hoặc 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 sau đây là thông báo lỗi:

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

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

Hộp cát và thiết bị đầu cuối chính thức

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. 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 phát hành công khai: https://mapsbooking.googleapis.com/

Điểm cuối 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()