本頁面由 Cloud Translation API 翻譯而成。

如何使用 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 的標準 Payments API 整合。程式碼範例專案結構包含 outbound 目錄和 inbound 目錄，用於反映 Google 傳送給合作夥伴的傳入 echo 要求，以及合作夥伴導入 Google 的傳出要求。

這兩個目錄的封裝方式都具有相同的階層。三個主要圖層為 controller、service 和 domain。

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

安裝依附元件

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

./mvnw install

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

付款整合商帳戶 ID (PIAID) 是用來識別整合項目的 ID。開始本教學課程前，請先完成事前準備，確保 Google 已取得你的 PIAID。

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

payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}

4. 設定 Google 代管的 echo 網址

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

前往專案目錄中的 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 輔助公開金鑰。
前往 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 傳出 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. 測試傳入 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"
}

建立回應

成功讀取傳入 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)

傳回回應

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

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

9. 恭喜！

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