Ao configurar um servidor de agendamento, a Central de ações pode criar agendamentos / reservas / reservas com você em nome do usuário.
Implementar uma interface de API baseada em gRPC
Observação: todos os novos parceiros precisam usar a interface da API REST em vez da API gRPC.
Implemente uma interface de API baseada em gRPC. Isso permite que o Google envie solicitações de agendamento. 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 funcionarem melhor para a infraestrutura deles.
Esta seção apresenta um conjunto recomendado da 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 a Central 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
Familiarize-se com os seguintes tipos de recursos que serão utilizados nesta implementação:
- Slot: um slot de inventário
- Agendamento: agendamento para um espaço de inventário.
Métodos
Os seguintes métodos de API são necessários para serem implementados no servidor gRPC:
Estes cinco métodos definem o conjunto obrigató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
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 finalização de compra como convidado do ponto de vista do parceiro, já que 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, da mesma forma que as reservas feitas no sistema do parceiro.
Implementação de esqueleto em Java
Para começar, fornecemos um esqueleto de servidor gRPC em Java que pode ser compilado e instalado. Confira na seção Amostras > Implementação da referência gRPC. Este servidor criou stubs de métodos gRPC que são necessários para oferecer suporte à integração, incluindo autenticação e serviço de integridade.
Requisitos
Erro gRPC e erro de lógica de negócios
Dois tipos de erro podem ocorrer quando um back-end de parceiro processa solicitações gRPC: erros inesperados que surgem de dados incorretos e erros de lógica de negócios que indicam incapacidade de criar ou atualizar um agendamento (consulte Falha no agendamento), por exemplo, se o slot solicitado não estiver disponível.
Erros inesperados, se encontrados, devem ser retornados ao cliente usando códigos de erro gRPC canônicos. Alguns exemplos incluem:
- INVALID_ ARGUMENT é usado em RPCs, como CheckAvailability e CreateLease, e deve ser retornado se o slot fornecido contiver informações inválidas.
- NOT_FOUND é usado em RPCs, como CreateBooking e ListBookings, e precisará ser retornado se o identificador fornecido for desconhecido para o parceiro.
Consulte a referência de cada método para os códigos de erro canônicos do gRPC ou veja a lista completa de códigos de status.
Por outro lado, os erros de lógica de negócios precisam ser registrados em Falha no agendamento e retornados na resposta de RPC. Erros de lógica de negócios podem ser encontrados ao criar ou atualizar um recurso, ou seja, ao processar CreateBooking e RefreshBooking de RPCs. Alguns exemplos incluem:
- SLOT_UNAVAILABLE será usado se o espaço solicitado não estiver mais disponível.
- PAYMENT_ERROR_CARD_TYPE_REJECTED será 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 poderá tentar fazer RPCs novamente se nenhuma resposta for recebida. Por esse motivo, todos os RPCs que mudam o estado (CreateBooking, UpdateBooking) precisam ser idempotentes. As mensagens de solicitação para essas RPCs incluem tokens de idempotência para identificar exclusivamente a solicitação e permitir que o parceiro diferencie uma RPC repetida (com a intenção de criar um único agendamento) e duas reservas separadas.
Alguns exemplos incluem:
- Uma resposta de RPC CreateBooking bem-sucedida inclui o agendamento criado 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. Nenhuma segunda reserva é criada, e o usuário, se aplicável, vai ser cobrado exatamente uma vez. Se uma tentativa de CreateBooking falhar, o back-end do parceiro precisará tentar se a mesma solicitação for enviada novamente.
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 da Central de ações para seu back-end precisam ser protegidas usando SSL/TLS com autenticação mútua de cliente/servidor baseada em certificado. Isso exige o uso de um certificado de servidor válido para a implementação do gRPC e a aceitação de um certificado do cliente válido.
Certificado do servidor:o servidor do parceiro precisa estar equipado com um certificado de servidor válido associado ao nome de domínio do servidor. Consulte esta lista de CAs raiz aceitas. As implementações do servidor GRPC esperam disponibilizar 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 em 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 real do certificado não será verificado enquanto o certificado for válido. Use o seguinte comando para verificar a validade do seu certificado:
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
Certificado do cliente:para nos autenticar como o Google do parceiro, fornecemos um certificado do cliente emitido pela Google Internet Authority G2 (certificado de CA) 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. É possível conseguir esse conjunto de raízes confiáveis de uma autoridade como o Mozilla (link em inglês) ou instalar o conjunto de raízes atualmente recomendado pela Google Internet Authority G2 (em inglês). 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 de back-end da implementação do gRPC. A especificação
do serviço
faz parte da distribuição GRPC. Seguindo a convenção de nomenclatura 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 ver a documentação de outras versões da API, consulte as seguintes páginas: * API v3 * API v0