نحوه برقراری ارتباط با Google API در جاوا

۱. قبل از شروع

پیش‌نیازها

  • شما مراحل ۱ و ۲ فرآیند پیاده‌سازی را تکمیل کرده‌اید.
  • شما می‌توانید سرور جاوای ارائه شده را با قابلیت خاتمه TLS با استفاده از Google App Engine یا راهکار خودتان در دامنه پیکربندی شده با گوگل میزبانی کنید.
  • جاوا روی محیط شما نصب شده است.

آنچه یاد خواهید گرفت

  • نحوه تأیید اتصال با ارسال یک درخواست معتبر به API گوگل اکو.
  • نحوه دریافت، رمزگشایی و تجزیه درخواست از گوگل به API echo میزبانی شده توسط شریک.

۲. تنظیمات و الزامات

دانلود اپلیکیشن

کد نمونه جاوا را دانلود کنید.

بررسی اجمالی ساختار برنامه

کد نمونه جاوا با APIهای استاندارد پرداخت گوگل ادغام می‌شود. ساختار پروژه کد نمونه شامل یک دایرکتوری outbound و همچنین یک دایرکتوری inbound است تا درخواست اکو ورودی از گوگل به شریک و درخواست خروجی از پیاده‌سازی شریک به گوگل را منعکس کند.

هر دوی این دایرکتوری‌ها شامل سلسله مراتب مشابهی در بسته‌بندی بر اساس لایه هستند. سه لایه اصلی عبارتند از controller ، service و domain .

  • بسته controller شامل APIها است.
  • بسته service مسئول منطق تجاری، کدگذاری base64url و رمزگذاری است.
  • بسته domain شامل POJO ها است.

نصب وابستگی‌ها

به دایرکتوری پروژه بروید و دستور زیر را برای نصب وابستگی‌های مورد نیاز با استفاده از Maven Wrapper اجرا کنید. اگر از App Engine استفاده می‌کنید، می‌توانید از این مرحله صرف نظر کنید.

./mvnw install

۳. شناسه حساب یکپارچه‌ساز پرداخت (PIAID) را پیکربندی کنید

شناسه حساب یکپارچه‌ساز پرداخت ( PIAID ) شناسه‌ای است که برای شناسایی منحصر به فرد یکپارچه‌سازی‌های شما استفاده می‌شود. قبل از شروع این آموزش، باید با تکمیل پیش‌نیازها، PIAID خود را از گوگل دریافت کرده باشید.

  1. به مسیر src/main/resources/application.properties در دایرکتوری پروژه بروید.
  2. مقدار property payment.integrator.account.id را روی PIAID که توسط گوگل برای شما صادر شده است، تنظیم کنید. 
payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}

۴. آدرس اکو میزبانی شده توسط گوگل را تنظیم کنید

URL echo میزبانی شده توسط گوگل بسته به اینکه با کدام API ادغام می‌شوید، متفاوت است. برای نوع ادغام خاص خود، به مستندات مرجع API مراجعه کنید و URL مربوط به API echo تشخیصی را کپی کنید. پس از کپی کردن URL، برای به‌روزرسانی آن در پروژه جاوا، به مراحل بعدی بروید.

  1. به مسیر src/main/resources/application.properties در دایرکتوری پروژه بروید.
  2. ویژگی API_SERVICE_NAME را طوری تنظیم کنید که با آنچه در مستندات توسعه‌دهنده آمده است، مطابقت داشته باشد. 
google.hosted.echo.url=vgw.googleapis.com/gsp/{API_SERVICE_NAME}/echo/

۵. کلیدهای 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(...) هستند را از حالت کامنت خارج کنید.

عالی، شما آماده اجرای برنامه هستید!

۶. برنامه را اجرا کنید

برای شروع برنامه، دستور زیر را اجرا کنید.

  $ ./mvnw spring-boot:run

اگر از یک نمونه از پیش پیکربندی شده App Engine استفاده می‌کنید، این دستور را اجرا کنید.

$ gcloud app deploy

به طور پیش‌فرض، سرور به پورت ۸۰۸۰ گوش می‌دهد. برای مشاهده رابط کاربری Open API Swagger، به آدرس اینترنتی زیر بروید.

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

۷. اتصال API خروجی پرداخت‌های استاندارد گوگل را آزمایش کنید

اکنون که برنامه در حال اجرا است، زمان آن رسیده است که اتصال را با API گوگل اکو آزمایش کنیم.

