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 di Google all'API Partner Hosted echo.
2. Configurazione e requisiti
Scarica l'applicazione
Scarica il codice di esempio Java.
Panoramica della struttura dell'applicazione
Il codice di esempio Java si integra con le API standard per i pagamenti di Google. La struttura del progetto di codice di esempio contiene una directory outbound
e una directory inbound
per riflettere la richiesta di eco in entrata da Google al partner e la richiesta in uscita dell'implementazione del partner a Google.
Entrambe queste directory contengono una gerarchia simile nella pacchettizzazione 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 dipendenze
Passa alla directory del progetto ed esegui questo comando per installare le dipendenze richieste utilizzando Maven Wrapper. Se utilizzi App Engine, puoi saltare questo passaggio.
./mvnw install
3. Configurare l'ID account di integrazione dei pagamenti (PIAID)
L'ID account integratore pagamenti (PIAID
) è un identificatore utilizzato per identificare in modo univoco le integrazioni. Prima di iniziare questo tutorial, dovresti aver ricevuto il PIAID da Google completando i prerequisiti.
- Vai a
src/main/resources/application.properties
nella directory del progetto. - Imposta la proprietà
payment.integrator.account.id
sul PIAID che ti è stato inviato da Google.
payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}
4. Imposta l'URL echo ospitato da Google
L'URL echo
ospitato su Google varia a seconda dell'API con cui vuoi eseguire l'integrazione. Consulta la documentazione di riferimento dell'API per il tipo di integrazione specifico e copia l'URL dell'API diagnostica echo. Dopo aver copiato l'URL, procedi con i passaggi successivi per aggiornarlo nel progetto Java.
- Vai a
src/main/resources/application.properties
nella directory del progetto. - 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 armorizzata ASCII al file. - Vai a
src/resources/privateKey1.gpg
e aggiungi la chiave privata armorizzata ASCII al file. - Vai a
src/resources/passphrase1.txt
e aggiungi la passphrase segreta al file.
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 inserito la seconda chiave, 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 eseguire l'applicazione.
6. Esegui l'applicazione
Per avviare l'applicazione, esegui questo comando.
$ ./mvnw spring-boot:run
Se invece stai eseguendo un'istanza di App Engine preconfigurata, esegui questo comando.
$ gcloud app deploy
Per impostazione predefinita, il server rimane in ascolto sulla porta 8080. Per visualizzare l'interfaccia utente Swagger API aperta, vai all'URL di seguito.
https://{APPLICATION_HOST}/swagger-ui.html
7. Test della 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 l'interfaccia utente Swagger o l'interfaccia a riga di comando per eseguire il comando seguente in modo da avviare una chiamata dalla tua 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, viene inviata una richiesta successiva all'API ospitata da Google.
Invia una richiesta tramite la 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
Invia una richiesta nella UI Swagger
Per inviare una richiesta con UI Swagger, vai a https://{APPLICATION_HOST}/swagger-ui
e imposta il messaggio client nel corpo della richiesta. Fai clic sul pulsante "Esegui" quando tutto è pronto per inviare la richiesta a Google.
Ricevere la risposta
Una richiesta API riuscita genererà la seguente risposta da parte di Google.
{
"responseHeader":{
"responseTimestamp":"1606710026723"
},
"clientMessage":"Hello from Bank Little Bear!",
"serverMessage":"Server message."
}
Dettagli
Ora che una richiesta è stata inviata dal tuo server, vediamo come ha funzionato.
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 di 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 e cripta la richiesta in Base64url
Tutte le richieste sono criptate e con codifica Base64url. In questo esempio, PgpEncryptor.java
contiene metodi helper che eseguono crittografia e decriptazione, nonché la codifica Base64url. 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 base64url decodificano la risposta e restituiscono la risposta
La risposta positiva di Google è codificata e criptata in base64url, quindi deve essere decodificata e decriptata anche per poter essere restituita come 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 di risposta HTTP 202.
return new ResponseEntity<>(decryptedData, HttpStatus.ACCEPTED);
8. Testare la connettività API in entrata
Per testare la connettività dell'API echo in entrata, Google invierà una richiesta all'API Partner Hosted echo. Quando è tutto pronto, collabora con il tuo punto di contatto Google per attivare questa richiesta da parte di Google.
Il test eco è completo quando sei in grado di leggere la richiesta di eco in entrata di Google e rispondere con una risposta eco valida.
Dettagli
Ora che il tuo server ha ricevuto e gestito correttamente una richiesta, vediamo come ha funzionato.
Base64url decodifica e decripta la richiesta
Quando viene ricevuta una richiesta, PgpEncryptor.java
chiama decrypt
, che base64url decodifica e decripta la richiesta.
String decryptedRequest = pgpEncryptor.decrypt(echoRequest);
Ricevi la richiesta
Una volta decodificato e decriptato, Google ha inviato un payload del 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 eco in entrata, puoi creare la risposta.
private EchoResponse convertEchoRequestStringToEchoResponse(String decryptedRequest);
La risposta include il messaggio di Google, un timestamp e un messaggio del server.
{ "responseHeader": { "responseTimestamp": { "epochMillis":1481899950236 } }, "clientMessage": "echo Me", "serverMessage": "Debug ID 12345" }
Codifica e cripta la risposta con il formato Base64url
Poiché tutte le richieste sono criptate e con codifica Base64url, PgpEncryptor.java
chiama encrypt
alla codifica base64url e cripta la richiesta.
pgpEncryptor.encrypt(echoResponseString)
Restituire la risposta
La risposta viene restituita con un codice di stato di 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.