Implementar o servidor de reserva: API v2

A configuração de um servidor de agendamento permite que o Centro de ações crie compromissos / agendamentos / reservas com você em nome do usuário.

Implementar uma interface de API com base no gRPC

Observação: todos os novos parceiros precisam usar a interface da API REST em vez da API gRPC.

Implemente uma interface de API com base no gRPC. Isso permite que o Google envie solicitações de reserva. A superfície da API é definida usando o IDL baseado em protobuf do gRPC.

Pedimos aos nossos novos parceiros que implementem um conjunto recomendado da API v2. Os parceiros podem selecionar o URL e a PORTA que funcionar melhor para a infraestrutura.

Esta seção apresenta um conjunto recomendado de API v2. Isso se aplica a parceiros que não implementaram a API v0. Para nossos parceiros atuais que implementaram a API v0, entre em contato com o Centro de ações para saber mais.

Faça o download da definição do serviço no formato proto abaixo para começar a implementação da API.

Fazer o download da definição do serviço

Recursos de API

Conheça os seguintes tipos de recurso que serão usados nesta implementação:

Métodos

Os métodos de API a seguir são obrigatórios para o servidor gRPC:

Estes cinco métodos definem o conjunto necessário de RPCs do 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) {}
}

Fluxo: criar um agendamento

Figura 1: criar um agendamento diretamente de um espaço disponível

Ao criar um agendamento, o Google envia ao parceiro o nome, sobrenome, número de telefone e e-mail do usuário. Isso precisa ser tratado como uma compra sem login do ponto de vista do parceiro, porque a Central de ações não tem como procurar a conta do usuário no sistema do parceiro. A reserva final precisa ser mostrada aos comerciantes do parceiro no sistema deles, assim como as reservas que vêm do sistema de reservas do parceiro.

Implementação de esqueleto em Java

Para começar, fornecemos um servidor gRPC em Java que pode ser compilado e instalado. Confira na seção Samples > gRPC Reference Implementation. Esse servidor tem métodos gRPC stubbed necessários para oferecer suporte à integração, incluindo autenticação e serviço de integridade.

Requisitos

Erro de gRPC e de lógica de negócios

Dois tipos de erros podem ocorrer quando um back-end do parceiro processa solicitações gRPC: erros inesperados que surgem de dados incorretos e erros de lógica de negócios que indicam a incapacidade de criar ou atualizar um agendamento (consulte Falha de agendamento), por exemplo, se o espaço solicitado estiver indisponível.

Erros inesperados, se encontrados, devem ser retornados ao cliente usando códigos de erro canônicos do gRPC. Alguns exemplos incluem, entre outros:

  • INVALID_ARGUMENT é usado em RPCs, como CheckAvailability e CreateLease, e precisa ser retornado se o slot fornecido tiver informações inválidas.
  • NOT_FOUND é usado em RPCs, como CreateBooking e ListBookings, e precisa ser retornado se o identificador fornecido for desconhecido pelo parceiro.

Consulte a referência de cada método para ver os códigos de erro canônicos do gRPC ou a lista completa de códigos de status.

Por outro lado, os erros de lógica de negócios precisam ser capturados em Falhas no agendamento e retornados na resposta do RPC. Esses erros podem acontecer ao criar ou atualizar um recurso, ou seja, ao processar RPCs CreateBooking e UpdatingBooking. Alguns exemplos incluem, entre outros:

  • SLOT_UNAVAILABLE é usado se o slot solicitado não estiver mais disponível.
  • PAYMENT_ERROR_CARD_TYPE_REJECTED é usado se o tipo de cartão de crédito fornecido não for aceito.

Idempotência

A comunicação pela rede nem sempre é confiável, e o Google Reserve pode repetir RPCs se nenhuma resposta for recebida. Por esse motivo, todas as RPCs que modificam o estado (CreateBooking, UpdateBooking) precisam ser idempotentes. As mensagens de solicitação para essas RPCs incluem tokens de idempotência para identificar de forma exclusiva a solicitação e permitir que o parceiro distinga entre uma RPC repetida (com a intenção de criar uma reserva única) e duas reservas separadas.

Alguns exemplos incluem, entre outros:

  • Uma resposta RPC CreateBooking bem-sucedida inclui a reserva criada e, em alguns casos, o pagamento é processado como parte do fluxo de reserva. Se o mesmo CreateBookingRequest for recebido uma segunda vez (incluindo idempotency_token), o mesmo CreateBookingResponse precisará ser retornado. O segundo agendamento não será criado, e o usuário, se aplicável, será cobrado apenas uma vez. Se uma tentativa de CreateBooking falhar, o back-end do parceiro vai tentar novamente se a mesma solicitação for enviada de novo.

O requisito de idempotência se aplica a todos os métodos que contêm tokens de idempotência.

Segurança e autenticação do servidor gRPC

As chamadas do Actions Center para o back-end precisam ser protegidas usando SSL/TLS com autenticação mútua de cliente/servidor baseada em certificado. Isso requer o uso de um certificado de servidor válido para a implementação do gRPC e a aceitação de um certificado de cliente válido.

Certificado do servidor:o servidor parceiro precisa ter um certificado de servidor válido associado ao nome de domínio do servidor. Consulte esta lista de autoridades certificadoras raiz aceitas. As implementações do servidor GRPC esperam servir uma cadeia de certificados que leva ao certificado raiz. A maneira mais fácil de fazer isso é anexar os certificados intermediários fornecidos pelo host da Web do parceiro no formato PEM ao certificado do servidor (também no formato PEM).

O certificado do servidor é verificado no momento da conexão, e certificados autoassinados não são aceitos. O conteúdo do certificado não é verificado, desde que o certificado seja válido. Verifique a validade do certificado com o seguinte comando:

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

Certificado do cliente:para nos autenticar (como o Google) ao parceiro, fornecemos um certificado do cliente emitido pela Autoridade da Internet do Google G2 (certificado de AC) com as seguintes propriedades:

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

As tentativas de conexão sem esse certificado do cliente precisam ser rejeitadas pelo servidor do parceiro.

Para validar o certificado do cliente, o servidor depende de um conjunto de certificados raiz confiáveis do cliente. Você pode escolher receber esse conjunto de raízes confiáveis de uma autoridade, como a Mozilla, ou instalar o conjunto de raízes atualmente recomendado pelo Google Internet Authority G2. Em ambos os casos, pode ser necessário atualizar manualmente os certificados raiz.

Implementar o protocolo de verificação de integridade do gRPC

Implemente o protocolo de verificação de integridade do GRPC. Esse protocolo permite que o Google monitore o status do back-end da sua implementação do gRPC. A especificação de serviço faz parte da distribuição do GRPC. Seguindo a convenção de nomenclatura do GRPC, o nome do serviço nas chamadas de verificação de integridade é ext.maps.booking.partner.v2.BookingService para a API v2 ou ext.maps.booking.partner.v0.BookingService para a API v0. A verificação de integridade precisa ser executada no mesmo URL e porta que os outros endpoints.

Outras versões

Para conferir a documentação de outras versões da API, consulte as seguintes páginas: * API v3 * API v0