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 על ידי השלמת הדרישות המוקדמות לפני שתתחילו את המדריך הזה.
- מנווטים אל
src/main/resources/application.properties
בספריית הפרויקט. - מגדירים את המאפיין
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.
- מנווטים אל
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
ומוסיפים לקובץ את ביטוי הסיסמה הסודי.
כדי להפעיל הצפנה של שני מפתחות, עליך להוסיף את המפתח הציבורי השני ל-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.
קבלת התגובה
בקשת 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!