איך ליצור קישוריות עם Google APIs ב-Java

1. לפני שמתחילים

דרישות מוקדמות

  • השלמת את שלבים 1 ו-2 של תהליך ההטמעה.
  • אפשר לארח את שרת ה-Java שסופק עם סיום TLS באמצעות Google App Engine או פתרון משלכם בדומיין שהוגדר ב-Google.
  • Java מותקנת בסביבה.

הנושאים שתלמד

  • איך מאמתים את הקישוריות על ידי שליחת בקשה תקינה ל-Google echo API.
  • איך מקבלים, מפענחים ומנתחים בקשה מ-Google ל-echo API שמתארח אצל שותף.

2. הגדרה ודרישות

הורדת האפליקציה

מורידים את קוד הדוגמה של Java.

סקירה כללית על מבנה האפליקציה

קוד הדוגמה ל-Java משתלב עם ממשקי ה-API הרגילים של Google לתשלומים. מבנה הפרויקט של הקוד לדוגמה מכיל ספרייה outbound וגם ספרייה inbound, כדי לשקף את בקשת ה-echo הנכנסת מ-Google לשותף ואת הבקשה היוצאת מההטמעה של השותף אל Google.

שתי הספריות האלה מכילות היררכיה דומה של אריזה לפי שכבה. שלוש השכבות העיקריות הן controller, service ו-domain.

  • החבילה controller מכילה את ממשקי ה-API.
  • החבילה service אחראית על הלוגיקה העסקית, קידוד base64url והצפנה.
  • החבילה domain מכילה POJOs.

יחסי תלות בהתקנות

עוברים לספריית הפרויקט ומריצים את הפקודה הבאה כדי להתקין את יחסי התלות הנדרשים באמצעות Maven Wrapper. אם אתם משתמשים ב-App Engine, אפשר לדלג על השלב הזה.

./mvnw install

3. הגדרת מספר החשבון של מיזוג התשלומים (PIAID)

מזהה החשבון של מיזוג התשלומים (PIAID) הוא מזהה המשמש לזיהוי ייחודי של השילובים שלכם. לפני שתתחילו את המדריך הזה, עליכם להשלים את הדרישות המוקדמות כדי לקבל את ה-PIAID מ-Google.

  1. עוברים אל src/main/resources/application.properties בספריית הפרויקט.
  2. מגדירים את הנכס payment.integrator.account.id למזהה PIAID שהונפק לכם על ידי Google.
payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}

4. הגדרת כתובת ה-URL של הדהוד המתארח ב-Google

כתובת ה-URL של echo שמתארח ב-Google משתנה בהתאם ל-API שאליו מבצעים את השילוב. בקר במסמכי העזרה של ה-API עבור סוג השילוב הספציפי ומעתיק את כתובת ה-URL של ממשק ה-API לאבחון הד. אחרי שמעתיקים את כתובת ה-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 ולהוסיף את ביטוי הסיסמה הסודי לקובץ.

הוספת מפתחות 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, עוברים לכתובת ה-URL הבאה.

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

7. בדיקת הקישוריות של Google Standard Payments Outbound API

עכשיו, כשהיישום פועל, הגיע הזמן לבדוק את הקישוריות עם ממשק ה-API של Google echo.

ניתן להשתמש בממשק המשתמש של Swagger או ב-CLI כדי להריץ את הפקודה הבאה כדי להפעיל קריאה ממופע של האפליקציה לדוגמה אל שרתי Google. ה-API לדוגמה של האפליקציה echo API מקבל בקשת POST בטקסט ללא הצפנה. לאחר קבלת הבקשה, נשלחת בקשה נוספת ל-API שמתארח ב-Google.

שליחת בקשה באמצעות שורת הפקודה

מחליפים את HOSTNAME בשם של מארח השרת לפני שמריצים את הפקודה.

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

שליחת בקשה בממשק המשתמש של Swagger

כדי לשלוח בקשה באמצעות Swagger UI, עוברים אל https://{APPLICATION_HOST}/swagger-ui ומגדירים את הודעת הלקוח בגוף הבקשה. כשמוכנים לשלוח את הבקשה ל-Google, לוחצים על הלחצן 'הפעלה'.

שליחת בקשת GSP Echo דרך Swagger

קבלת התשובה

אם הבקשה ל-API תתבצע בהצלחה, תקבלו את התגובה הבאה מ-Google.

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

שלב אחר שלב

עכשיו, לאחר שבקשה נשלחה בהצלחה על ידי השרת, בואו נראה איך זה עבד.

יצירת הבקשה

createEchoRequestWithMessage ב-OutboundEchoService יוצר את בקשת ה-echo שנשלחת ל-API של Google.

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, לכן צריך גם לפענח ולפענח אותה כדי להחזיר אותה בטקסט ללא הצפנה. השיטה base64url של decrypt מפענחת את התגובה ומפענחת אותה.

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

החזרת התשובה

התשובה מוחזרת עם קוד סטטוס תגובה 202 HTTP.

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

8. בדיקת הקישוריות של Inbound API

כדי לבדוק את הקישוריות של echo API נכנס, Google תשלח בקשה ל-echo API שמתארח אצל השותף. כשיתאים לך, אפשר לפנות לאיש הקשר שלך ב-Google כדי להפעיל את הבקשה הזו מ-Google.

בדיקת ההד מסתיימת אם אפשר לקרוא את בקשת ההד הנכנסת מ-Google ולהגיב באמצעות תגובת הד חוקית.

שלב אחר שלב

עכשיו, אחרי שהבקשה התקבלה והשרת טיפל בה, נבדוק איך זה קרה.

פענוח הבקשה והצפנה מחדש (decrypt) באמצעות Base64url

כשמתקבלת בקשה, PgpEncryptor.java קורא ל-decrypt, שמפענח את הבקשה באמצעות base64url.

String decryptedRequest = pgpEncryptor.decrypt(echoRequest);

קבלת הבקשה

Google שלחה מטען ייעודי (payload) של הודעות שדומה להודעה הבאה לאחר הפענוח והפענוח.

{
  "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)

החזרת התשובה

התגובה מוחזרת עם קוד סטטוס תגובת HTTP 202.

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

9. מעולה!

בקודלאב הזה, יצרתם חיבור ל-Payments API.