Configurar um servidor de agendamento permite que a Central de ações crie compromissos, agendamentos e reservas com você em nome do usuário.
Implemente 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 com base em 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 funcionam 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 de serviço no formato proto abaixo para começar a implementar a API.
Recursos de API
Conheça os seguintes tipos de recursos que serão usados nesta implementação:
- Espaço: um espaço disponível no inventário.
- Agendamento: um horário em um espaço do inventário.
Métodos
Os seguintes métodos de API precisam ser implementados na sua extremidade para o servidor gRPC:
Esses 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
Ao criar uma reserva, 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, 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 deles, assim como as reservas que vêm do sistema de reservas do parceiro.
Implementação da estrutura em Java
Para começar, fornecemos um servidor gRPC esqueleto em Java que pode ser compilado e instalado. Confira na seção Amostras > Implementação de referência do gRPC. Esse servidor tem métodos gRPC simulados 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 de 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 no agendamento), por exemplo, se o espaço solicitado estiver indisponível.
Erros inesperados, se encontrados, precisam 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 para o 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.
Ao contrário, os erros de lógica de negócios devem ser capturados em Falha no agendamento e retornados na resposta 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 espaço solicitado não estiver mais disponível.
- PAYMENT_ERROR_CARD_TYPE_REJECTED é usado se o tipo de cartão de crédito informado não for aceito.
Idempotência
A comunicação pela rede nem sempre é confiável, e o Google Reserva pode repetir RPCs se nenhuma resposta for recebida. Por isso, 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 a solicitação de maneira exclusiva e permitir que o parceiro distinga entre uma RPC repetida (com a intenção de criar uma única reserva) e duas reservas separadas.
Alguns exemplos incluem, entre outros:
- Uma resposta
CreateBooking RPC
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. 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 deverá tentar de novo 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 sua implementação do gRPC e a aceitação de um certificado de cliente válido.
Certificado do servidor:o servidor do parceiro precisa ter um certificado de servidor válido associado ao nome de domínio dele. Consulte esta lista de CAs raiz aceitas. As implementações de servidor GRPC esperam veicular uma cadeia de certificados que leve 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 real do certificado não é verificado enquanto ele for 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 Google) com o parceiro, fornecemos um certificado do cliente emitido pela Google Internet Authority G2 (certificado da 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 de cliente confiáveis. Você pode obter esse conjunto de raízes confiáveis de uma autoridade como a Mozilla ou instalar o conjunto de raízes atualmente recomendado pela Google Internet Authority G2. Em ambos os casos, talvez seja necessário atualizar manualmente os certificados raiz de tempos em tempos.
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 dos outros endpoints.
Outras versões
Para documentação de outras versões da API, consulte as seguintes páginas: * API v3 * API v0