1. 시작하기 전에
기본 요건
- 구현 절차의 1단계와 2단계를 완료했습니다.
- Google App Engine 또는 Google로 구성된 도메인에서 자체 솔루션을 사용하여 TLS 종료로 제공된 자바 서버를 호스팅할 수 있습니다.
- 사용자 환경에 자바가 설치되어 있습니다.
학습할 내용
- Google echo API에 유효한 요청을 전송하여 연결을 확인하는 방법
- Google에서 Partner Hosted echo API로 요청을 수신, 복호화, 파싱하는 방법
2. 설정 및 요구사항
애플리케이션 다운로드
자바 샘플 코드를 다운로드합니다.
애플리케이션 구조 개요
Java 샘플 코드는 Google의 Standard Payments API와 통합됩니다. 샘플 코드 프로젝트 구조에는 Google에서 파트너에게 보내는 인바운드 에코 요청과 파트너 구현에서 Google로 보내는 아웃바운드 요청을 반영하는 inbound 디렉터리와 outbound 디렉터리가 포함되어 있습니다.
두 디렉터리 모두 레이어별로 패키징하는 데 비슷한 계층 구조를 포함하고 있습니다. 세 가지 기본 레이어는 controller, service, domain입니다.
controller패키지에는 API가 포함되어 있습니다.service패키지는 비즈니스 로직, base64url 인코딩 및 암호화를 담당합니다.domain패키지에는 POJO가 포함되어 있습니다.
종속 항목 설치
프로젝트 디렉터리로 이동하고 다음 명령어를 실행하여 Maven Wrapper를 사용하여 필요한 종속 항목을 설치합니다. App Engine을 사용하는 경우 이 단계를 건너뛸 수 있습니다.
./mvnw install
3. 결제 통합업체 계정 ID (PIAID) 구성
결제 통합업체 계정 ID (PIAID)는 통합을 고유하게 식별하는 데 사용되는 식별자입니다. 이 튜토리얼을 시작하기 전에 기본 요건을 완료하여 Google로부터 PIAID를 받으셨을 것입니다.
- 프로젝트 디렉터리에서
src/main/resources/application.properties로 이동합니다. payment.integrator.account.id속성을 Google에서 발급한 PIAID로 설정합니다.
payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}
4. Google 호스팅 에코 URL 설정
Google에서 호스팅하는 echo URL은 통합하는 API에 따라 다릅니다. 특정 통합 유형에 대한 API 참조 문서를 방문하여 진단 에코 API의 URL을 복사합니다. URL을 복사한 후 다음 단계로 이동하여 Java 프로젝트에서 URL을 업데이트합니다.
- 프로젝트 디렉터리에서
src/main/resources/application.properties로 이동합니다. - 개발자 문서에 설명된 것과 일치하도록
API_SERVICE_NAME속성을 설정합니다.
google.hosted.echo.url=vgw.googleapis.com/gsp/{API_SERVICE_NAME}/echo/
5. PGP 키 추가
아래와 같이 PGP 키를 추가하여 PGP 암호화를 사용 설정하세요.
src/resources/publicKey1.gpg로 이동하여 파일에 ASCII armored 공개 키를 추가합니다.src/resources/privateKey1.gpg로 이동하여 파일에 ASCII armored 비공개 키를 추가합니다.src/resources/passphrase1.txt로 이동하여 파일에 보안 비밀 암호를 추가합니다.
이중 키 암호화를 사용 설정하려면 publicKey2.gpg에 두 번째 공개 키를 추가하고 privateKey2.gpg에 두 번째 비공개 키를 추가하고 passphrase.txt에 두 번째 암호를 추가하세요. 두 번째 키를 추가한 후 KeyConfig.addPrivateKeyAndPassphrase(...) 및 KeyConfig.addPublicKeys(...)의 두 번째 키 쌍을 로드하는 주석 처리된 코드 줄의 주석 처리를 삭제합니다.
이제 애플리케이션을 실행할 준비가 되었습니다.
6. 애플리케이션 실행
다음 명령어를 실행하여 애플리케이션을 시작합니다.
$ ./mvnw spring-boot:run
사전 구성된 App Engine 인스턴스를 실행하는 경우 이 명령어를 대신 실행합니다.
$ gcloud app deploy
기본적으로 서버는 포트 8080에서 수신 대기합니다. Open API Swagger UI를 보려면 아래 URL로 이동하세요.
https://{APPLICATION_HOST}/swagger-ui.html
7. Google Standard Payments Outbound API 연결 테스트
이제 애플리케이션이 실행 중이므로 Google echo API와의 연결을 테스트할 차례입니다.
Swagger UI 또는 CLI를 사용하여 다음 명령어를 실행하여 샘플 애플리케이션의 인스턴스에서 Google 서버로 호출을 시작할 수 있습니다. 샘플 애플리케이션 echo API는 일반 텍스트로 POST 요청을 허용합니다. 요청을 받으면 후속 요청이 Google 호스팅 API로 전송됩니다.
명령줄을 통해 요청 보내기
명령어를 실행하기 전에 HOSTNAME을 서버 호스트 이름으로 바꿉니다.
$ curl -X POST -H 'Content-Type: text/plain' -d 'Hello from Partner Bank!' https://{HOSTNAME}/echo
Swagger UI에서 요청 보내기
Swagger UI로 요청을 보내려면 https://{APPLICATION_HOST}/swagger-ui로 이동하여 요청 본문에서 클라이언트 메시지를 설정합니다. Google에 요청을 보낼 준비가 되면 '실행' 버튼을 클릭합니다.
응답 수신
API 요청이 성공하면 Google에서 다음과 같은 응답을 받게 됩니다.
{
"responseHeader":{
"responseTimestamp":"1606710026723"
},
"clientMessage":"Hello from Bank Little Bear!",
"serverMessage":"Server message."
}
단계별 보기
이제 서버에서 요청을 성공적으로 전송했으므로 어떻게 작동하는지 살펴보겠습니다.
요청 빌드
OutboundEchoService의 createEchoRequestWithMessage는 Google의 API로 전송된 echo 요청을 빌드합니다.
String jsonEchoRequestMessage = objectMapper.writeValueAsString(createEchoRequestWithMessage(message));
생성된 요청에는 clientMessage와 여러 기본값 필드가 포함됩니다.
{
"requestHeader":{
"protocolVersion":{
"major":1,
"minor":0,
"revision":0
},
"requestId":"ddfe0fd0-ffdc-4fcf-991a-f0611ec83970",
"requestTimestamp":"1606715389040"
},
"clientMessage":"Hello from Bank Little Bear!"
}
요청을 Base64url로 인코딩 및 암호화
모든 요청은 암호화되고 base64url로 인코딩됩니다. 이 샘플에서 PgpEncryptor.java에는 base64url 인코딩은 물론 암호화 및 복호화도 수행하는 도우미 메서드가 포함되어 있습니다. 아래 메서드는 요청을 인코딩하고 Google의 공개 키를 사용하여 암호화를 수행합니다.
String encryptedMessage = pgpEncryptor.encrypt(jsonEchoRequestMessage);
POST 요청 보내기
암호화된 메시지는 POST 요청을 통해 전송됩니다.
postStandardPaymentsEchoApi(encryptedMessage)
응답을 복호화하고 base64url로 디코딩하여 응답 반환
Google의 성공적인 응답은 base64url로 인코딩되고 암호화되므로 일반 텍스트로 반환되기 전에 디코딩 및 복호화해야 합니다. decrypt 메서드 base64url은 응답을 디코딩하고 복호화합니다.
String decryptedData =
pgpEncryptor.decrypt(postStandardPaymentsEchoApi(encryptedMessage).getBody());
응답 반환
응답이 202 HTTP 응답 상태 코드와 함께 반환됩니다.
return new ResponseEntity<>(decryptedData, HttpStatus.ACCEPTED);
8. 인바운드 API 연결 테스트
인바운드 에코 API 연결을 테스트하기 위해 Google에서 Partner Hosted echo API에 요청을 보냅니다. 준비가 되면 Google 담당자와 협력하여 Google에서 이 요청을 트리거하세요.
Google의 인바운드 에코 요청을 읽고 유효한 에코 응답으로 응답할 수 있으면 에코 테스트가 완료된 것입니다.
단계별 보기
이제 서버가 성공적으로 요청을 수신하고 처리했으므로 어떻게 작동하는지 살펴보겠습니다.
요청을 Base64url 디코딩 및 복호화
요청이 수신되면 PgpEncryptor.java은 decrypt를 호출하여 요청을 base64url로 디코딩하고 복호화합니다.
String decryptedRequest = pgpEncryptor.decrypt(echoRequest);
요청 수신
Google에서는 디코딩 및 복호화된 후 다음과 유사한 메시지 페이로드를 전송했습니다.
{
"requestHeader": {
"protocolVersion": {
"major": 1
},
"requestId": "G1MQ0YERJ0Q7LPM",
"requestTimestamp": {
"epochMillis":1481899949606
},
"paymentIntegratorAccountId": "abcdef123456"
},
"clientMessage": "echo Me"
}
응답 빌드
인바운드 에코 요청을 성공적으로 읽었다면 응답을 빌드할 준비가 된 것입니다.
private EchoResponse convertEchoRequestStringToEchoResponse(String decryptedRequest);
응답에는 Google의 메시지뿐 아니라 타임스탬프 및 서버의 메시지가 포함됩니다.
{
"responseHeader": {
"responseTimestamp": {
"epochMillis":1481899950236
}
},
"clientMessage": "echo Me",
"serverMessage": "Debug ID 12345"
}
응답을 Base64url로 인코딩 및 암호화
모든 요청이 암호화되고 base64url이 인코딩되므로, PgpEncryptor.java는 encrypt를 호출하여 요청을 base64url로 인코딩하고 암호화합니다.
pgpEncryptor.encrypt(echoResponseString)
응답 반환
응답이 202 HTTP 응답 상태 코드와 함께 반환됩니다.
return new ResponseEntity<>(pgpEncryptor.encrypt(echoResponseString), HttpStatus.ACCEPTED);
9. 축하합니다.
이 Codelab을 통해 Payments API와의 연결을 성공적으로 설정했습니다.