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

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

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

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

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

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

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

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

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

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

הקוד לדוגמה ב-Java משתלב עם ממשקי ה-API הרגילים של Google Payments. מבנה הפרויקט לדוגמה של הקוד מכיל ספריית outbound וגם ספריית inbound המשקפת את בקשת ההד הנכנס מ-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. כדי לראות את ממשק המשתמש של Swagger ב-API, צריך לעבור לכתובת ה-URL שלמטה.

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

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

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

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

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

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

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

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

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

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

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

החזרת התשובה

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

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

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

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

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

שלב אחר שלב

עכשיו, אחרי שבקשה כלשהי התקבלה בהצלחה וטופלה על ידי השרת שלכם, הגיע הזמן לבדוק איך זה עובד.

פענוח ופענוח של הבקשה באמצעות 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)

החזרת התשובה

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

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

9. כל הכבוד!

ב-codelab זה השגת בהצלחה את הקישוריות ל-Payments API!