Come stabilire la connettività con le API di Google in Java

1. Prima di iniziare

Prerequisiti

  • Hai completato i passaggi 1 e 2 della procedura di implementazione.
  • Puoi ospitare il server Java fornito con terminazione TLS utilizzando Google App Engine o la tua soluzione nel dominio configurato con Google.
  • Java è installato nel tuo ambiente.

Obiettivi didattici

  • Come verificare la connettività inviando una richiesta valida all'API Google Echo.
  • Come ricevere, decriptare e analizzare una richiesta da Google all'API echo ospitata dal partner.

2. Configurazione e requisiti

Scaricare l'applicazione

Scarica il codice di esempio Java.

Panoramica della struttura dell'applicazione

Il codice di esempio Java si integra con le API Standard Payments di Google. La struttura del progetto di codice di esempio contiene una directory outbound e una directory inbound per riflettere la richiesta di echo in entrata da Google al partner e la richiesta in uscita dall'implementazione del partner a Google.

Entrambe le directory contengono una gerarchia simile nel packaging per livello. I tre livelli principali sono controller, service e domain.

  • Il pacchetto controller contiene le API.
  • Il pacchetto service è responsabile della logica di business, della codifica base64url e della crittografia.
  • Il pacchetto domain contiene POJO.

Installa le dipendenze

Vai alla directory del progetto ed esegui il seguente comando per installare le dipendenze richieste utilizzando Maven Wrapper. Se utilizzi App Engine, puoi saltare questo passaggio.

./mvnw install

3. Configura l'ID account dell'integratore dei pagamenti (PIAID)

L'ID account dell'integratore dei pagamenti (PIAID) è un identificatore utilizzato per identificare in modo univoco le tue integrazioni. Prima di iniziare questo tutorial, dovresti aver ricevuto il tuo PIAID da Google completando i prerequisiti.

  1. Vai a src/main/resources/application.properties nella directory del progetto.
  2. Imposta la proprietà payment.integrator.account.id sul PIAID che ti è stato emesso da Google.
payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}

4. Impostare l'URL di echo ospitato da Google

L'URL echo ospitato da Google varia a seconda dell'API con cui esegui l'integrazione. Consulta la documentazione di riferimento dell'API per il tuo tipo di integrazione specifico e copia l'URL dell'API diagnostica echo. Dopo aver copiato l'URL, vai ai passaggi successivi per aggiornarlo nel progetto Java.

  1. Vai a src/main/resources/application.properties nella directory del progetto.
  2. Imposta la proprietà API_SERVICE_NAME in modo che corrisponda a quanto indicato nella documentazione per gli sviluppatori.
google.hosted.echo.url=vgw.googleapis.com/gsp/{API_SERVICE_NAME}/echo/

5. Aggiungi chiavi PGP

Come mostrato di seguito, aggiungi le tue chiavi PGP per attivare la crittografia PGP.

  • Vai a src/resources/publicKey1.gpg e aggiungi la chiave pubblica con crittografia ASCII al file.
  • Passa a src/resources/privateKey1.gpg e aggiungi al file la chiave privata con protezione ASCII.
  • Vai a src/resources/passphrase1.txt e aggiungi la passphrase del secret al file.

Aggiunta di chiavi PGP

Per attivare la crittografia a doppia chiave, aggiungi la seconda chiave pubblica a publicKey2.gpg, la seconda chiave privata a privateKey2.gpg e la seconda passphrase a passphrase.txt. Dopo aver aggiunto le seconde chiavi, rimuovi il commento dalle righe di codice commentate che sono responsabili del caricamento della seconda coppia di chiavi in KeyConfig.addPrivateKeyAndPassphrase(...) e KeyConfig.addPublicKeys(...).

Ottimo, è tutto pronto per l'esecuzione dell'applicazione.

6. Esegui l'applicazione

Per avviare l'applicazione, esegui il seguente comando.

  $ ./mvnw spring-boot:run

Se stai eseguendo un'istanza di App Engine preconfigurata, esegui questo comando.

$ gcloud app deploy

Per impostazione predefinita, il server rimarrà in ascolto sulla porta 8080. Per visualizzare l'interfaccia Swagger di Open API, vai all'URL riportato di seguito.

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

