Jak nawiązać połączenie z interfejsami API Google w języku Java

1. Zanim zaczniesz

Wymagania wstępne

  • Masz ukończone kroki 1 i 2 procesu implementacji.
  • Możesz hostować serwer Java z zakończeniem TLS, używając Google App Engine lub własnego rozwiązania w domenie skonfigurowanej w Google.
  • Obiekt Java jest zainstalowany w Twoim środowisku.

Czego się nauczysz

  • Jak weryfikować połączenie, wysyłając prawidłowe żądanie do interfejsu API obsługującego test echa w Google.
  • Jak odbierać, odszyfrowywać i analizować żądanie od Google do interfejsu API obsługującego test echa hostowanego przez partnera.

2. Konfiguracja i wymagania

Pobieranie aplikacji

Pobierz przykładowy kod w języku Java.

Omówienie struktury aplikacji

Przykładowy kod w Javie jest zintegrowany z interfejsami API Google Standard Payments. Struktura projektu z przykładowym kodem zawiera katalog outbound oraz katalog inbound, aby odzwierciedlać przychodzące żądanie echa od Google do partnera i wychodzące żądanie od implementacji partnera do Google.

Oba te katalogi mają podobną hierarchię w zakresie pakowania według warstw. Trzy główne warstwy to controller, service i domain.

  • Pakiet controller zawiera interfejsy API.
  • Pakiet service odpowiada za logikę biznesową, kodowanie base64url i szyfrowanie.
  • Pakiet domain zawiera obiekty POJO.

Instalowanie zależności

Aby zainstalować wymagane zależności za pomocą narzędzia Maven Wrapper, otwórz katalog projektu i uruchom polecenie znajdujące się poniżej. Jeśli korzystasz z App Engine, możesz pominąć ten krok.

./mvnw install

3. Konfigurowanie identyfikatora konta integratora płatności

Identyfikator konta integratora płatności (PIAID) to identyfikator używany do jednoznacznego oznaczania integracji. Przed rozpoczęciem tego samouczka powinien dotrzeć do Ciebie ten identyfikator od Google, jeśli udało Ci się spełnić wymagania wstępne.

  1. Przejdź do pliku src/main/resources/application.properties w katalogu projektu.
  2. Ustaw właściwość payment.integrator.account.id na identyfikator konta integratora płatności, który został Ci wysłany przez Google.
payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}

4. Ustawianie adresu URL hostowanej przez Google metody echa

Adres URL hostowany przez Google echo różni się w zależności od interfejsu API, z którym integrujesz usługę. Otwórz dokumentację referencyjną interfejsu API dla konkretnego typu integracji i skopiuj adres URL interfejsu API diagnostycznego echa. Po skopiowaniu adresu URL wykonaj kolejne czynności, aby zaktualizować go w projekcie Java.

  1. Przejdź do pliku src/main/resources/application.properties w katalogu projektu.
  2. Ustaw właściwość API_SERVICE_NAME zgodnie z informacjami w dokumentacji dla deweloperów.
google.hosted.echo.url=vgw.googleapis.com/gsp/{API_SERVICE_NAME}/echo/

5. Dodawanie kluczy PGP

Jak pokazano poniżej, dodaj klucze PGP, aby włączyć szyfrowanie PGP.

  • Przejdź do src/resources/publicKey1.gpg i dodaj do pliku klucz publiczny w opakowaniu ASCII.
  • Przejdź do src/resources/privateKey1.gpg i dodaj do pliku klucz prywatny w opakowaniu ASCII.
  • Otwórz src/resources/passphrase1.txt i dodaj do niego tajne hasło.

Dodawanie kluczy PGP

Aby włączyć szyfrowanie dwukluczowe, dodaj drugi klucz publiczny do publicKey2.gpg, drugi klucz prywatny do privateKey2.gpg i drugie hasło do passphrase.txt. Po dodaniu drugiego klucza usuń komentarze z zakomentowanych wierszy kodu, które odpowiadają za wczytywanie drugiej pary kluczy w KeyConfig.addPrivateKeyAndPassphrase(...) i KeyConfig.addPublicKeys(...).

Świetnie, wszystko gotowe do uruchomienia aplikacji.

6. Uruchamianie aplikacji

Aby uruchomić aplikację, wykonaj to polecenie:

  $ ./mvnw spring-boot:run

Jeśli używasz domyślnie skonfigurowanej instancji App Engine, zamiast tego uruchom to polecenie:

$ gcloud app deploy

Domyślnie serwer nasłuchuje na porcie 8080. Aby wyświetlić interfejs Open API Swagger UI, otwórz poniższy adres URL.

https://{APPLICATION_HOST}/swagger-ui.html

7. Testowanie połączenia wychodzącego interfejsu API Google Standard Payments

Gdy aplikacja jest już uruchomiona, czas przetestować połączenie za pomocą interfejsu API obsługującego test echa w Google.

Aby nawiązać połączenie między Twoją instancją przykładowej aplikacji a serwerami Google, możesz uruchomić to polecenie w interfejsie Swagger UI lub w interfejsie wiersza poleceń. Interfejs API obsługujący test echa przykładowej aplikacji akceptuje żądanie POST w formie tekstu jawnego. Po otrzymaniu żądania kolejne żądanie jest wysyłane do interfejsu API hostowanego przez Google.

Wysyłanie żądania za pomocą wiersza poleceń

