Việc thiết lập máy chủ Đặt phòng ở phía bạn sẽ cho phép Trung tâm hành động thay mặt người dùng tạo cuộc hẹn / lịch đặt phòng / lịch đặt chỗ với bạn.
Triển khai giao diện API dựa trên gRPC
Xin lưu ý: tất cả đối tác mới đều phải sử dụng giao diện API REST thay vì API gRPC.
Triển khai giao diện API dựa trên gRPC. Việc này cho phép Google gửi yêu cầu đặt phòng. Giao diện API được xác định bằng cách sử dụng IDL dựa trên protobuf của gRPC.
Chúng tôi yêu cầu các đối tác mới triển khai một bộ API v2 được đề xuất. Đối tác có thể chọn bất kỳ URL và PORT nào phù hợp nhất với cơ sở hạ tầng của họ.
Phần này giới thiệu một bộ API v2 được đề xuất. Điều khoản này áp dụng cho những đối tác chưa triển khai API phiên bản 0. Đối với các đối tác hiện tại đã triển khai API phiên bản 0, vui lòng liên hệ với Trung tâm hành động để tìm hiểu thêm.
Tải định nghĩa dịch vụ ở định dạng proto ở bên dưới để bắt đầu triển khai API.
Tài nguyên API
Vui lòng làm quen với các loại tài nguyên sau đây sẽ được sử dụng trong quá trình triển khai này:
- Khe: một khe khoảng không quảng cáo
- Lượt đặt trước: lượt đặt trước một khung giờ nhận đặt hẹn
Phương thức
Bạn bắt buộc phải triển khai các phương thức API sau đây cho máy chủ gRPC:
5 phương thức này xác định tập hợp RPC BookingService bắt buộc:
// Manages slot availability, leases and bookings for an inventory of
// appointments
service BookingService {
// Gets availability information for an appointment slot
rpc CheckAvailability(CheckAvailabilityRequest)
returns (CheckAvailabilityResponse) {}
// Creates a booking
rpc CreateBooking(CreateBookingRequest) returns (CreateBookingResponse) {}
// Updates an existing booking
rpc UpdateBooking(UpdateBookingRequest) returns (UpdateBookingResponse) {}
// Gets status for an existing booking
rpc GetBookingStatus(GetBookingStatusRequest)
returns (GetBookingStatusResponse) {}
// Lists all upcoming bookings for a user
rpc ListBookings(ListBookingsRequest) returns (ListBookingsResponse) {}
}
Quy trình: tạo lượt đặt trước
Khi tạo yêu cầu đặt trước, Google sẽ gửi cho đối tác tên, họ, số điện thoại và email của người dùng. Theo quan điểm của đối tác, giao dịch này phải được coi là giao dịch thanh toán không cần đăng nhập vì Trung tâm hành động không có cách nào để tra cứu tài khoản của người dùng trong hệ thống của đối tác. Lượt đặt phòng cuối cùng sẽ hiển thị cho người bán của đối tác trong hệ thống của họ, giống như các lượt đặt phòng đến từ hệ thống đặt phòng của đối tác.
Triển khai khung trong Java
Để bắt đầu, chúng tôi cung cấp một máy chủ gRPC khung trong Java có thể được biên dịch và cài đặt. Hãy xem trong phần Mẫu > Triển khai tham chiếu gRPC. Máy chủ này đã tạo các phương thức gRPC cần thiết để hỗ trợ việc tích hợp, bao gồm cả dịch vụ xác thực và dịch vụ sức khoẻ.
Yêu cầu
Lỗi gRPC và lỗi logic kinh doanh
Có thể xảy ra hai loại lỗi khi phần phụ trợ của đối tác xử lý các yêu cầu gRPC: lỗi không mong muốn phát sinh từ dữ liệu không chính xác; và lỗi logic nghiệp vụ cho biết không thể tạo hoặc cập nhật yêu cầu đặt phòng (xem phần Lỗi đặt phòng), ví dụ: nếu không có khung giờ được yêu cầu.
Nếu gặp lỗi ngoài dự kiến, bạn nên trả về lỗi đó cho ứng dụng bằng cách sử dụng mã lỗi gRPC chuẩn. Các ví dụ bao gồm, nhưng không giới hạn ở:
- INVALID_ARGUMENT được dùng trong các RPC như CheckAvailability và CreateLease, và sẽ được trả về nếu vị trí được cung cấp chứa thông tin không hợp lệ.
- NOT_FOUND được dùng trong các RPC như CreateBooking và ListBookings và sẽ được trả về nếu đối tác không biết giá trị nhận dạng được cung cấp.
Xem tài liệu tham khảo của từng phương thức để biết mã lỗi gRPC chuẩn hoặc xem danh sách mã trạng thái đầy đủ.
Ngược lại, lỗi logic nghiệp vụ phải được ghi lại trong Booking Failure (Lỗi đặt phòng) và trả về trong phản hồi RPC. 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, tức là trong quá trình xử lý RPC CreateBooking và UpdatingBooking. Các ví dụ bao gồm, nhưng không giới hạn ở:
- SLOT_UNAVAILABLE được dùng nếu vị trí đượ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 Reserve có thể thử lại RPC nếu không nhận được phản hồi. Vì lý do này, tất cả RPC thay đổi trạng thái (CreateBooking, UpdateBooking) đều phải idempotent. Thông báo yêu cầu cho RPC này bao gồm mã thông báo idempotent để xác định duy nhất yêu cầu và cho phép đối tác phân biệt giữa RPC thử lại (với ý định tạo một lượt đặt phòng) và 2 lượt đặt phòng riêng biệt.
Các ví dụ bao gồm, nhưng không giới hạn ở:
- Phản hồi RPC CreateBooking thành công bao gồm cả yêu cầu đặt phòng đã tạo và 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ột CreateBookingRequest lần thứ hai (bao gồm cả
idempotency_token), thì bạn phải trả về chính xác cùng một CreateBookingResponse. Hệ thống sẽ không tạo yêu cầu đặt phòng thứ hai và người dùng (nếu có) sẽ chỉ bị tính phí một lần. Xin lưu ý rằng nếu một lần tạo yêu cầu CreateBooking không thành công, thì phần phụ trợ của đối tác sẽ thử lại nếu bạn gửi lại cùng một 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 chứa mã thông báo idempotent.
Bảo mật và xác thực máy chủ gRPC
Bạn cần bảo mật các lệnh gọi từ Trung tâm hành động đến phần phụ trợ bằng SSL/TLS với phương thức xác thực máy khách/máy chủ tương hỗ dựa trên chứng chỉ. Điều này yêu cầu bạn sử dụng một chứng chỉ máy chủ hợp lệ để triển khai gRPC và chấp nhận một chứng chỉ ứng dụng hợp lệ.
Chứng chỉ máy chủ: máy chủ của đối tác phải được trang bị một chứng chỉ máy chủ hợp lệ liên kết với tên miền của máy chủ (tham khảo danh sách các CA gốc được chấp nhận này). Các hoạt động triển khai máy chủ GRPC dự kiến sẽ phân phát một chuỗi chứng chỉ dẫn đến chứng chỉ gốc. Cách dễ nhất để thực hiện việc này là thêm(các) chứng chỉ trung gian do máy chủ lưu trữ web của đối tác cung cấp ở định dạng PEM vào chứng chỉ máy chủ (cũng ở định dạng PEM).
Chứng chỉ máy chủ được xác minh tại thời điểm kết nối và không chấp nhận chứng chỉ tự ký. Nội dung chứng chỉ thực tế sẽ không được kiểm tra miễn là chứng chỉ đó hợp lệ. Bạn có thể kiểm tra tính hợp lệ của chứng chỉ thông qua lệnh sau:
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
Chứng chỉ ứng dụng: để xác thực chúng tôi (với tư cách là Google) với đối tác, chúng tôi cung cấp chứng chỉ ứng dụng do Google Internet Authority G2 (chứng chỉ CA) cấp với các thuộc tính sau:
| Trường | Giá trị |
|---|---|
CN |
mapsbooking.businesslink-3.net |
SAN |
DNS:mapsbooking.businesslink-3.net |
Máy chủ đối tác sẽ từ chối các nỗ lực kết nối không có chứng chỉ ứng dụng này.
Để xác thực chứng chỉ máy khách, máy chủ dựa vào một tập hợp chứng chỉ gốc máy khách đáng tin cậy. Bạn có thể chọn lấy tập hợp các thư mục gốc đáng tin cậy này từ một cơ quan như Mozilla hoặc cài đặt tập hợp các thư mục gốc hiện được Cơ quan Internet Google G2 đề xuất. Trong cả hai trường hợp, đôi khi bạn có thể phải cập nhật chứng chỉ gốc theo cách thủ công.
Triển khai Giao thức kiểm tra tình trạng gRPC
Triển khai Giao thức kiểm tra tình trạng của GRPC.
Giao thức này cho phép Google theo dõi trạng thái phụ trợ của quá trình triển khai gRPC. Quy cách dịch vụ là một phần của bản phân phối GRPC. Theo quy ước đặt tên GRPC, tên của dịch vụ trong lệnh gọi kiểm tra tình trạng là ext.maps.booking.partner.v2.BookingService đối với API v2 hoặc ext.maps.booking.partner.v0.BookingService đối với API v0. Quy trình kiểm tra tình trạng phải chạy trên cùng một URL và PORT với các điểm cuối khác.
Các phiên bản khác
Để biết tài liệu về các phiên bản API khác, hãy xem các trang sau: * API phiên bản 3 * API phiên bản 0