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.
- Triển khai Danh sách chờ đặt chỗ. Mã này được dùng khi bạn tham gia chương trình thí điểm về Danh sách chờ đặt phòng. Điều này cho phép Actions Center truy xuất thời gian chờ ước tính và thay mặt người dùng tạo mục trong danh sách chờ.
- 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. Để triển khai máy chủ đặt phòng cho tính năng tích hợp Dịch vụ đặt phòng hoàn chỉnh, vui lòng tham khảo phần Triển khai máy chủ đặt phòng.
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 danh sách chờ |
|---|
| Định nghĩa dịch vụ danh sách chờ. 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/ |
| BatchGetWaitEstimates | POST /v3/BatchGetWaitEstimates/ |
| CreateWaitlistEntry | POST /v3/CreateWaitlistEntry/ |
| GetWaitlistEntry | POST /v3/GetWaitlistEntry/ |
| DeleteWaitlistEntry | POST /v3/DeleteWaitlistEntry/ |
Tài nguyên API
Danh sách chờ
Các tài nguyên sau đây được dùng để triển khai tính năng đặt chỗ dựa trên danh sách chờ:
- WaitEstimate: Thời gian chờ ước tính cho một số lượng người dự tiệc và người bán cụ thể.
- WaitlistEntry: Mục nhập của người dùng trong danh sách chờ.
Quy trình: tạo mục trong danh sách chờ
Phần này trình bày cách tạo một lượt đặt phòng để tích hợp tính năng Danh sách chờ đặt phòng.
Khi người dùng tạo một mục trong danh sách chờ, Google sẽ gửi cho bạn tên, họ, số điện thoại và email của người dùng. Email này giống với Tài khoản Google của người dùng và được coi là giá trị nhận dạng duy nhất. Theo quan điểm của bạn, danh sách chờ này cần được coi là giao dịch thanh toán của khách vì tính năng Đặt trước bằng Google 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 mục nhập danh sách chờ cuối cùng giống với mục nhập của người bán trong hệ thống danh sách chờ 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 miễn phí, 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 tính năng tích hợp Danh sách chờ đặt chỗ, các lỗi logic nghiệp vụ được ghi lại trong Lỗi logic nghiệp vụ của danh sách chờ 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 tài nguyên, chẳng hạn như khi xử lý phương thức CreateWaitlistEntry. Các ví dụ bao gồm, nhưng không chỉ gồm:
ABOVE_MAX_PARTY_SIZEđược dùng khi mục nhập danh sách chờ được yêu cầu vượt quá quy mô bữa tiệc tối đa của người bán.MERCHANT_CLOSEDđược dùng khi danh sách chờ không mở vì nhà bán hàng đã đóng cửa.
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:
CreateWaitlistEntryDeleteWaitlistEntry
Đối với mọi thông báo yêu cầu ngoại trừ DeleteWaitlistEntry, 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.
DeleteWaitlistEntry được xác định riêng biệt bằng mã mục nhập danh sách chờ tương ứng, vì vậy, không có mã thông báo về tính chất không thể thay đổi trong các yêu cầu của họ.
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
CreateWaitlistEntrythành công sẽ bao gồm mã mục nhập danh sách chờ đã tạo. Nếu cùng mộtCreateWaitlistEntryRequestđược nhận lần thứ hai (với cùng mộtidempotency_token), thì phải trả về cùng mộtCreateWaitlistEntryResponse. Không có mục nhập danh sách chờ thứ hai nào được tạo và không có lỗi nào được trả về.Xin lưu ý rằng nếu một lần thử
CreateWaitlistEntrykhông thành công và cùng một yêu cầu được gửi lại, thì phần phụ trợ của bạn sẽ thử lại trong trường hợp này.
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.