Implementa el servidor de reservas: versión 2 de la API (heredada)

Configurar un servidor de reservas por tu cuenta permitirá que el Centro de acciones realice las siguientes acciones: crear citas, reservas o reservas contigo en nombre del usuario.

Implementa una interfaz de API basada en gRPC

Ten en cuenta que todos los socios nuevos deben usar la interfaz de la API de REST en lugar de gRPC. API.

Implementar una interfaz de API basada en gRPC Esto permite que Google envíe solicitudes de reserva. La plataforma de la API se define con el protobuf basado en protobuf IDL

Les pedimos a nuestros nuevos socios que implementen un conjunto recomendado de API v2. Los socios pueden seleccionar la URL y el PORT que mejor se adapten a su infraestructura

En esta sección, se presenta un conjunto recomendado de API v2. Se aplica a los socios que por lo que no deben haber implementado la versión 0 de la API. Para nuestros socios actuales que implementaron la API v0, comunícate con el Centro de acciones para obtener más información.

Descarga la definición del servicio en formato .proto para comenzar a usar la Implementación de la API.

Descarga el servicio definición

Recursos de la API

Familiarízate con los siguientes tipos de recursos que serán utilizados en esta implementación:

  • Espacio: Un inventario ranura
  • Reservas: cita de un espacio del inventario

Métodos

Es obligatorio que implementes los siguientes métodos de API por tu cuenta para el Servidor de gRPC:

Estos 5 métodos definen el conjunto requerido de RPC de 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) {}
}

Flujo: Cómo crear una reserva

Figura 1: Crea una reserva a partir de una ranura

Cuando cree una reserva, Google le enviará al socio el nombre del usuario, apellido, número de teléfono y correo electrónico. Esto se debe tratar como un como invitado desde el punto de vista del socio, ya que el Centro de acciones de búsqueda de la cuenta del usuario en el sistema del socio. La reserva final se mostrará a los comercios del socio en su sistema como las reservas que vienen para el sistema de reservas del socio.

Implementación de esqueleto en Java

Para comenzar, proporcionamos un servidor de gRPC de base en Java que puede compilarse. e instalarse. Consúltala en Muestras > Implementación de referencias de gRPC sección. Este servidor hizo un stub en los métodos de gRPC que son necesarios para admitir la integración, incluidos los servicios de autenticación y salud.

Requisitos

Error de gRPC y error de lógica empresarial

Pueden ocurrir dos tipos de errores cuando el backend de un socio controla las solicitudes de gRPC: errores inesperados que surgen de datos incorrectos; y los errores de lógica empresarial Indicar la incapacidad para crear o actualizar una reserva (consulta el artículo Reserva Error) p.ej., si el horario solicitado no está disponible.

Si se producen errores inesperados, se deben devolver al cliente mediante y códigos de error canónicos de gRPC. Los ejemplos incluyen, entre otros, los siguientes:

  • INVALID_ARGUMENT se usa en RPCs, como CheckAvailability y CreateLease, y se debe mostrar si el espacio proporcionado contiene información no válida.
  • NOT_FOUND se usa en RPC como CreateBooking y ListBookings, y debe Se mostrará si el socio desconoce el identificador proporcionado.

Consulta la referencia de cada método para sus códigos de error de gRPC canónicos o mira la página completa lista de códigos de estado.

Por el contrario, los errores de lógica empresarial deben registrarse en la sección Reservas Con errores que se muestra en la respuesta de RPC. Pueden surgir errores de lógica empresarial al crear o actualizar un recurso, es decir, en el manejo de RPC de CreateBooking y ActualizandoBooking. Los ejemplos incluyen, entre otros, los siguientes:

  • SLOT_UNAVAILABLE se usa si el horario solicitado ya no está disponible.
  • PAYMENT_ERROR_CARD_TYPE_REJECTED se usa si el tipo de tarjeta de crédito proporcionado es no se acepta.

Idempotencia

La comunicación a través de la red no siempre es fiable, por lo que Google Reserve puede reintentar las RPC si no se recibe ninguna respuesta. Por este motivo, todas las RPC que mutan (CreateBooking, UpdateBooking) deben ser idempotentes. Solicitar mensajes para estas RPC incluyen tokens de idempotencia para identificar de manera inequívoca la solicitud y permitir al socio para distinguir entre una RPC que se reintenta (con la intención de crear una una sola reserva) y dos reservas separadas.

Los ejemplos incluyen, entre otros, los siguientes:

  • Se completó correctamente RPC de CreateBooking incluye la reserva creada y, en algunos casos, el pago que se procesan como parte del flujo de la reserva. Si se usa exactamente el mismo CreateBookingRequest se recibe por segunda vez (incluido idempotency_token), luego, el mismo Se debe mostrar CreateBookingResponse. No se crea una segunda reserva y se le cobra al usuario, si corresponde, solo una vez. Ten en cuenta que si falla un intento de CreateBooking, el backend del socio debe volver a intentarlo. si se vuelve a enviar la misma solicitud.

El requisito de idempotencia se aplica a todos los métodos que contienen tokens de idempotencia.

Seguridad y autenticación del servidor gRPC

Las llamadas desde el Centro de Acciones a tu backend deben protegerse con SSL/TLS. con autenticación mutua de cliente-servidor basada en certificados. Esto requiere la usar un certificado de servidor válido para la implementación de gRPC y aceptar un certificado de cliente válido.

Certificado de servidor: el servidor del socio debe estar equipado con un certificado de servidor asociado al nombre de dominio del servidor (consulta este lista de AC raíz aceptadas). Las implementaciones del servidor de GRPC esperan entregar una cadena de certificados que lleve a el certificado raíz. La forma más fácil de hacerlo es agregando certificados intermedios proporcionados por el host web del socio en formato PEM para el certificado del servidor (también en formato PEM).

El certificado del servidor se verifica en el momento de la conexión y está autofirmado. por lo que no se aceptan certificados. El contenido real del certificado no se marca como siempre y cuando el certificado sea válido. Puedes verificar la validez de tu certificado a través del siguiente comando:

echo "" | openssl s_client  -connect YOUR_URL:YOUR_PORT  -showcerts -CApath /etc/ssl/certs

Certificado de cliente: Para autenticarnos (como Google) ante el socio proporcionamos un certificado de cliente emitido por la autoridad de Internet G2 de Google (CA certificado) con el siguientes propiedades:

Campo Valor
CN mapsbooking.businesslink-3.net
SAN DNS:mapsbooking.businesslink-3.net

El equipo de atención al cliente debe rechazar los intentos de conexión sin este certificado de cliente en el servidor del socio.

Para validar el certificado de cliente, el servidor se basa en un conjunto de clientes certificados raíz. Puedes optar por obtener este conjunto de raíces de confianza desde un con autoridad como Mozilla o instala el conjunto de raíces que Google Internet recomienda actualmente Autoridad G2. En ambos Tal vez debas actualizar de forma manual los certificados raíz.

Implementa el protocolo de verificación de estado de gRPC

Implementa la verificación de estado de gRPC Protocolo. Este protocolo permite que Google supervise el estado del backend de tu gRPC para implementarlos. El servicio especificación es parte de la distribución de gRPC. Siguiendo la convención de nomenclatura de gRPC, el nombre del servicio en las llamadas de verificación de estado ext.maps.booking.partner.v2.BookingService para API v2, o ext.maps.booking.partner.v0.BookingService para la versión de API v0. La verificación de estado ejecutar en la misma URL y PORT que los otros extremos.

Otras versiones

Para obtener documentación sobre otras versiones de la API, consulta las siguientes páginas: * API v3 * API v0