Como estabelecer conectividade com as APIs do Google em Java

1. Antes de começar

Pré-requisitos

  • Ter concluído as etapas 1 e 2 do processo de implementação.
  • É possível hospedar o servidor Java fornecido com a terminação TLS usando o Google App Engine ou sua própria solução no domínio configurado com o Google.
  • Ter o Java instalado no seu ambiente.

O que você vai aprender

  • Como verificar a conectividade fazendo uma solicitação válida para a API Google echo.
  • Como receber, descriptografar e analisar uma solicitação do Google para a API Partner Hosted echo.

2. Configuração e requisitos

Baixar o aplicativo

Faça o download do exemplo de código Java.

Visão geral da estrutura do aplicativo

O exemplo de código Java se integra às APIs Standard Payments do Google. A estrutura do projeto de exemplo de código contém um diretório outbound e um diretório inbound para refletir a solicitação de eco de entrada do Google para o parceiro e a solicitação de saída da implementação do parceiro para o Google.

Os dois diretórios contêm uma hierarquia semelhante no pacote por camada. As três camadas principais são controller, service e domain.

  • O pacote controller contém as APIs.
  • O pacote service é responsável pela lógica de negócios, codificação base64url e criptografia.
  • O pacote domain contém POJOs.

Instalar dependências

Navegue até o diretório do projeto e execute o seguinte comando para instalar as dependências necessárias usando o Maven Wrapper. Pule esta etapa se estiver usando o App Engine.

./mvnw install

3. Configurar o ID da conta do integrador de pagamentos (PIAID)

O ID da conta do integrador de pagamentos (PIAID) é um identificador usado para reconhecer suas integrações exclusivas. Você deve ter recebido seu PIAID do Google ao concluir os pré-requisitos antes de iniciar este tutorial.

  1. Navegue até src/main/resources/application.properties no diretório do projeto.
  2. Defina a propriedade payment.integrator.account.id como o PIAID que foi emitido pelo Google.
payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}

4. Definir o URL de eco hospedado pelo Google

O URL echo hospedado pelo Google varia de acordo com a API que você está integrando. Acesse a documentação de referência da API para seu tipo de integração específico e copie o URL da API de eco de diagnóstico. Depois de copiar o URL, siga as próximas etapas para atualizá-lo no projeto Java.

  1. Navegue até src/main/resources/application.properties no diretório do projeto.
  2. Defina a propriedade API_SERVICE_NAME para corresponder ao que é encontrado na documentação do desenvolvedor.
google.hosted.echo.url=vgw.googleapis.com/gsp/{API_SERVICE_NAME}/echo/

5. Adicionar chaves PGP

Conforme mostrado abaixo, adicione suas chaves PGP para ativar a criptografia desse tipo.

  • Navegue até src/resources/publicKey1.gpg e adicione a chave pública blindada em ASCII ao arquivo.
  • Navegue até src/resources/privateKey1.gpg e adicione a chave privada blindada em ASCII ao arquivo.
  • Navegue até src/resources/passphrase1.txt e adicione a senha longa secreta ao arquivo.

Como adicionar chaves PGP

Para ativar a criptografia de duas chaves, adicione a segunda chave pública a publicKey2.gpg, a segunda chave privada a privateKey2.gpg e a segunda senha longa a passphrase.txt. Depois de adicionar as segundas chaves, remova a marca de comentário das linhas de código responsáveis por carregar o segundo par de chaves em KeyConfig.addPrivateKeyAndPassphrase(...) e KeyConfig.addPublicKeys(...).

Agora você já pode executar o aplicativo.

6. Execute o aplicativo

Para iniciar o aplicativo, execute o seguinte comando:

  $ ./mvnw spring-boot:run

Se você estiver executando uma instância pré-configurada do App Engine, execute este comando:

$ gcloud app deploy

Por padrão, o servidor fará a detecção na porta 8080. Para acessar a interface do usuário Swagger da OpenAPI, navegue até o URL abaixo.

https://{APPLICATION_HOST}/swagger-ui.html

7. Testar a conectividade da API Google Standard Payments Outbound

Agora que o aplicativo está em execução, é hora de testar a conectividade com a API Google echo.

A interface do Swagger ou a CLI podem ser usadas para executar o comando a seguir e iniciar uma chamada da sua instância do aplicativo de amostra para os servidores do Google. A API echo desse app aceita uma solicitação POST em texto simples. Depois que ela é recebida, uma outra é enviada para a API hospedada pelo Google.

Enviar uma solicitação pela linha de comando

Substitua HOSTNAME pelo nome do host de servidor antes de executar o comando.

  $ curl -X POST -H 'Content-Type: text/plain' -d 'Hello from Partner Bank!' https://{HOSTNAME}/echo

