É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 la terminaison TLS à l'aide de Google App Engine ou de votre propre solution sur le domaine configuré avec Google.
  • Java est installé dans votre environnement.

Ce que vous allez apprendre

  • Vérifier la connectivité en envoyant une requête valide à l'API Google Echo
  • Recevoir, déchiffrer et analyser une requête de Google à l'API Partner Hosted Echo

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 Google Payments standards. L'exemple de structure de projet de code contient un répertoire outbound et un répertoire inbound pour refléter la demande d'écho entrante de Google vers le partenaire et la demande sortante de l'implémentation du partenaire vers Google.

Ces deux répertoires contiennent une hiérarchie similaire dans le packaging par couche. Les trois couches principales 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 du compte de l'intégrateur de paiement (PIAID)

L'ID de compte de l'intégrateur de paiement (PIAID) est un identifiant permettant d'identifier de manière unique vos intégrations. Vous devriez avoir reçu votre PIAID de la part de Google après avoir rempli 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 l'ID PIA qui vous a été attribué par Google.
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 correspondant à votre type d'intégration spécifique et copiez l'URL de l'API Echo de diagnostic. Une fois l'URL copiée, 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 à celle indiquée dans la documentation destinée aux 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 blindée ASCII au fichier.
  • Accédez à src/resources/privateKey1.gpg et ajoutez la clé privée blindée ASCII au fichier.
  • Accédez à src/resources/passphrase1.txt et ajoutez la phrase secrète 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, puis votre deuxième phrase secrète à passphrase.txt. Après avoir ajouté les deuxièmes clés, décommentez les lignes de code commentées qui sont chargées de charger 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 d'OpenAPI, 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'UI Swagger ou la CLI pour exécuter la commande suivante afin d'effectuer un appel de votre instance de l'application exemple vers les serveurs de Google. L'exemple d'API echo 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 l'interface utilisateur Swagger, accédez à https://{APPLICATION_HOST}/swagger-ui et définissez le message client dans le corps de la requête. Lorsque vous êtes prêt à envoyer la requête à Google, cliquez sur le bouton "Exécuter".

Envoyer une requête Echo GSP via Swagger

Recevoir la réponse

Si la requête d'API aboutit, Google renvoie la réponse suivante.

{
   "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 le fonctionnement.

Créer la requête

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 le clientMessage, ainsi que plusieurs champs de valeur 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!"
}

Encodage et chiffrement de 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. La méthode ci-dessous encode la requête et procède au 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échiffrer et décoder base64url la réponse et la renvoyer

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 base64url décode 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 de réponse HTTP 202.

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

8. Tester la connectivité de l'API entrante

Pour tester la connectivité de l'API d'écho entrant, Google enverra une requête à l'API Partner Hosted Echo. Lorsque vous êtes prêt, veuillez vous adresser à votre contact Google pour déclencher cette demande de la part de Google.

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

pas-à-pas

Maintenant qu'une requête a été reçue et géré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écodera et déchiffrera la requête en base64url.

String decryptedRequest = pgpEncryptor.decrypt(echoRequest);

Recevoir la requête

Une fois décodée et déchiffrée, Google a envoyé une charge utile de message semblable à celle-ci :

{
  "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 requête 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 en base64url, PgpEncryptor.java appelle encrypt pour les encoder en base64url et les chiffrer.

pgpEncryptor.encrypt(echoResponseString)

Renvoyer la réponse

La réponse est renvoyée avec un code d'état de réponse 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.