Etapa 4: implementar o servidor de agendamento

Você precisa configurar um servidor de reserva para permitir que o Actions Center faça callbacks para criar e atualizar reservas em seu nome.

• A implementação padrão. Isso permite que o Centro de ações crie compromissos, agendamentos e reservas com você em nome do usuário.

Consulte a documentação do Portal do Google Cloud Partner Advantage para saber como configurar a conexão com seus servidores de agendamento do sandbox e de produção.

Implementar uma interface da API REST

Implemente uma interface de API com base em REST. Assim, o Google poderá enviar solicitações do servidor de agendamento por HTTP.

Para começar, configure um servidor de agendamento do sandbox ou de desenvolvimento que possa ser conectado ao ambiente do sandbox da Central de ações. Só mude para um ambiente de produção depois que o servidor do sandbox for completamente testado.

Métodos

Para cada tipo de servidor de agendamento, é necessário usar um conjunto diferente de métodos de API. Você pode fazer o download da definição do serviço no formato proto para começar a implementar a API. As tabelas a seguir mostram os métodos de cada implementação e incluem links para os formatos proto do serviço.

Implementação padrão
Definição de serviço padrão Faça o download do arquivo de definição do serviço proto.

Método	Solicitação HTTP
HealthCheck	GET /v3/HealthCheck/
BatchAvailabilityLookup	POST /v3/BatchAvailabilityLookup/
CreateBooking	POST /v3/CreateBooking/
UpdateBooking	POST /v3/UpdateBooking/
GetBookingStatus	POST /v3/GetBookingStatus/
ListBookings	POST /v3/ListBookings/

Recursos de API

Reserva

Os seguintes tipos de recurso são usados na implementação padrão:

• Espaço: um espaço de inventário.
• Agendamento: um horário em um espaço do inventário.

Fluxo: criar um agendamento

Nesta seção, explicamos como criar um agendamento para a implementação padrão.

Quando um usuário cria um agendamento, o Google envia o nome, sobrenome, número de telefone e e-mail dele. Do seu ponto de vista, esse agendamento precisa ser tratado como uma compra sem login, porque o Centro de ações não consegue procurar a conta do usuário no seu sistema. Verifique se a reserva final é idêntica aos agendamentos dos comerciantes feitos no seu sistema.

Segurança e autenticação

Toda a comunicação com seu servidor de agendamento acontece por HTTPS. Portanto, é essencial que ele tenha um certificado TLS válido que corresponda ao nome DNS. Para ajudar a configurar o servidor, use uma ferramenta de verificação SSL/TLS disponível publicamente, como o SSL Server Test da Qualys.

Todas as solicitações que o Google fizer nesse servidor serão confirmadas pela autenticação básica de HTTP. As credenciais básicas de autenticação (nome de usuário e senha) do seu servidor de agendamento podem ser inseridas na página de configuração do servidor de agendamento no Portal do Google Partners. É preciso mudar de senha a cada seis meses.

Exemplos de implementações da estrutura

Para começar, confira os seguintes exemplos de estrutura de um servidor de agendamento escritos para frameworks Node.js e Java:

• Esqueleto do Node.js js-maps-booking-rest-server-v3-skeleton
• Esqueleto Java java-maps-booking-rest-server-v3-skeleton

Esses servidores usam os métodos REST em testes.

Requisitos

Erros HTTP e de lógica de negócios

Quando seu back-end gerencia solicitações HTTP, podem ocorrer dois tipos de erro.

• Erros relacionados à infraestrutura ou dados incorretos
  • Informe esses erros ao cliente com códigos de erro HTTP padrão. Consulte a lista completa de códigos de status HTTP.
• Erros relacionados à lógica de negócios
  • Retorne o código de status HTTP definido como 200 OK e especifique a falha da lógica de negócios no corpo da resposta. Os tipos de erros de lógica de negócios variam de acordo com o tipo de implementação do servidor.

Para a implementação padrão, os possíveis erros de lógica de negócios são capturados em Falhas no agendamento e retornados na resposta HTTP. Esses erros podem acontecer quando um recurso é criado ou atualizado. Por exemplo, ao processar os métodos CreateBooking ou UpdatingBooking. Confira alguns exemplos:

• 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 poderá repetir solicitações HTTP se nenhuma resposta for recebida. Por isso, todos os métodos que modificam o estado precisam ser idempotentes:

• CreateBooking
• UpdateBooking

Para cada mensagem de solicitação, exceto UpdateBooking, os tokens de idempotência são incluídos para identificar a solicitação de maneira exclusiva. Isso permite distinguir entre uma chamada REST repetida, com a intenção de criar apenas uma solicitação, e duas solicitações separadas. UpdateBooking é identificado de forma exclusiva pelos IDs de entrada do agendamento, respectivamente. Portanto, nenhum token de idempotência é incluído nas solicitações.

Veja a seguir alguns exemplos de como os servidores de agendamento lidam com a idempotência:

• Uma resposta HTTP CreateBooking bem-sucedida inclui o agendamento criado. Em alguns casos, o pagamento é processado como parte do fluxo de reserva. Se o mesmo CreateBookingRequest for recebido uma segunda vez (com o mesmo idempotency_token), o mesmo CreateBookingResponse precisará ser retornado. O segundo agendamento não será criado, e o usuário será cobrado apenas uma vez, se aplicável.

  Se uma tentativa CreateBooking falhar e a mesma solicitação for reenviada, o back-end deverá tentar novamente.

O requisito de idempotência se aplica a todos os métodos que modificam o estado.