Java で Google API との接続を確立する方法

1. 始める前に

前提条件

• 実装プロセスのステップ 1 と 2 を完了している。
• Google を使用して構成したドメインで Google App Engine または独自のソリューションを使用することにより、提供されている Java サーバーと TLS 終端をホストすることが可能である。
• Java が環境にインストールされている。

学習内容

• Google echo API に有効なリクエストを送信して接続を確認する方法。
• Google からパートナー ホスト型 echo API へのリクエストを受信、復号、解析する方法。

2. 設定と要件

アプリケーションをダウンロード

Java サンプルコードをダウンロードします。

アプリケーション構造の概要

Java サンプルコードは、Google の Standard Payments API と統合されています。サンプルコードのプロジェクト構造には、outbound ディレクトリと inbound ディレクトリが含まれています。これは、Google からパートナーへのインバウンド エコー リクエストと、パートナーの実装から Google へのアウトバウンド リクエストを反映するためです。

どちらのディレクトリにも、レイヤごとのパッケージングに類似した階層が含まれています。3 つの主なレイヤは controller、service、domain です。

• controller パッケージには API が含まれています。
• service パッケージは、ビジネス ロジック、base64url エンコード、暗号化を行います。
• domain パッケージには POJO が含まれています。

依存関係のインストール

プロジェクト ディレクトリに移動し、次のコマンドを実行して、Maven ラッパーを使用して必要な依存関係をインストールします。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 URL を設定する

Google がホストする echo の URL は、統合する API によって異なります。特定の統合タイプの API リファレンス ドキュメントを参照し、診断エコー API の URL をコピーします。URL をコピーしたら、次のステップに進んで 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 に移動し、シークレット パスフレーズをファイルに追加します。

デュアルキー暗号化を有効にするには、2 つ目の公開鍵を publicKey2.gpg に追加し、2 つ目の秘密鍵を privateKey2.gpg に追加し、2 つ目のパスフレーズを passphrase.txt に追加します。2 つ目の鍵を追加したら、KeyConfig.addPrivateKeyAndPassphrase(...) と KeyConfig.addPublicKeys(...) で 2 つ目の鍵ペアを読み込むコード行のコメントを解除します。

これで、アプリケーションを実行する準備が整いました。

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 に移動し、リクエスト本文にクライアント メッセージを設定します。[Execute] をクリックします。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 の接続をテストする

インバウンド echo API 接続をテストするために、Google は Partner Hosted echo API にリクエストを送信します。準備ができたら、Google の担当者と連携して、このリクエストを Google からトリガーしてください。

Google からの受信エコー リクエストを読み取り、有効なエコー レスポンスを返せば、エコーテストは完了です。

段階的

リクエストがサーバーによって正常に受信され処理されたら、これからはその動作について詳しく見ていきます。

リクエストを base64url でデコードして復号する

リクエストを受信すると、PgpEncryptor.java は decrypt を呼び出し、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. 完了

この Codelab では、Payments API との接続が正常に確立されました。