如何使用 Java 與 Google API 建立連線

1. 事前準備

必要條件

  • 您已完成導入程序的步驟 1 和 2。
  • 您可以使用 Google App Engine 或在透過 Google 設定的網域中使用自己的解決方案，代管採用 TLS 終止功能的 Java 伺服器。
  • 您的環境已安裝 Java。

課程內容

  • 如何向 Google echo API 發出有效要求來驗證連線。
  • 如何接收、解密及剖析來自 Google 傳送至 Partner Hosted echo API 的要求。

2. 設定和需求

下載應用程式

下載 Java 程式碼範例。

應用程式結構總覽

Java 範例程式碼可與 Google 的 Standard Payments API 整合。範例程式碼專案結構包含 outbound 目錄和 inbound 目錄，分別用於反映 Google 傳送至合作夥伴的回音內送要求，以及合作夥伴實作傳送至 Google 的回音外送要求。

這兩個目錄在依層級分類的包裝方式上，都包含類似的階層。這三個主要層是 controller、service 和 domain。

  • controller 套件包含 API。
  • service 套件負責商業邏輯、base64url 編碼和加密。
  • domain 套件包含 POJO。

安裝依附元件

前往專案目錄，並執行下列指令，使用 Maven Wrapper 安裝所需的依附元件。如果您使用的是 App Engine，則可略過這個步驟。

./mvnw install

3. 設定付款整合商帳戶 ID (PIAID)

付款整合商帳戶 ID (PIAID) 是用來識別整合項目的 ID。開始本教學課程前，請先完成必備條件，並確認您已透過 Google 取得 PIAID。

  1. 前往專案目錄中的 src/main/resources/application.properties。
  2. 將屬性 payment.integrator.account.id 設為 Google 核發的 PIAID。
payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}

4. 設定 Google 代管的 echo 網址

Google 代管的 echo 網址會因您要整合的 API 而有所不同。請參閱特定整合類型的 API 參考說明文件，然後複製 diagnostic echo API 的網址。複製網址後，請繼續下一步，在 Java 專案中更新網址。

  1. 前往專案目錄中的 src/main/resources/application.properties。
  2. 將屬性 API_SERVICE_NAME 設為符合開發人員說明文件中的值。
google.hosted.echo.url=vgw.googleapis.com/gsp/{API_SERVICE_NAME}/echo/

5. 新增 PGP 金鑰

如以下所示，新增 PGP 金鑰即可啟用 PGP 加密功能。

  • 前往 src/resources/publicKey1.gpg，並將 ASCII 封裝的公開金鑰新增至檔案。
  • 前往 src/resources/privateKey1.gpg，在檔案中新增 ASCII 封裝的私密金鑰。
  • 前往 src/resources/passphrase1.txt，並在檔案中新增密鑰通關密語。

新增 PGP 金鑰

如要啟用雙金鑰加密功能，請將第二個公開金鑰新增至 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，請前往下列網址。

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 時，請按一下「執行」按鈕。

透過 Swagger 提交 GSP Echo 要求

接收回應

如果 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. 測試 Inbound API 連線

如要測試傳入 echo API 連線，Google 會傳送要求至 Partner Hosted echo API。當您準備就緒時，請與 Google 聯絡窗口合作，由 Google 觸發這項要求。

如果您能讀取來自 Google 的內送 echo 要求，並傳回有效的 echo 回應，即代表 echo 測試完成。

詳細路線指示

現在伺服器已成功接收並處理要求，讓我們來看看運作方式。

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. 恭喜！

在本程式碼研究室中，您已成功與 Payments API 建立連線！