Établir la connectivité avec les API Google en Java

1. Avant de commencer

Prérequis

  • Vous avez terminé les étapes 1 et 2 du processus d'implémentation.
  • Vous pouvez héberger le serveur Java fourni avec terminaison TLS en utilisant Google App Engine ou votre propre solution au niveau du domaine configuré avec Google.
  • Java est installé dans votre environnement.

Ce que vous allez apprendre

  • Découvrez comment vérifier la connectivité en envoyant une requête valide à l'API Google Echo.
  • Découvrez comment recevoir, déchiffrer et analyser une requête envoyée par Google à l'API Echo hébergée par le partenaire.

2. Préparation

Télécharger l'application

Téléchargez l'exemple de code Java.

Présentation de la structure de l'application

L'exemple de code Java s'intègre aux API Standard Payments de Google. La structure du projet de code exemple contient un répertoire outbound ainsi qu'un répertoire inbound pour refléter la requête d'écho entrante de Google au partenaire et la requête sortante de l'implémentation du partenaire à Google.

Ces deux répertoires contiennent une hiérarchie similaire dans l'emballage par couche. Les trois principaux calques sont controller, service et domain.

  • Le package controller contient les API.
  • Le package service est responsable de la logique métier, de l'encodage base64url et du chiffrement.
  • Le package domain contient des POJO.

Installer des dépendances

Accédez au répertoire du projet et exécutez la commande suivante pour installer les dépendances requises à l'aide du wrapper Maven. Si vous utilisez App Engine, vous pouvez ignorer cette étape.

./mvnw install

3. Configurer l'ID de compte de l'intégrateur de paiement (PIAID)

L'ID de compte de l'intégrateur de paiement (PIAID) est un identifiant utilisé pour identifier de manière unique vos intégrations. Vous devriez avoir reçu votre PIAID de Google en remplissant les conditions préalables avant de commencer ce tutoriel.

  1. Accédez à src/main/resources/application.properties dans le répertoire du projet.
  2. Définissez la propriété payment.integrator.account.id sur le PIAID que Google vous a attribué.
payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}

4. Définir l'URL d'écho hébergée par Google

L'URL echo hébergée par Google diffère selon l'API que vous intégrez. Consultez la documentation de référence de l'API pour votre type d'intégration spécifique, puis copiez l'URL de l'API d'écho de diagnostic. Après avoir copié l'URL, passez aux étapes suivantes pour la mettre à jour dans le projet Java.

  1. Accédez à src/main/resources/application.properties dans le répertoire du projet.
  2. Définissez la propriété API_SERVICE_NAME pour qu'elle corresponde à ce qui est indiqué dans la documentation pour les développeurs.
google.hosted.echo.url=vgw.googleapis.com/gsp/{API_SERVICE_NAME}/echo/

5. Ajouter des clés PGP

Comme indiqué ci-dessous, ajoutez vos clés PGP pour activer le chiffrement PGP.

  • Accédez à src/resources/publicKey1.gpg et ajoutez la clé publique ASCII armored au fichier.
  • Accédez à src/resources/privateKey1.gpg et ajoutez la clé privée ASCII armored au fichier.
  • Accédez à src/resources/passphrase1.txt et ajoutez la phrase secrète au fichier.

Ajouter des clés PGP

Pour activer le chiffrement à double clé, ajoutez votre deuxième clé publique à publicKey2.gpg, votre deuxième clé privée à privateKey2.gpg et votre deuxième phrase secrète à passphrase.txt. Après avoir ajouté les deuxièmes clés, supprimez les commentaires des lignes de code responsables du chargement de la deuxième paire de clés dans KeyConfig.addPrivateKeyAndPassphrase(...) et KeyConfig.addPublicKeys(...).

Parfait, vous êtes prêt à exécuter l'application.

6. Exécuter l'application

Pour démarrer l'application, exécutez la commande suivante.

  $ ./mvnw spring-boot:run

Si vous exécutez une instance App Engine préconfigurée, exécutez plutôt cette commande.

$ gcloud app deploy

Par défaut, le serveur écoute sur le port 8080. Pour afficher l'UI Swagger de l'API Open, accédez à l'URL ci-dessous.

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

