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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

./mvnw install

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

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

  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 armored לקובץ.
  • עוברים אל 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

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

אפשר להשתמש בממשק המשתמש של Swagger או ב-CLI כדי להריץ את הפקודה הבאה ולהתחיל שיחה מהמופע של אפליקציית הדוגמה לשרתים של Google. ה-API של אפליקציית הדוגמה echo מקבל בקשת 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, לוחצים על הלחצן Execute (ביצוע).

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

קבלת התשובה

בקשת API שמושלמת בהצלחה תניב את התגובה הבאה מ-Google.

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

שלב אחר שלב

אחרי שהשרת שלכם שלח בקשה בהצלחה, נסביר איך זה קרה.

הרכבת הבקשה

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

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 נכנס

כדי לבדוק את הקישוריות של ה-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.