Cómo establecer la conectividad con las APIs de Google en Java

1. Antes de comenzar

Requisitos previos

  • Completaste los pasos 1 y 2 del proceso de implementación.
  • Puedes alojar el servidor Java proporcionado con finalización de TLS usando Google App Engine o tu propia solución en el dominio configurado con Google.
  • Java está instalado en tu entorno.

Lo que aprenderá

  • Cómo verificar la conectividad realizando una solicitud válida a la API de Google Echo
  • Cómo recibir, desencriptar y analizar una solicitud de Google a la API de Partner Hosted echo

2. Configuración y requisitos

Descarga la aplicación

Descarga el código de muestra de Java.

Descripción general de la estructura de la aplicación

El código de muestra de Java se integra con las APIs de Standard Payments de Google. La estructura del proyecto de código de muestra contiene un directorio outbound y un directorio inbound para reflejar la solicitud de eco entrante de Google al socio y la solicitud saliente de la implementación del socio a Google.

Ambos directorios contienen una jerarquía similar en el empaquetado por capas. Las tres capas principales son controller, service y domain.

  • El paquete controller contiene las APIs.
  • El paquete service es responsable de la lógica empresarial, la codificación en base64url y la encriptación.
  • El paquete domain contiene POJO.

Instala las dependencias

Navega al directorio del proyecto y ejecuta el siguiente comando para instalar las dependencias requeridas con el wrapper de Maven. Si usas App Engine, puedes omitir este paso.

./mvnw install

3. Configura el ID de cuenta del integrador de pagos (PIAID)

El ID de la cuenta del integrador de pagos (PIAID) es un identificador que se usa para identificar de forma única tus integraciones. Para comenzar este instructivo, debes haber completado los requisitos previos y haber recibido tu PIAID de Google.

  1. Navega a src/main/resources/application.properties en el directorio del proyecto.
  2. Establece la propiedad payment.integrator.account.id en el PIAID que Google te proporcionó.
payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}

4. Cómo establecer la URL de eco alojada por Google

La URL de echo alojada por Google varía según la API con la que realices la integración. Visita la documentación de referencia de la API para tu tipo de integración específico y copia la URL de la API de eco de diagnóstico. Después de copiar la URL, continúa con los siguientes pasos para actualizarla en el proyecto de Java.

  1. Navega a src/main/resources/application.properties en el directorio del proyecto.
  2. Establece la propiedad API_SERVICE_NAME para que coincida con lo que se encuentra en la documentación para desarrolladores.
google.hosted.echo.url=vgw.googleapis.com/gsp/{API_SERVICE_NAME}/echo/

5. Cómo agregar claves de PGP

Como se muestra a continuación, agrega tus claves de PGP para habilitar la encriptación con PGP.

  • Navega a src/resources/publicKey1.gpg y agrega la clave pública con armadura ASCII al archivo.
  • Navega a src/resources/privateKey1.gpg y agrega la clave privada con armadura ASCII al archivo.
  • Navega a src/resources/passphrase1.txt y agrega la frase de contraseña secreta al archivo.

Cómo agregar claves de PGP

Para habilitar la encriptación con dos claves, agrega tu segunda clave pública a publicKey2.gpg, tu segunda clave privada a privateKey2.gpg y tu segunda frase de contraseña a passphrase.txt. Después de agregar las segundas claves, quita la marca de comentario de las líneas de código comentadas que se encargan de cargar el segundo par de claves en KeyConfig.addPrivateKeyAndPassphrase(...) y KeyConfig.addPublicKeys(...).

Excelente. Ya puedes ejecutar la aplicación.

6. Cómo ejecutar la aplicación

Para iniciar la aplicación, ejecuta el siguiente comando.

  $ ./mvnw spring-boot:run

Si ejecutas una instancia de App Engine preconfigurada, ejecuta este comando.

$ gcloud app deploy

De forma predeterminada, el servidor escuchará en el puerto 8080. Para ver la IU de Swagger de Open API, navega a la siguiente URL.

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

7. Prueba la conectividad de la API de Google Standard Payments Outbound

