كيفية إنشاء اتصال بواجهات Google API في Java

1. قبل البدء

المتطلبات الأساسية

  • لقد أكملت الخطوتين 1 و2 من عملية التنفيذ.
  • يمكنك استضافة خادم Java المقدَّم مع إنهاء بروتوكول أمان طبقة النقل (TLS) باستخدام Google App Engine أو الحل الخاص بك في النطاق الذي تم إعداده من خلال Google.
  • تثبيت Java في بيئتك

ما ستتعلمه

  • كيفية التحقّق من الاتصال من خلال تقديم طلب صالح إلى Google echo API
  • كيفية تلقّي طلب من Google إلى واجهة برمجة التطبيقات Partner Hosted echo API وفك تشفيره وتحليله

2. الإعداد والمتطلبات

تنزيل التطبيق

نزِّل نموذج رمز Java.

نظرة عامة على بنية التطبيق

يتكامل رمز نموذج Java مع واجهات برمجة التطبيقات للدفعات العادية من Google. يحتوي نموذج بنية مشروع الرمز على دليل outbound ودليل inbound لعرض طلب الارتداد الوارد من Google إلى الشريك والطلب الصادر من تنفيذ الشركاء إلى Google.

يحتوي كلا الدليلَين على تسلسل هرمي مشابه في الحزمة حسب الطبقة. الطبقات الرئيسية الثلاث هي controller وservice وdomain.

  • تحتوي الحزمة controller على واجهات برمجة التطبيقات.
  • حزمة 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 الذي تستضيفه Google على echo وفقًا لواجهة برمجة التطبيقات التي يتم الدمج معها. انتقِل إلى المستندات المرجعية لواجهة برمجة التطبيقات لنوع الدمج المحدّد وانسخ عنوان URL لواجهة برمجة التطبيقات الخاصة بميزة "صدى بيانات التشخيص". بعد نسخ عنوان 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

والآن بعد تشغيل التطبيق، حان وقت اختبار الاتصال بواجهة برمجة تطبيقات Google echo API.

يمكن استخدام واجهة مستخدم Shagger أو واجهة سطر الأوامر لتشغيل الأمر التالي لبدء الاتصال من مثيل التطبيق بخوادم Google. تقبل نموذج echo API للتطبيق طلب POST بنص عادي. وبعد تلقّي الطلب، يتم إرسال طلب لاحق إلى واجهة برمجة التطبيقات التي تستضيفها 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.

إرسال طلب Echo GSP من خلال Shagger

تلقّي الردّ

سينتج عن تنفيذ طلب البيانات من واجهة برمجة التطبيقات الردّ التالي من Google.

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

الخطوات بالتفصيل

بعد أن أرسل الخادم طلبًا بنجاح، لنراجع كيفية تنفيذ ذلك.

إنشاء الطلب

createEchoRequestWithMessage في OutboundEchoService ينشئ طلب echo الذي يتم إرساله إلى واجهة برمجة تطبيقات 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());

عرض الردّ

يتم عرض الاستجابة مع رمز حالة استجابة HTTP‏ 202.

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

8. اختبار اتصال واجهة برمجة التطبيقات الواردة

لاختبار اتصال واجهة برمجة التطبيقات echo API الوارد، سترسل Google طلبًا إلى Partner Hosted echo API. عندما تكون مستعدًا، يُرجى التواصل مع جهة التواصل المعنية في Google لبدء هذا الطلب من Google.

ويكتمل اختبار صدى الصوت عندما تكون قادرًا على قراءة طلب صدى الصوت الوارد من Google والاستجابة باستجابة ارتداد صالحة.

الخطوات بالتفصيل

بعد أن تلقّى الخادم طلبًا وعالجه بنجاح، لنراجع كيفية تنفيذ ذلك.

Base64url لفك ترميز الطلب وفك تشفيره

عند تلقّي طلب، سيتصل PgpEncryptor.java بخدمة decrypt التي ستفك ترميز base64url للطلب وتُشفّره.

String decryptedRequest = pgpEncryptor.decrypt(echoRequest);

تلقّي الطلب

أرسلت Google حمولة رسائل مشابهة لما يلي بعد فك ترميزها وفك تشفيرها.

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