Cette page a été traduite par l'API Cloud Translation.

Établir la connectivité avec les API Google en Java

1. Avant de commencer

Conditions préalables

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

Ce que vous allez apprendre

Comment vérifier la connectivité en envoyant une requête valide à l'API Google echo.
Recevoir, déchiffrer et analyser une requête envoyée de Google à l'API Echo hébergée par un partenaire

2. Prérequis

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

Ces deux répertoires contiennent une hiérarchie similaire en termes de 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 de Maven Wrapper. Si vous utilisez App Engine, vous pouvez ignorer cette étape.

./mvnw install

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

L'ID de compte de l'intégrateur de paiement (PIAID) est un identifiant permettant d'identifier vos intégrations de manière unique. Google vous a envoyé votre PIAID en remplissant les conditions préalables avant de commencer ce tutoriel.

Accédez à src/main/resources/application.properties dans le répertoire du projet.
Définissez la propriété payment.integrator.account.id sur le PIAID qui vous a été envoyé par Google.

payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}

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

L'URL echo hébergée par Google diffère selon l'API avec laquelle vous effectuez l'intégration. Consultez la documentation de référence de l'API correspondant à votre type d'intégration et copiez l'URL de l'API Diagnostic echo. Après avoir copié l'URL, passez aux étapes suivantes pour la mettre à jour dans le projet Java.

Accédez à src/main/resources/application.properties dans le répertoire du projet.
Définissez la propriété API_SERVICE_NAME pour qu'elle corresponde à ce qui est disponible 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 à deux clés, ajoutez votre deuxième clé publique à publicKey2.gpg, ajoutez votre deuxième clé privée à privateKey2.gpg, puis ajoutez votre deuxième phrase secrète à passphrase.txt. Après avoir ajouté les deuxièmes clés, annulez la mise en commentaire des lignes de code commentées qui sont 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 Open API, accédez à l'URL ci-dessous.

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

7. Tester la connectivité de l'API sortante standard Google pour les paiements

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

Vous pouvez utiliser l'UI ou la CLI Swagger pour exécuter la commande suivante afin d'appeler les serveurs de Google à partir de votre instance de l'exemple d'application. L'API echo de l'exemple d'application accepte une requête POST en texte brut. Après avoir reçu la requête, 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 votre hôte 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'UI Swagger, accédez à https://{APPLICATION_HOST}/swagger-ui et définissez le message du client dans le corps de la requête. Cliquez sur le bouton "Exécuter" lorsque vous êtes prêt à envoyer la requête à Google.

Envoyer une demande d'écho GSP via Swagger

Recevoir la réponse

Si la requête aboutit, Google génère la réponse suivante.

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

Itinéraire détaillé

Maintenant que votre serveur a envoyé une requête, examinons comment elle a fonctionné.

Créer la requête

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

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

La requête générée comprend 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!"
}

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 à votre place. 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échiffrer et base64url décoder la réponse et renvoyer la réponse

La réponse positive de Google est encodée et chiffrée en base64url. Elle doit donc également ê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é des API entrantes

Pour tester la connectivité de l'API d'écho entrant, Google envoie une requête à l'API d'écho hébergée par un partenaire. Lorsque vous serez prêt, rapprochez-vous de 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 par une réponse d'écho valide.

Itinéraire détaillé

Maintenant que votre serveur a reçu et traité une demande, examinons comment elle a fonctionné.

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

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

String decryptedRequest = pgpEncryptor.decrypt(echoRequest);

Recevoir la requête

Une fois décodé et déchiffré, Google a envoyé une charge utile de message semblable à la suivante.

{
  "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 avec succès 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 et chiffrer les requêtes en base64url.

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 la connectivité avec l'API Payments.