Настройка сервера бронирования на вашей стороне позволит Центру действий создавать встречи/бронирования/бронирования у вас от имени пользователя.
Реализовать интерфейс API на основе gRPC.
Обратите внимание: всем новым партнерам следует использовать интерфейс REST API, а не gRPC API.
Реализовать API-интерфейс на основе gRPC . Это позволяет Google отправлять запросы на бронирование. Поверхность API определяется с использованием IDL на основе protobuf gRPC .
Мы просим наших новых партнеров внедрить рекомендуемый набор API v2. Партнеры могут выбрать тот URL-адрес и ПОРТ, которые лучше всего подходят для их инфраструктуры.
В этом разделе представлен рекомендуемый набор API v2. Это касается партнеров, которые не внедрили API v0. Если наши текущие партнеры внедрили API версии 0, обратитесь в Центр действий, чтобы узнать больше.
Загрузите определение сервиса в формате прототипа ниже, чтобы приступить к реализации API.
API-ресурсы
Пожалуйста, ознакомьтесь со следующими типами ресурсов, которые будут использоваться в этой реализации:
- Слот : слот инвентаря.
- Бронирование : запись на место в инвентаре
Методы
Следующие методы API должны быть реализованы на вашей стороне для сервера gRPC:
Эти 5 методов определяют необходимый набор RPC BookingService:
// 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) {}
}
Ход: создать бронирование
При создании бронирования Google отправит партнеру имя, фамилию, номер телефона и адрес электронной почты пользователя. С точки зрения партнера это следует рассматривать как гостевую проверку, поскольку Центр действий не имеет возможности найти учетную запись пользователя в системе партнера. Окончательное бронирование должно быть показано продавцам партнера в его системе так же, как бронирования, поступающие в систему бронирования партнера.
Реализация скелета в Java
Для начала мы предоставляем скелет сервера gRPC на Java, который можно скомпилировать и установить. Ознакомьтесь с этим в разделе «Примеры» > «Эталонная реализация gRPC» . На этом сервере отключены методы gRPC, необходимые для поддержки интеграции, включая службу аутентификации и работоспособности.
Требования
Ошибка gRPC и ошибка бизнес-логики
Когда серверная часть партнера обрабатывает запросы gRPC, могут возникнуть два типа ошибок: непредвиденные ошибки, возникающие из-за неверных данных; и ошибки бизнес-логики, которые указывают на невозможность создания или обновления бронирования (см. «Ошибка бронирования» ), например, если запрошенный слот недоступен.
Неожиданные ошибки, если они возникли, должны быть возвращены клиенту с использованием канонических кодов ошибок gRPC. Примеры включают, помимо прочего:
- INVALID_ARGUMENT используется в RPC, таких как CheckAvailability и CreateLease, и должен возвращаться, если предоставленный слот содержит недопустимую информацию.
- NOT_FOUND используется в RPC, таких как CreateBooking и ListBookings, и должен возвращаться, если предоставленный идентификатор неизвестен партнеру.
См. ссылку на каждый метод, чтобы узнать его канонические коды ошибок gRPC, или просмотрите полный список кодов состояния .
Напротив, ошибки бизнес-логики должны фиксироваться в сбое резервирования и возвращаться в ответе RPC. Ошибки бизнес-логики могут возникнуть при создании или обновлении ресурса, т. е. при обработке вызовов RPC CreateBooking и UpdatingBooking. Примеры включают, помимо прочего:
- SLOT_UNAVAILABLE используется, если запрошенный слот больше не доступен.
- PAYMENT_ERROR_CARD_TYPE_REJECTED используется, если указанный тип кредитной карты не принимается.
Идемпотентность
Связь по сети не всегда надежна, и Google Reserve может повторить попытку RPC, если ответ не получен. По этой причине все RPC, изменяющие состояние (CreateBooking, UpdateBooking), должны быть идемпотентными. Сообщения запроса для этих RPC включают токены идемпотентности, позволяющие уникально идентифицировать запрос и позволяющие партнеру различать повторную попытку RPC (с намерением создать одно бронирование) и два отдельных бронирования.
Примеры включают, помимо прочего:
- Успешный ответ CreateBooking RPC включает в себя созданное бронирование, и в некоторых случаях платеж обрабатывается как часть потока бронирования. Если тот же CreateBookingRequest получен во второй раз (включая
idempotency_token), то должен быть возвращен тот же CreateBookingResponse. Второе бронирование не создается, и с пользователя, если применимо, взимается плата ровно один раз. Обратите внимание: если попытка CreateBooking не удалась, серверная часть партнера должна повторить попытку, если тот же запрос будет отправлен снова.
Требование идемпотентности применяется ко всем методам, содержащим токены идемпотентности.
Безопасность и аутентификация сервера gRPC
Вызовы из Центра действий на ваш сервер должны быть защищены с помощью SSL/TLS с взаимной проверкой подлинности клиента и сервера на основе сертификатов. Для этого необходимо использовать действительный сертификат сервера для реализации gRPC и принять действительный сертификат клиента.
Сертификат сервера: партнерский сервер должен быть оснащен действительным сертификатом сервера, связанным с доменным именем сервера (см. этот список принятых корневых центров сертификации ). Реализации сервера GRPC предполагают обслуживать цепочку сертификатов, ведущую к корневому сертификату. Самый простой способ сделать это — добавить промежуточные сертификаты, предоставленные веб-хостом партнера в формате PEM, к сертификату сервера (также в формате PEM).
Сертификат сервера проверяется во время подключения, самозаверяющие сертификаты не принимаются. Фактическое содержимое сертификата не проверяется, пока сертификат действителен. Вы можете проверить действительность вашего сертификата с помощью следующей команды:
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
Сертификат клиента: чтобы аутентифицировать нас (как Google) партнеру, мы предоставляем сертификат клиента, выданный Google Internet Authority G2 ( сертификат CA ) со следующими свойствами:
| Поле | Ценить |
|---|---|
CN | mapsbooking.businesslink-3.net |
SAN | DNS:mapsbooking.businesslink-3.net |
Попытки подключения без этого сертификата клиента должны быть отклонены партнерским сервером.
Для проверки сертификата клиента сервер использует набор доверенных корневых сертификатов клиента. Вы можете получить этот набор доверенных корней от такого органа, как Mozilla, или установить набор корней, рекомендованный в настоящее время Google Internet Authority G2 . В обоих случаях вам, возможно, придется время от времени обновлять корневые сертификаты вручную.
Внедрить протокол проверки работоспособности gRPC.
Внедрить протокол проверки работоспособности GRPC . Этот протокол позволяет Google отслеживать серверный статус вашей реализации gRPC. Спецификация сервиса является частью дистрибутива GRPC. В соответствии с соглашением об именах GRPC имя службы в вызовах проверки работоспособности — ext.maps.booking.partner.v2.BookingService для API v2 или ext.maps.booking.partner.v0.BookingService для API v0. Проверка работоспособности должна выполняться по тому же URL-адресу и ПОРТУ, что и другие конечные точки.
Другие версии
Документацию для других версий API см. на следующих страницах: * API v3 * API v0