7. Testare la connettività dell'API Google Standard Payments in uscita

Ora che l'applicazione è in esecuzione, è il momento di testare la connettività con l'API Google Echo.

Puoi utilizzare Swagger UI o l'interfaccia a riga di comando per eseguire il seguente comando per avviare una chiamata dall'istanza dell'applicazione di esempio ai server di Google. L'API echo dell'applicazione di esempio accetta una richiesta POST in testo non crittografato. Dopo aver ricevuto la richiesta, ne viene inviata una successiva all'API ospitata da Google.

Invia una richiesta dalla riga di comando

Sostituisci HOSTNAME con il nome dell'host del server prima di eseguire il comando.

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

Inviare una richiesta in Swagger UI

Per inviare una richiesta con l'interfaccia utente di Swagger, vai a https://{APPLICATION_HOST}/swagger-ui e imposta il messaggio del client nel corpo della richiesta. Fai clic sul pulsante "Esegui" quando è tutto pronto per inviare la richiesta a Google.

Invio di una richiesta Echo GSP tramite Swagger

Ricevi la risposta

Una richiesta API andata a buon fine comporterà la seguente risposta da parte di Google.

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

Istruzioni dettagliate

Ora che una richiesta è stata inviata correttamente dal server, vediamo come funziona.

Crea la richiesta

createEchoRequestWithMessage in OutboundEchoService crea la richiesta echo inviata all'API di Google.

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

La richiesta generata include clientMessage e diversi campi con valori predefiniti.

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

Codifica Base64URL e cripta la richiesta

Tutte le richieste sono criptate e codificate in base64url. In questo esempio, PgpEncryptor.java contiene metodi di assistenza che eseguono la crittografia e la decrittografia, nonché la codifica base64url per te. Il metodo riportato di seguito codifica la richiesta ed esegue la crittografia utilizzando la chiave pubblica di Google.

String encryptedMessage = pgpEncryptor.encrypt(jsonEchoRequestMessage);

Invia la richiesta POST

Il messaggio criptato viene inviato tramite una richiesta POST.

postStandardPaymentsEchoApi(encryptedMessage)

Decripta e decodifica la risposta con base64url e restituisci la risposta

La risposta di Google positiva è base64url codificata e criptata, quindi deve essere decodificata e decriptata anch'essa prima di poter essere restituita in testo non crittografato. Il metodo decrypt base64url decodifica e decripta la risposta.

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

Restituire la risposta

La risposta viene restituita con un codice di stato risposta HTTP 202.

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

8. Testare la connettività dell'API in entrata

Per testare la connettività dell'API echo in entrata, Google invierà una richiesta all'API echo ospitata dal partner. Quando è tutto pronto, collabora con il tuo punto di contatto Google per attivare questa richiesta da parte di Google.

Il test di eco è completato quando riesci a leggere la richiesta di eco in entrata da Google e a rispondere con una risposta di eco valida.

Istruzioni dettagliate

Ora che la richiesta è stata ricevuta e gestita dal server, vediamo come ha funzionato.

Decodifica Base64url e decripta la richiesta

Quando viene ricevuta una richiesta, PgpEncryptor.java chiama decrypt, che decodifica e decripta la richiesta con base64url.

String decryptedRequest = pgpEncryptor.decrypt(echoRequest);

Ricevi la richiesta

Una volta decodificato e decriptato, Google ha inviato un payload di messaggio simile al seguente.

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

Crea la risposta

Dopo aver letto correttamente la richiesta di echo in entrata, puoi creare la risposta.

private EchoResponse convertEchoRequestStringToEchoResponse(String decryptedRequest);

La risposta include il messaggio di Google, nonché un timestamp e un messaggio del server.

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

Base64url codifica e cripta la risposta

Poiché tutte le richieste sono criptate e codificate in base64url, PgpEncryptor.java chiama encrypt per codificare la richiesta in base64url e criptarla.

pgpEncryptor.encrypt(echoResponseString)

Restituisci la risposta

La risposta viene restituita con un codice di stato della risposta HTTP 202.

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

9. Complimenti!

In questo codelab, hai stabilito correttamente la connettività con l'API Payments.