7. Tester la connectivité de l'API Google Standard Payments Outbound

Maintenant que l'application est en cours d'exécution, il est temps de tester la connectivité avec l'API Google Echo.

Vous pouvez utiliser l'interface utilisateur Swagger ou la CLI pour exécuter la commande suivante afin d'initier un appel depuis votre instance de l'application exemple vers les serveurs de Google. L'exemple d'API d'écho d'application accepte une requête POST en texte brut. Une fois la requête reçue, une requête ultérieure est envoyée à l'API hébergée par Google.

Envoyer une requête via la ligne de commande

Remplacez HOSTNAME par le nom de l'hôte de votre serveur avant d'exécuter la commande.

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

Envoyer une requête dans l'UI Swagger

Pour envoyer une requête avec Swagger UI, accédez à https://{APPLICATION_HOST}/swagger-ui et définissez le message client dans le corps de la requête. Cliquez sur le bouton "Exécuter" lorsque vous êtes prêt à envoyer la demande à Google.

Envoyer une requête GSP Echo via Swagger

Recevoir la réponse

Une requête d'API réussie génère la réponse suivante de Google.

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

Pas-à-pas

Maintenant qu'une requête a été envoyée par votre serveur, examinons comment cela a fonctionné.

Créer la demande

createEchoRequestWithMessage dans OutboundEchoService crée la requête echo envoyée à l'API de Google.

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

La requête générée inclut clientMessage, ainsi que plusieurs champs de valeurs par défaut.

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

Encoder et chiffrer la requête en Base64url

Toutes les requêtes sont chiffrées et encodées en base64url. Dans cet exemple, PgpEncryptor.java contient des méthodes d'assistance qui effectuent le chiffrement et le déchiffrement, ainsi que l'encodage base64url pour vous. La méthode ci-dessous encode la requête et effectue le chiffrement à l'aide de la clé publique de Google.

String encryptedMessage = pgpEncryptor.encrypt(jsonEchoRequestMessage);

Envoyer la requête POST

Le message chiffré est envoyé via une requête POST.

postStandardPaymentsEchoApi(encryptedMessage)

Déchiffre et décode la réponse en base64url, puis renvoie la réponse.

La réponse de Google est encodée et chiffrée en base64url. Elle doit donc être décodée et déchiffrée avant de pouvoir être renvoyée en texte brut. La méthode decrypt décode en base64url et déchiffre la réponse.

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

Renvoyer la réponse

La réponse est renvoyée avec un code d'état HTTP 202.

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

8. Tester la connectivité de l'API Inbound

Pour tester la connectivité de l'API Echo entrante, Google enverra une requête à l'API Echo hébergée par le partenaire. Lorsque vous serez prêt, veuillez contacter votre point de contact Google pour déclencher cette demande depuis Google.

Le test d'écho est terminé lorsque vous pouvez lire la demande d'écho entrante de Google et y répondre avec une réponse d'écho valide.

Pas-à-pas

Maintenant qu'une requête a été reçue et traitée par votre serveur, examinons comment cela s'est passé.

Décoder et déchiffrer la requête en base64url

Lorsqu'une requête est reçue, PgpEncryptor.java appelle decrypt, qui décode et déchiffre la requête en base64url.

String decryptedRequest = pgpEncryptor.decrypt(echoRequest);

Recevoir la demande

Une fois décodée et déchiffrée, la charge utile du message envoyé par Google ressemble à ce qui suit.

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

Créer la réponse

Une fois que vous avez lu la demande d'écho entrante, vous êtes prêt à créer la réponse.

private EchoResponse convertEchoRequestStringToEchoResponse(String decryptedRequest);

La réponse inclut le message de Google, ainsi qu'un code temporel et un message du serveur.

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

Encoder et chiffrer la réponse en base64url

Étant donné que toutes les requêtes sont chiffrées et encodées en base64url, PgpEncryptor.java appelle encrypt pour encoder en base64url et chiffrer la requête.

pgpEncryptor.encrypt(echoResponseString)

Renvoyer la réponse

La réponse est renvoyée avec un code d'état HTTP 202.

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

9. Félicitations !

Dans cet atelier de programmation, vous avez réussi à établir une connectivité avec l'API Payments.