Ao configurar um servidor de agendamento, a Central de ações pode Criar agendamentos / reservas com você em nome do usuário.
Implementar uma interface de API baseada no gRPC
Observação: todos os parceiros novos devem usar a interface da API REST em vez do gRPC. API.
Implemente uma interface de API baseada em gRPC. Isso permite que o Google envie solicitações de reserva. A superfície da API é definido usando o protocolo protobuf do gRPC IDL.
Pedimos aos nossos novos parceiros que implementem um conjunto recomendado de API v2. Os parceiros podem selecionar o URL e a PORTA que funcionarem melhor para sua infraestrutura.
Esta seção apresenta um conjunto recomendado de APIs v2. Isso se aplica a parceiros que implementaram a API v0. Para os parceiros que já 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 usar implementação da API.
Faça o download do serviço definição
Recursos de API
Familiarize-se com os seguintes tipos de recursos que serão utilizadas nesta implementação:
- Slot: um inventário. entrada
- Agendamento: para um horário no inventário
Métodos
Você precisa implementar os seguintes métodos de API para 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 enviará ao parceiro o nome do usuário, sobrenome, número de telefone e e-mail. Isso deve ser tratado como um do ponto de vista do parceiro, já que a Central de ações não tem para procurar a conta do usuário no sistema do parceiro. A reserva final precisa ser mostrado aos comerciantes do parceiro no sistema deles, assim como as reservas. que vêm para o sistema de reservas do parceiro.
Implementação de estrutura em Java
Para começar, fornecemos um esqueleto de servidor gRPC em Java que pode ser compilado. e instalado. Confira em Amostras > Implementação da referência do gRPC nesta seção. Este servidor eliminou os métodos gRPC que são necessários para a compatibilidade a integração, incluindo autenticação e serviços de saúde.
Requisitos
erro de gRPC e de lógica de negócios
Podem ocorrer dois tipos de erros 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 uma reserva (consulte Reservas falha), Por exemplo, se o horário solicitado não estiver disponível.
Erros inesperados, se encontrados, devem ser retornados ao cliente usando códigos de erro canônicos do gRPC. Alguns exemplos incluem:
- INVALID_MCC é usado em RPCs, como CheckAvailability e CreateLease, e deve ser retornado se o espaço fornecido contiver informações inválidas.
- NOT_FOUND é usado em RPCs, como CreateBooking e ListBookings, e precisa será retornado se o parceiro não souber o identificador fornecido.
Consulte a referência de cada método para os respectivos códigos de erro gRPC canônicos ou consulte a documentação lista de códigos de status.
Pelo contrário, erros de lógica de negócios devem ser capturados em Agendamento falha; retornados na resposta da RPC. Erros de lógica de negócios podem ser encontrados ao criar ou atualizar um recurso, ou seja, ao lidar com RPCs CreateBooking, e Atualização de reserva. 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 for não é 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, todos os RPCs que mudam (CreateBooking, UpdateBooking) precisam ser idempotentes. Mensagens de solicitação para essas RPCs incluem tokens de idempotência para identificar exclusivamente a solicitação e permitir o parceiro para distinguir entre uma RPC repetida (com a intenção de criar uma reserva única) e duas reservas separadas.
Alguns exemplos incluem:
- Um bem-sucedido
RPC CreateBooking
inclui a reserva criada e, em alguns casos, o pagamento é
processados como parte do fluxo de reserva. Se o mesmo CreateBookingRequest
for recebido uma segunda vez (incluindo
idempotency_token), o mesmo CreateBookingResponse precisa ser retornado. Nenhuma segunda reserva é criada e o usuário, se for o caso, é cobrado exatamente uma vez. Se uma tentativa do CreateBooking falhar, o back-end do parceiro deverá tentar novamente se a mesma solicitação for enviada outra vez.
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 o back-end precisam ser protegidas usando SSL/TLS com autenticação de cliente/servidor mútua baseada em certificado. Isso exige que o uso de um certificado de servidor válido para sua implementação do gRPC e a aceitação de uma certificado de cliente válido.
Certificado do servidor:o servidor do parceiro precisa estar equipado com um certificado de servidor associado ao nome de domínio do servidor (consulte este lista de CAs raiz aceitas). As implementações do servidor GRPC esperam exibir uma cadeia de certificados que leva o certificado raiz. A maneira mais fácil de fazer isso é anexando o certificados intermediários fornecidos pelo host da Web do parceiro em formato PEM para o certificado do servidor (também em formato PEM).
O certificado do servidor é verificado no momento da conexão e autoassinado certificados não são aceitos. O conteúdo real do certificado não é verificado como desde que o certificado seja válido. Você pode verificar a validade do seu certificado pelo 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) para o parceiro, fornecemos um certificado do cliente emitido pelo Google Internet Authority G2 (CA) certificado) pelo propriedades a seguir:
| Campo | Valor |
|---|---|
CN |
mapsbooking.businesslink-3.net |
SAN |
DNS:mapsbooking.businesslink-3.net |
As tentativas de conexão sem esse certificado do cliente devem ser rejeitadas pelo servidor do parceiro.
Para validar o certificado do cliente, o servidor usa um conjunto de clientes confiáveis certificados raiz. Você pode obter esse conjunto de raízes confiáveis de um de Internet, como o Mozilla ou instalar o conjunto de raízes recomendado atualmente pelo Google Autoridade G2. Em ambos em alguns casos, pode ser necessário atualizar manualmente os certificados raiz.
Implementar o protocolo de verificação de integridade do gRPC
Implementar a verificação de integridade do GRPC
Protocolo de acesso.
Esse protocolo permite que o Google monitore o status de back-end do gRPC.
implementação. O serviço
especificaçã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 API v2 ou
ext.maps.booking.partner.v0.BookingService para a API v0. A verificação de integridade precisa
e são executados no mesmo URL e PORTA que os outros endpoints.
Outras versões
Para acessar a documentação de outras versões da API, consulte as seguintes páginas: * API v3 * API v0