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

1. 事前準備

必要條件

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

課程內容

  • 如何向 Google echo API 發出有效要求來驗證連線。
  • 如何接收、解密及剖析 Google 對合作夥伴代管 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 參考說明文件，並複製診斷回聲 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());

傳回回應

系統會傳回 HTTP 回應狀態碼 202 的回應。

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

8. 測試 Inbound API 連線

如要測試連入 echo API 連線，Google 會傳送要求至合作夥伴代管的 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"
}

建立回應

成功讀取內送 echo 要求後，即可開始建立回應。

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)

傳回回應

系統會傳回 HTTP 回應狀態碼 202 的回應。

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

9. 恭喜！

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