Bạn cần thiết lập một máy chủ đặt phòng để cho phép Trung tâm hành động thực hiện lệnh gọi lại nhằm thay mặt bạn tạo và cập nhật các yêu cầu đặt phòng.
- Phương thức triển khai Chuẩn. Điều này cho phép Trung tâm hành động thay mặt người dùng tạo cuộc hẹn, đặt chỗ và đặt trước với bạn.
Hãy tham khảo tài liệu về Partner Portal để tìm hiểu cách định cấu hình kết nối với hộp cát và máy chủ đặt phòng chính thức.
Triển khai giao diện API REST
Triển khai giao diện API dựa trên REST. Điều này cho phép Google gửi yêu cầu máy chủ đặt phòng qua HTTP.
Để bắt đầu, hãy thiết lập một máy chủ đặt phòng phát triển hoặc hộp cát có thể kết nối với môi trường hộp cát của Trung tâm hành động. Chỉ chuyển sang môi trường phát hành công khai sau khi kiểm thử đầy đủ máy chủ hộp cát.
Phương thức
Đối với mỗi loại máy chủ đặt phòng, bạn cần có một bộ phương thức API khác nhau. Bạn có thể tải định nghĩa dịch vụ xuống ở định dạng proto để bắt đầu triển khai API (không bắt buộc). Các bảng sau đây cho thấy các phương thức triển khai và bao gồm các đường liên kết đến định dạng proto của dịch vụ.
| Triển khai chuẩn |
|---|
| Định nghĩa dịch vụ chuẩn Tải tệp định nghĩa dịch vụ proto xuống. |
| Phương thức | Yêu cầu HTTP |
|---|---|
| HealthCheck | GET /v3/HealthCheck/ |
| BatchAvailabilityLookup | POST /v3/BatchAvailabilityLookup/ |
| CreateBooking | POST /v3/CreateBooking/ |
| UpdateBooking | POST /v3/UpdateBooking/ |
| GetBookingStatus | POST /v3/GetBookingStatus/ |
| ListBookings | POST /v3/ListBookings/ |
Tài nguyên API
Đặt dịch vụ
Các loại tài nguyên sau đây được dùng trong quá trình triển khai tiêu chuẩn:
- Khe: Một khe khoảng không quảng cáo.
- Lượt đặt phòng: Lượt đặt lịch hẹn cho một khung giờ nhận đặt phòng.
Quy trình: tạo lượt đặt trước
Phần này trình bày cách tạo một lượt đặt trước cho phương thức triển khai tiêu chuẩn.
Khi người dùng tạo một yêu cầu đặt trước, Google sẽ gửi cho bạn tên, họ, số điện thoại và email của người dùng đó. Theo quan điểm của bạn, lượt đặt phòng này cần được coi là lượt thanh toán của khách vì Trung tâm hành động không thể tra cứu tài khoản của người dùng trong hệ thống của bạn. Đảm bảo rằng lượt đặt phòng cuối cùng giống hệt với lượt đặt phòng của người bán qua hệ thống đặt phòng của bạn.
Bảo mật và xác thực
Tất cả hoạt động giao tiếp với máy chủ đặt phòng đều diễn ra qua HTTPS, vì vậy, máy chủ của bạn phải có chứng chỉ TLS hợp lệ khớp với tên DNS. Để giúp thiết lập máy chủ, bạn nên sử dụng một công cụ xác minh SSL/TLS có sẵn công khai, chẳng hạn như Kiểm thử máy chủ SSL của Qualys.
Tất cả các yêu cầu mà Google gửi đến máy chủ đặt phòng của bạn sẽ được xác thực bằng phương thức xác thực cơ bản HTTP. Bạn có thể nhập thông tin xác thực cơ bản (tên người dùng và mật khẩu) cho máy chủ đặt phòng trên trang Cấu hình máy chủ đặt phòng trong Cổng thông tin đối tác. Bạn phải thay đổi mật khẩu 6 tháng một lần.
Triển khai khung mẫu
Để bắt đầu, hãy xem các khung mẫu sau đây của máy chủ đặt phòng được viết cho khung Node.js và Java:
- Khung Node.js js-maps-booking-rest-server-v3-skeleton
- Khung Java java-maps-booking-rest-server-v3-skeleton
Các máy chủ này đã tạo bản mô phỏng cho các phương thức REST.
Yêu cầu
Lỗi HTTP và lỗi logic nghiệp vụ
Khi phần phụ trợ xử lý các yêu cầu HTTP, có thể xảy ra hai loại lỗi.
- Lỗi liên quan đến cơ sở hạ tầng hoặc dữ liệu không chính xác
- Trả về các lỗi này cho ứng dụng khách bằng mã lỗi HTTP chuẩn. Xem danh sách đầy đủ mã trạng thái HTTP.
- Lỗi liên quan đến logic kinh doanh
- Trả về mã trạng thái HTTP được đặt thành
200OK và chỉ định lỗi logic nghiệp vụ trong nội dung phản hồi. Các loại lỗi logic kinh doanh mà bạn có thể gặp phải sẽ khác nhau tuỳ theo loại triển khai máy chủ.
- Trả về mã trạng thái HTTP được đặt thành
Đối với phương thức triển khai Chuẩn, các lỗi logic kinh doanh có thể xảy ra sẽ được ghi lại trong Booking Failure (Lỗi đặt phòng) và được trả về trong phản hồi HTTP. Bạn có thể gặp lỗi logic nghiệp vụ khi tạo hoặc cập nhật tài nguyên. Ví dụ: khi bạn xử lý các phương thức CreateBooking hoặc UpdatingBooking. Một số ví dụ bao gồm, nhưng không giới hạn ở:
SLOT_UNAVAILABLEđược dùng nếu khung giờ được yêu cầu không còn.PAYMENT_ERROR_CARD_TYPE_REJECTEDđược dùng nếu loại thẻ tín dụng được cung cấp không được chấp nhận.
Tính chất idempotent
Không phải lúc nào việc giao tiếp qua mạng cũng đáng tin cậy và Google có thể thử lại các yêu cầu HTTP nếu không nhận được phản hồi. Vì lý do này, tất cả các phương thức thay đổi trạng thái phải idempotent:
CreateBookingUpdateBooking
Đối với mọi thông báo yêu cầu ngoại trừ UpdateBooking, mã thông báo idempotent sẽ được đưa vào để xác định duy nhất yêu cầu đó. Điều này cho phép bạn phân biệt giữa lệnh gọi REST thử lại, với ý định tạo một yêu cầu và hai yêu cầu riêng biệt.
UpdateBooking được xác định riêng biệt bằng mã mục đặt phòng tương ứng, vì vậy, không có mã thông báo về tính chất idempotent nào được đưa vào yêu cầu của chúng.
Sau đây là một số ví dụ về cách máy chủ đặt phòng xử lý tính chất không thể thay đổi:
Phản hồi HTTP
CreateBookingthành công sẽ bao gồm cả lượt đặt phòng đã tạo. Trong một số trường hợp, khoản thanh toán được xử lý trong quy trình đặt phòng. Nếu nhận được chính xác cùng mộtCreateBookingRequestlần thứ hai (với cùng mộtidempotency_token), thì phải trả về chínhCreateBookingResponseđó. Hệ thống sẽ không tạo yêu cầu đặt phòng thứ hai và người dùng sẽ chỉ bị tính phí một lần (nếu có).Xin lưu ý rằng nếu một lần thử
CreateBookingkhông thành công và cùng một yêu cầu được gửi lại, thì trong trường hợp này, phần phụ trợ của bạn sẽ thử lại yêu cầu đó.
Yêu cầu về tính chất idempotent áp dụng cho tất cả các phương thức thay đổi trạng thái.