Przed uruchomieniem polecenia zastąp HOSTNAME nazwą hosta serwera.

  $ curl -X POST -H 'Content-Type: text/plain' -d 'Hello from Partner Bank!' https://{HOSTNAME}/echo

Wysyłanie żądania w interfejsie Swagger

Aby wysłać żądanie za pomocą interfejsu Swagger, otwórz https://{APPLICATION_HOST}/swagger-ui i ustaw wiadomość klienta w treści żądania. Gdy wszystko będzie gotowe, kliknij przycisk „Wykonaj”, aby wysłać prośbę do Google.

Przesyłanie żądania GSP Echo za pomocą Swaggera

Otrzymywanie odpowiedzi

Pomyślne żądanie do interfejsu API spowoduje wyświetlenie takiej odpowiedzi od Google:

{
   "responseHeader":{
      "responseTimestamp":"1606710026723"
   },
   "clientMessage":"Hello from  Bank Little Bear!",
   "serverMessage":"Server message."
}

Krok po kroku

Żądanie zostało już wysłane przez serwer, więc teraz sprawdźmy, jak to działa.

Tworzenie żądania

createEchoRequestWithMessage w OutboundEchoService tworzy żądanie echo wysłane do interfejsu API Google.

String jsonEchoRequestMessage = objectMapper.writeValueAsString(createEchoRequestWithMessage(message));

Wygenerowane żądanie zawiera clientMessage oraz kilka domyślnych pól wartości.

{
   "requestHeader":{
      "protocolVersion":{
         "major":1,
         "minor":0,
         "revision":0
      },
      "requestId":"ddfe0fd0-ffdc-4fcf-991a-f0611ec83970",
      "requestTimestamp":"1606715389040"
   },
   "clientMessage":"Hello from Bank Little Bear!"
}

Kodowanie i szyfrowanie żądania za pomocą base64url

Wszystkie żądania są zaszyfrowane i zakodowane w base64url. W tym przykładzie PgpEncryptor.java zawiera metody pomocnicze, które wykonują szyfrowanie i odszyfrowywanie danych oraz kodowanie w base64url za Ciebie. Poniższa metoda koduje żądanie i szyfruje je za pomocą klucza publicznego Google.

String encryptedMessage = pgpEncryptor.encrypt(jsonEchoRequestMessage);

Wysyłanie żądania POST

Zaszyfrowana wiadomość jest wysyłana za pomocą żądania POST.

postStandardPaymentsEchoApi(encryptedMessage)

Odszyfrowywanie i dekodowanie odpowiedzi za pomocą base64url oraz zwracanie odpowiedzi

Prawidłowa odpowiedź od Google jest zakodowana i zaszyfrowana w base64url, więc przed wyświetleniem jako tekst jawny musi zostać odkodowana i odszyfrowana. Metoda decrypt dekoduje i odszyfrowuje odpowiedź za pomocą base64url.

String decryptedData =
     pgpEncryptor.decrypt(postStandardPaymentsEchoApi(encryptedMessage).getBody());

Wysyłanie odpowiedzi

Odpowiedź jest zwracana z kodem stanu odpowiedzi HTTP 202.

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

8. Testowanie połączenia z interfejsem API do przesyłania danych przychodzących

Aby przetestować łączność z interfejsem API obsługującym test echa, Google wyśle żądanie do interfejsu API obsługującego test echa hostowanego przez partnera. Gdy wszystko będzie gotowe, skontaktuj się z osobą kontaktową w Google, aby aktywować to żądanie z Google.

Test echa jest zakończony, gdy możesz odczytać przychodzące żądanie echa od Google i odpowiedzieć za pomocą prawidłowej odpowiedzi echa.

Krok po kroku

Żądanie zostało już otrzymane i obsłużone przez serwer, więc teraz sprawdźmy, jak to działa.

Dekodowanie i odszyfrowywanie żądania za pomocą base64url

Gdy żądanie zostanie odebrane, PgpEncryptor.java wywoła decrypt, które zdekoduje i odszyfruje żądanie za pomocą base64url.

String decryptedRequest = pgpEncryptor.decrypt(echoRequest);

Odbieranie żądania

Z Google został wysłany ładunek wiadomości, który po zdekodowaniu i odszyfrowaniu jest podobny do tego:

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "G1MQ0YERJ0Q7LPM",
    "requestTimestamp": {
      "epochMillis":1481899949606
    },
    "paymentIntegratorAccountId": "abcdef123456"
  },
  "clientMessage": "echo Me"
}

Tworzenie odpowiedzi

Po pomyślnym odczytaniu przychodzącego żądania echa możesz utworzyć odpowiedź.

private EchoResponse convertEchoRequestStringToEchoResponse(String decryptedRequest);

Odpowiedź zawiera wiadomość od Google, a także sygnaturę czasową i wiadomość z serwera.

{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis":1481899950236
    }
  },
  "clientMessage": "echo Me",
  "serverMessage": "Debug ID 12345"
}

Kodowanie i szyfrowanie odpowiedzi za pomocą base64url

Ponieważ wszystkie żądania są zaszyfrowane i zakodowane w base64url, PgpEncryptor.java wywołuje encrypt, aby zakodować i zaszyfrować żądanie.

pgpEncryptor.encrypt(echoResponseString)

Wysyłanie odpowiedzi

Odpowiedź jest zwracana z kodem stanu odpowiedzi HTTP 202.

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

9. Gratulacje!

Dzięki temu ćwiczeniu z programowania udało Ci się nawiązać połączenie z interfejsem Payments API.