می‌توان از رابط کاربری Swagger یا رابط خط فرمان (CLI) برای اجرای دستور زیر جهت آغاز فراخوانی از نمونه برنامه نمونه شما به سرورهای گوگل استفاده کرد. رابط برنامه‌نویسی کاربردی echo برنامه نمونه، درخواست POST را به صورت متن ساده می‌پذیرد. پس از دریافت درخواست، درخواست بعدی به API میزبانی شده توسط گوگل ارسال می‌شود.

ارسال درخواست از طریق خط فرمان

قبل از اجرای دستور، 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 بروید و پیام کلاینت را در بدنه درخواست تنظیم کنید. وقتی آماده ارسال درخواست به گوگل شدید، روی دکمه «اجرا» کلیک کنید.

ارسال درخواست GSP Echo از طریق Swagger

دریافت پاسخ

یک درخواست API موفق منجر به پاسخ زیر از گوگل خواهد شد.

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

گام به گام

اکنون که درخواست با موفقیت توسط سرور شما ارسال شده است، بیایید نحوه عملکرد آن را بررسی کنیم.

درخواست را بسازید

createEchoRequestWithMessage در OutboundEchoService درخواست echo ارسال شده به 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 را برای شما انجام می‌دهند. متد زیر درخواست را رمزگذاری کرده و با استفاده از کلید عمومی گوگل، رمزگذاری را انجام می‌دهد. 

String encryptedMessage = pgpEncryptor.encrypt(jsonEchoRequestMessage);

ارسال درخواست POST

پیام رمزگذاری شده از طریق درخواست POST ارسال می‌شود. 

postStandardPaymentsEchoApi(encryptedMessage)

رمزگشایی و base64url پاسخ را رمزگشایی کرده و پاسخ را برمی‌گردانند

پاسخ موفقیت‌آمیز گوگل به صورت base64url کدگذاری و رمزگذاری شده است، بنابراین قبل از اینکه بتواند به صورت متن ساده برگردانده شود، باید رمزگشایی و رمزگشایی نیز شود. متد decrypt base64url پاسخ را رمزگشایی و رمزگشایی می‌کند. 

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

پاسخ را برگردانید

پاسخ با کد وضعیت پاسخ HTTP 202 برگردانده می‌شود. 

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

۸. اتصال ورودی API را آزمایش کنید

برای آزمایش اتصال ورودی echo API، گوگل درخواستی را به Partner Hosted echo API ارسال می‌کند. وقتی آماده شدید، لطفاً با رابط گوگل خود برای فعال کردن این درخواست از گوگل همکاری کنید.

تست اکو زمانی کامل می‌شود که بتوانید درخواست اکوی ورودی از گوگل را بخوانید و با یک پاسخ اکوی معتبر پاسخ دهید.

گام به گام

اکنون که درخواستی با موفقیت توسط سرور شما دریافت و مدیریت شده است، بیایید نحوه عملکرد آن را بررسی کنیم.

رمزگشایی و رمزگشایی درخواست Base64url

وقتی درخواستی دریافت می‌شود، PgpEncryptor.java تابع decrypt را فراخوانی می‌کند که درخواست را با استفاده از base64url رمزگشایی و رمزگشایی می‌کند. 

String decryptedRequest = pgpEncryptor.decrypt(echoRequest);

دریافت درخواست

گوگل پس از رمزگشایی و رمزگشایی، پیامی مشابه زیر ارسال کرد. 

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

پاسخ را بسازید

زمانی که درخواست اکوی ورودی را با موفقیت خواندید، آماده‌ی ساخت پاسخ هستید. 

private EchoResponse convertEchoRequestStringToEchoResponse(String decryptedRequest);

این پاسخ شامل پیام دریافتی از گوگل، و همچنین یک مهر زمانی و پیام دریافتی از سرور است. 

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

کدگذاری و رمزگذاری پاسخ با Base64url

از آنجایی که همه درخواست‌ها رمزگذاری شده و با base64url کدگذاری شده‌اند، PgpEncryptor.java تابع encrypt را به base64url encode فراخوانی کرده و درخواست را رمزگذاری می‌کند. 

pgpEncryptor.encrypt(echoResponseString)

پاسخ را برگردانید

پاسخ با کد وضعیت پاسخ HTTP 202 برگردانده می‌شود. 

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

۹. تبریک می‌گویم!

در این آزمایشگاه کد، شما با موفقیت به API پرداخت‌ها متصل شدید!