Enviar uma solicitação na interface do Swagger

Para enviar uma solicitação com a interface do Swagger, acesse https://{APPLICATION_HOST}/swagger-ui e defina a mensagem do cliente no corpo da solicitação. Clique no botão "Executar" quando estiver tudo pronto para enviar a solicitação ao Google.

Envio de uma solicitação de eco do GSP pelo Swagger

Receber a resposta

Uma solicitação de API bem-sucedida resultará na seguinte resposta do Google.

{
   "responseHeader":{
      "responseTimestamp":"1606710026723"
   },
   "clientMessage":"Hello from  Bank Little Bear!",
   "serverMessage":"Server message."
}

Instruções detalhadas

Agora que o servidor enviou uma solicitação, vamos ver como isso funcionou.

Criar a solicitação

createEchoRequestWithMessage em OutboundEchoService cria a solicitação echo enviada para a API do Google.

String jsonEchoRequestMessage = objectMapper.writeValueAsString(createEchoRequestWithMessage(message));

A solicitação gerada inclui clientMessage e vários campos de valor padrão.

{
   "requestHeader":{
      "protocolVersion":{
         "major":1,
         "minor":0,
         "revision":0
      },
      "requestId":"ddfe0fd0-ffdc-4fcf-991a-f0611ec83970",
      "requestTimestamp":"1606715389040"
   },
   "clientMessage":"Hello from Bank Little Bear!"
}

Codificar em base64url e criptografar a solicitação

Todas as solicitações são criptografadas e codificadas em base64url. Neste exemplo, PgpEncryptor.java contém métodos auxiliares que executam criptografia e descriptografia, além da codificação base64url. O método abaixo codifica a solicitação e realiza a criptografia usando a chave pública do Google.

String encryptedMessage = pgpEncryptor.encrypt(jsonEchoRequestMessage);

Enviar a solicitação POST

A mensagem criptografada é enviada por uma solicitação POST.

postStandardPaymentsEchoApi(encryptedMessage)

Descriptografar e decodificar a resposta em base64url e retornar a resposta

A resposta bem-sucedida do Google é codificada e criptografada em base64url. Portanto, ela precisa ser decodificada e descriptografada antes de voltar ao texto simples. O método decrypt decodifica e descriptografa a resposta em base64url.

String decryptedData =
     pgpEncryptor.decrypt(postStandardPaymentsEchoApi(encryptedMessage).getBody());

Retornar a resposta

A resposta é retornada com um código de status HTTP 202.

return new ResponseEntity<>(decryptedData, HttpStatus.ACCEPTED);

8. Testar a conectividade da API de entrada

Para testar a conectividade da API de eco de entrada, o Google enviará uma solicitação à API de eco hospedada pelo parceiro. Quando estiver tudo pronto, trabalhe com seu contato do Google para acioná-la.

O teste echo será concluído quando você conseguir ler a solicitação echo de entrada do Google e enviar uma resposta echo válida.

Instruções detalhadas

Agora que uma solicitação foi recebida e processada pelo servidor, vamos ver como isso funcionou.

Decodificar e descriptografar a solicitação em base64url

Quando uma solicitação é recebida, PgpEncryptor.java chama decrypt, que decodifica e descriptografa a solicitação em base64url.

String decryptedRequest = pgpEncryptor.decrypt(echoRequest);

Receber a solicitação

O Google enviou um payload de mensagem semelhante ao seguinte código após a decodificação e a descriptografia.

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "G1MQ0YERJ0Q7LPM",
    "requestTimestamp": {
      "epochMillis":1481899949606
    },
    "paymentIntegratorAccountId": "abcdef123456"
  },
  "clientMessage": "echo Me"
}

Criar a resposta

Depois de ler a solicitação echo recebida, você poderá criar a resposta.

private EchoResponse convertEchoRequestStringToEchoResponse(String decryptedRequest);

Ela inclui a mensagem do Google e carimbo de data e hora, além da mensagem do servidor.

{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis":1481899950236
    }
  },
  "clientMessage": "echo Me",
  "serverMessage": "Debug ID 12345"
}

Codificar em base64url e criptografar a resposta

Como todas as solicitações são criptografadas e codificadas em base64url, as chamadas PgpEncryptor.java chamam encrypt para codificar e criptografar a solicitação em base64url.

pgpEncryptor.encrypt(echoResponseString)

Retornar a resposta

A resposta é retornada com um código de status HTTP 202.

return new ResponseEntity<>(pgpEncryptor.encrypt(echoResponseString), HttpStatus.ACCEPTED);

9. Parabéns!

Neste codelab, você estabeleceu a conectividade com a API Payments.