Việc thiết lập máy chủ Đặt trước ở phía bạn sẽ cho phép Trung tâm hành động tạo cuộc hẹn / đặt chỗ / đặt chỗ với bạn thay mặt cho người dùng.
Triển khai giao diện API dựa trên gRPC
Xin lưu ý: tất cả đối tác mới 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. Quyền này cho phép Google gửi yêu cầu đặt trước. Bề mặt API được xác định bằ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 bộ API phiên bản 2 được đề xuất. Đối tác có thể chọn bất kỳ URL và cổng nào hoạt động tốt nhất cho cơ sở hạ tầng của mình.
Phần này giới thiệu một bộ API phiên bản 2 được đề xuất. Chính sách này áp dụng cho các đối tác chưa triển khai API phiên bản 0. Đối với những đố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.
Hãy tải định nghĩa dịch vụ xuống ở đị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:
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 sau đây xác định tập hợp RPC SubscriptionService cần thiết:
// 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 một lượt đặt trước
Khi tạo một lượt đặt phòng, Google sẽ gửi cho đối tác họ tên, số điện thoại và email của người dùng. Theo quan điểm của đối tác, đây nên được coi là quy trình 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 trước cuối cùng sẽ được hiển thị cho người bán của đối tác trong hệ thống của họ giống như lượt đặt trước trong hệ thống đặt trước của đối tác.
Triển khai bộ xương trong Java
Để bắt đầu, chúng tôi cung cấp một máy chủ gRPC cơ bản trong Java có thể được biên dịch và cài đặt. Hãy tìm hiểu trong phần Mẫu > Triển khai tham chiếu gRPC. Máy chủ này đã loại bỏ các phương thức gRPC cần thiết để hỗ trợ quá trình 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 nghiệp vụ
Có 2 loại lỗi có thể xảy ra 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 kinh doanh cho biết không thể tạo hoặc cập nhật lượt đặt trước (xem phần Đặt trước không thành công), chẳng hạn như khi không có khoảng trống mà bạn yêu cầu.
Lỗi không mong muốn (nếu gặp phải) sẽ được trả về ứng dụng bằng mã lỗi gRPC chính tắc. Các ví dụ bao gồm, nhưng không giới hạn ở:
- INVALID_ACCOUNT được dùng trong các RPC như CheckAvailability và CreateL chủ đề, đồng thời sẽ được trả về nếu vùng được cung cấp chứa thông tin không hợp lệ.
- NOT_FOUND được sử dụng trong RPC như CreateBooking và ListBookings và sẽ được trả về nếu đối tác không xác định được giá trị nhận dạng được cung cấp.
Bạn có thể xem tài liệu tham khảo của từng phương thức để biết mã lỗi gRPC chính tắc của phương thức đó hoặc xem danh sách mã trạng thái đầy đủ.
Ngược lại, các lỗi logic kinh doanh sẽ được ghi lại trong phần Booking failed (Không đặt chỗ) rồi trả về trong phản hồi RPC. Bạn có thể gặp lỗi về logic nghiệp vụ khi tạo hoặc cập nhật tài nguyên, chẳng hạn như khi xử lý RPC, CreateBooking và (Cập nhật lịch đặt trước). Các ví dụ bao gồm, nhưng không giới hạn ở:
- slot_UNAVAILABLE được sử dụng nếu vùng được yêu cầu không còn trống.
- PAYMENT_ERROR_CARD_TYPE_exclusion được sử dụng nếu loại thẻ tín dụng đã cung cấp không được chấp nhận.
Tính không xác định
Hoạt động giao tiếp qua mạng không phải lúc nào 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 có thay đổi trạng thái (CreateBooking, UpdateBooking) (Tạo đặt trước, yêu cầu cập nhật đặt trước) phải giống nhau. Thông báo yêu cầu cho những RPC này sẽ bao gồm mã thông báo giá trị nhận dạng để xác định riêng yêu cầu và cho phép đối tác phân biệt giữa một RPC đã thử lại (với ý định tạo một lượt đặt trước) và hai lượt đặt trước 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 yêu cầu đặt trước đã tạo và trong một số trường hợp, khoản thanh toán sẽ được xử lý trong quy trình đặt trước. Nếu hệ thống nhận được cùng một CreateBookingRequest giống lần thứ hai (bao gồm cả
idempotency_token), thì tính năng trả về cùng một CreateBookingResponse sẽ phải được trả về. Không có lượt đặt phòng thứ hai nào được tạo và người dùng (nếu có) sẽ bị tính phí chính xác một lần. Xin lưu ý rằng nếu tính năng CreateBooking không thành công, thì phần phụ trợ của đối tác sẽ thử lại nếu hệ thống gửi lại yêu cầu đó.
Yêu cầu về mã xác thực áp dụng cho tất cả phương thức chứa mã thông báo không xác định.
Bảo mật và xác thực máy chủ gRPC
Các lệnh gọi từ Trung tâm hành động đến phần phụ trợ cần được bảo mật 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ỉ. Bạn cần sử dụng chứng chỉ máy chủ hợp lệ để triển khai gRPC và chấp nhận chứng chỉ ứng dụng hợp lệ.
Chứng chỉ máy chủ: máy chủ đối tác phải được trang bị một chứng chỉ máy chủ hợp lệ được 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). Quá trình 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à chứng chỉ tự ký không được chấp nhận. Nội dung của chứng chỉ thực tế sẽ không được kiểm tra miễn là chứng chỉ vẫn 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 khách: để 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 khách do Google Internet Authority G2 (chứng chỉ CA) cấp với những 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ỉ ứng dụng, máy chủ dựa vào một tập hợp các chứng chỉ gốc ứng dụng đáng tin cậy. Bạn có thể chọn lấy tập hợp gốc đáng tin cậy này từ một cơ quan như Mozilla hoặc cài đặt nhóm gốc hiện được cơ quan quản lý Internet của Google đề xuất G2. Trong cả hai trường hợp, đôi khi bạn có thể phải cập nhật các 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 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. Thông số kỹ thuật dịch vụ là một phần của quá trình phân phối GRPC. Theo quy ước đặt tên GRPC, tên của dịch vụ trong các lệnh gọi kiểm tra tình trạng sẽ 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 sẽ chạy trên cùng một URL và Port như các điểm cuối khác.
Các phiên bản khác
Để xem tài liệu về các phiên bản khác của API, hãy xem các trang sau: * API v3 * API v0