Ahora que la aplicación se está ejecutando, es momento de probar la conectividad con la API de Google Echo.

Puedes usar Swagger UI o la CLI para ejecutar el siguiente comando y, así, iniciar una llamada desde tu instancia de la aplicación de ejemplo a los servidores de Google. La API de eco de la aplicación de ejemplo acepta una solicitud POST en texto sin formato. Después de recibir la solicitud, se envía una solicitud posterior a la API alojada en Google.

Envía una solicitud a través de la línea de comandos

Reemplaza HOSTNAME por el nombre del host de tu servidor antes de ejecutar el comando.

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

Envía una solicitud en la IU de Swagger

Para enviar una solicitud con la IU de Swagger, ve a https://{APPLICATION_HOST}/swagger-ui y configura el mensaje del cliente en el cuerpo de la solicitud. Haz clic en el botón "Ejecutar" cuando esté todo listo para enviar la solicitud a Google.

Cómo enviar una solicitud de GSP Echo a través de Swagger

Cómo recibir la respuesta

Una solicitud a la API correcta generará la siguiente respuesta de Google.

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

Paso a paso

Ahora que tu servidor envió correctamente una solicitud, revisemos cómo funcionó.

Crea la solicitud

createEchoRequestWithMessage en OutboundEchoService crea la solicitud echo que se envía a la API de Google.

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

La solicitud generada incluye el clientMessage, así como varios campos de valores predeterminados.

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

Codifica y encripta la solicitud en Base64url

Todas las solicitudes están encriptadas y codificadas en base64url. En este ejemplo, PgpEncryptor.java contiene métodos auxiliares que realizan la encriptación y el desencriptado, así como la codificación en base64url por ti. El siguiente método codifica la solicitud y realiza la encriptación con la clave pública de Google.

String encryptedMessage = pgpEncryptor.encrypt(jsonEchoRequestMessage);

Envía la solicitud POST

El mensaje encriptado se envía a través de una solicitud POST.

postStandardPaymentsEchoApi(encryptedMessage)

Desencripta y decodifica en base64url la respuesta, y la devuelve.

La respuesta exitosa de Google está codificada y encriptada en base64url, por lo que también debe decodificarse y desencriptarse antes de que se pueda devolver en texto sin formato. El método decrypt decodifica y descifra la respuesta con Base64url.

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

Devuelve la respuesta

La respuesta se devuelve con un código de estado de respuesta HTTP 202.

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

8. Prueba la conectividad de la API entrante

Para probar la conectividad de la API de eco entrante, Google enviará una solicitud a la API de eco alojada por el socio. Cuando esté todo listo, comunícate con tu punto de contacto de Google para que se envíe la solicitud desde Google.

La prueba de eco se completa cuando puedes leer la solicitud de eco entrante de Google y responder con una respuesta de eco válida.

Paso a paso

Ahora que tu servidor recibió y procesó correctamente una solicitud, revisemos cómo funcionó.

Decodifica y desencripta la solicitud con Base64url

Cuando se recibe una solicitud, PgpEncryptor.java llamará a decrypt, que decodificará en base64url y desencriptará la solicitud.

String decryptedRequest = pgpEncryptor.decrypt(echoRequest);

Recibe la solicitud

Google envió una carga útil de mensaje similar a la siguiente una vez que se decodificó y desencriptó.

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

Cómo crear la respuesta

Una vez que hayas leído correctamente la solicitud de eco entrante, podrás compilar la respuesta.

private EchoResponse convertEchoRequestStringToEchoResponse(String decryptedRequest);

La respuesta incluye el mensaje de Google, así como una marca de tiempo y un mensaje del servidor.

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

Codifica en Base64url y encripta la respuesta

Dado que todas las solicitudes están encriptadas y codificadas en base64url, PgpEncryptor.java llama a encrypt para codificar en base64url y encriptar la solicitud.

pgpEncryptor.encrypt(echoResponseString)

Devuelve la respuesta

La respuesta se devuelve con un código de estado de respuesta HTTP 202.

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

9. ¡Felicitaciones!

En este codelab, estableciste correctamente la conectividad con la API de Payments.