Внедрить сервер бронирования: API v2.

Настройка сервера бронирования на вашей стороне позволит Центру действий создавать записи/бронирования/резервации от имени пользователя.

Реализуйте API-интерфейс на основе gRPC.

Обратите внимание: всем новым партнерам следует использовать интерфейс REST API, а не gRPC API.

Реализуйте API-интерфейс на основе gRPC . Это позволит Google отправлять запросы на бронирование. API-интерфейс определяется с использованием IDL на основе protobuf gRPC .

Мы просим наших новых партнеров внедрить рекомендуемый набор API версии 2. Партнеры могут выбрать тот URL-адрес и порт, которые лучше всего подходят для их инфраструктуры.

В этом разделе представлен рекомендуемый набор API v2. Он применим к партнерам, которые еще не внедрили API v0. Нашим текущим партнерам, которые уже внедрили API v0, следует обратиться в Центр действий для получения дополнительной информации.

Загрузите описание сервиса в формате proto ниже, чтобы начать реализацию API.

Скачать определение сервиса

Ресурсы API

Пожалуйста, ознакомьтесь со следующими типами ресурсов, которые будут использоваться в данной реализации:

Методы

Для работы с gRPC-сервером на вашей стороне необходимо реализовать следующие методы API:

Эти 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) {}
}

Схема: создание бронирования

Рисунок 1: Создание бронирования из временного слота.

При создании бронирования Google отправляет партнеру имя, фамилию, номер телефона и адрес электронной почты пользователя. С точки зрения партнера, это следует рассматривать как оформление заказа без регистрации, поскольку Центр действий не имеет возможности найти учетную запись пользователя в системе партнера. Окончательное бронирование должно отображаться продавцам партнера в их системе так же, как и бронирования, поступающие в систему бронирования партнера.

Реализация скелета в Java

Для начала мы предоставляем базовый gRPC-сервер на Java, который можно скомпилировать и установить. Его можно найти в разделе «Примеры > Эталонная реализация gRPC» . Этот сервер содержит заглушки для необходимых методов gRPC, поддерживающих интеграцию, включая аутентификацию и проверку работоспособности.

Требования

Ошибка gRPC и ошибка бизнес-логики

При обработке gRPC-запросов партнерской системой могут возникать два типа ошибок: непредвиденные ошибки, возникающие из-за некорректных данных; и ошибки бизнес-логики, указывающие на невозможность создания или обновления бронирования (см. Ошибка бронирования ), например, если запрошенное место недоступно.

В случае возникновения непредвиденных ошибок, они должны быть возвращены клиенту с использованием стандартных кодов ошибок gRPC. Примеры включают, но не ограничиваются следующим:

  • Параметр INVALID_ARGUMENT используется в RPC-вызовах, таких как CheckAvailability и CreateLease, и должен возвращаться, если предоставленный слот содержит недопустимую информацию.
  • Параметр NOT_FOUND используется в RPC-вызовах, таких как CreateBooking и ListBookings, и должен возвращаться, если предоставленный идентификатор неизвестен партнеру.

Для получения информации о канонических кодах ошибок gRPC см. справочную информацию по каждому методу или полный список кодов состояния .

Напротив, ошибки бизнес-логики следует фиксировать в сообщении об ошибке бронирования (Booking Failure) и возвращать в ответе RPC. Ошибки бизнес-логики могут возникать при создании или обновлении ресурса, то есть при обработке RPC-запросов CreateBooking и UpdatingBooking. Примеры включают, но не ограничиваются следующим:

  • Параметр SLOT_UNAVAILABLE используется, если запрошенный слот больше недоступен.
  • Параметр PAYMENT_ERROR_CARD_TYPE_REJECTED используется, если указанный тип кредитной карты не принимается.

Идемпотентность

Обмен данными по сети не всегда надежен, и Google Reserve может повторять RPC-запросы, если не получает ответа. По этой причине все RPC-запросы, изменяющие состояние (CreateBooking, UpdateBooking), должны быть идемпотентными. Сообщения запроса для этих RPC-запросов содержат токены идемпотентности для уникальной идентификации запроса и позволяют партнеру различать повторный RPC-запрос (с целью создания одного бронирования) и два отдельных бронирования.

Примеры включают, но не ограничиваются следующим:

  • Успешный RPC-ответ CreateBooking включает созданное бронирование, и в некоторых случаях оплата обрабатывается в рамках процесса бронирования. Если точно такой же запрос CreateBookingRequest получен повторно (включая idempotency_token ), то должен быть возвращен тот же запрос CreateBookingResponse. Второе бронирование не создается, и с пользователя, если таковой имеется, взимается плата ровно один раз. Обратите внимание, что если попытка создания бронирования не удалась, партнерская система должна повторить попытку, если тот же запрос будет отправлен снова.

Требование идемпотентности применяется ко всем методам, содержащим токены идемпотентности.

Безопасность и аутентификация 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