Việc thiết lập một máy chủ Đặt phòng ở phía bạn sẽ cho phép Actions Center tạo cuộc hẹn / lượt đặt phòng / lượt đặt chỗ với bạn thay mặt cho người dùng.
Triển khai một giao diện API dựa trên gRPC
Xin lưu ý: tất cả đối tác mới đều nên sử dụng giao diện REST API thay vì gRPC API.
Triển khai một giao diện API dựa trên gRPC. Nhờ đó, Google có thể gửi yêu cầu đặt trước. 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 URL và CỔNG 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 nhóm API v2 được đề xuất. Quy định 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 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 Actions Center để tìm hiểu thêm.
Tải định nghĩa dịch vụ ở định dạng proto xuống bên dưới để bắt đầu triển khai API.
Tài nguyên API
Vui lòng tìm hiểu kỹ các loại tài nguyên sau đây sẽ được sử dụng trong quá trình triển khai này:
- Slot: một ô chức năng trong khoảng không quảng cáo
- Đặt trước: đặt lịch hẹn cho một khung giờ trong lịch
Phương thức
Bạn bắt buộc phải triển khai các phương thức API sau đây ở phía bạn cho máy chủ gRPC:
5 phương thức này xác định nhóm 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 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. Đối tác nên coi đây là một quy trình thanh toán của khách 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. Người bán của đối tác sẽ thấy thông tin đặt phòng cuối cùng trong hệ thống của họ, giống như thông tin đặ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 bằng Java có thể được biên dịch và cài đặt. Hãy xem 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ó thể xảy ra 2 loại lỗi khi một hệ thống 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 lượt đặt phòng (xem Lỗi đặt phòng), ví dụ: nếu khung giờ được yêu cầu không có sẵn.
Nếu gặp phải lỗi không mong muốn, bạn nên trả về cho ứng dụng bằ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, đồng thời sẽ được trả về nếu khe cắm đượ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.
Hãy xem thông tin tham khảo về từng phương thức để biết mã lỗi gRPC chuẩn hoặc xem danh sách đầy đủ mã trạng thái.
Ngược lại, các lỗi logic nghiệp vụ phải được ghi lại trong BookingFailure và được trả về trong phản hồi RPC. Bạn có thể gặp phải lỗi logic nghiệp vụ khi tạo hoặc cập nhật tài nguyên, tức là khi xử lý các 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 khe cắm được yêu cầu không còn nữa.
- PAYMENT_ERROR_CARD_TYPE_REJECTED được dùng nếu loại thẻ tín dụng bạn cung cấp không được chấp nhận.
Tính chất luỹ đẳ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 các RPC nếu không nhận được phản hồi. Vì lý do này, tất cả các RPC làm thay đổi trạng thái (CreateBooking, UpdateBooking) đều phải có tính chất luỹ đẳng. Thông báo yêu cầu cho các RPC này bao gồm mã thông báo về tính chất bất biến để xác định duy nhất yêu cầu và cho phép đối tác phân biệt giữa một RPC được thử lại (với mục đích tạo một lượt đặt phòng duy nhất) và hai 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 thông tin đặ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 cùng một CreateBookingRequest được nhận lần thứ hai (kể cả
idempotency_token), thì bạn phải trả về cùng một CreateBookingResponse. Không có lượt đặt phòng thứ hai nào được tạo và người dùng (nếu có) chỉ bị tính phí một lần. Xin lưu ý rằng nếu một lần thử CreateBooking không thành công, thì phần phụ trợ của đối tác sẽ phải thử lại nếu cùng một yêu cầu được gửi lại.
Yêu cầu về tính chất luỹ đẳng áp dụng cho tất cả các phương thức có chứa mã thông báo luỹ đẳng.
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ủa bạn cần được bảo mật bằng SSL/TLS với phương thức xác thực tương hỗ dựa trên chứng chỉ của máy khách/máy chủ. Điều này yêu cầu bạn sử dụng chứng chỉ máy chủ hợp lệ cho việc 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ệ 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 phương thức 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 thực tế của chứng chỉ 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 khách: để xác thực chúng tôi (với tư cách là Google) cho đố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 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 những lần 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 nhóm chứng chỉ gốc đáng tin cậy của ứng dụng. Bạn có thể chọn lấy bộ gốc đáng tin cậy này từ một cơ quan như Mozilla hoặc cài đặt bộ gốc hiện được Cơ quan quản lý Internet của 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 GRPC.
Giao thức này cho phép Google theo dõi trạng thái phụ trợ của việc 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 các lệnh gọi kiểm tra tình trạng là ext.maps.booking.partner.v2.BookingService cho API phiên bản 2 hoặc ext.maps.booking.partner.v0.BookingService cho API phiên bản 0. Quy trình kiểm tra tình trạng phải chạy trên cùng một URL và CỔNG 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 phiên bản 3 * API phiên bản 0