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

‫1. قبل البدء

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

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

ما ستتعلمه

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

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

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

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

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

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

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

  • تحتوي الحزمة controller على واجهات برمجة التطبيقات.
  • حزمة service مسؤولة عن منطق النشاط التجاري وتشفير base64url والتشفير.
  • تحتوي الحزمة domain على عناصر POJO.

تثبيت الحِزم التابعة

انتقِل إلى دليل المشروع ونفِّذ الأمر التالي لتثبيت الموارد الاعتمادية المطلوبة باستخدام 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 الخاص بخدمة Echo المستضافة من 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 armored إلى الملف.
  • انتقِل إلى 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.

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

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

تلقّي الردّ

سيؤدي طلب البيانات الناجح من واجهة برمجة التطبيقات إلى تلقّي الردّ التالي من 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، سترسل Google طلبًا إلى واجهة برمجة التطبيقات الخارجية لخدمة Echo التي يستضيفها الشريك. عندما تكون مستعدًا، يُرجى التواصل مع جهة الاتصال المعنية في 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.