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

1- قبل البدء

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

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

المعلومات التي ستطّلع عليها

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

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

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

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

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

يتكامل نموذج رمز Java مع واجهات برمجة التطبيقات العادية لـ Google Payments. يحتوي نموذج بنية مشروع الرمز على دليل 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 الخاص بصدى Google الذي تستضيفه Google

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

إرسال طلب من خلال سطر الأوامر

استبدِل HOSTNAME باسم مضيف الخادم قبل تنفيذ الأمر.

  $ curl -X POST -H 'Content-Type: text/plain' -d 'Hello from Partner Bank!' https://{HOSTNAME}/echo

إرسال طلب في واجهة مستخدم التباهي

لإرسال طلب باستخدام واجهة مستخدم Swagger، انتقِل إلى https://{APPLICATION_HOST}/swagger-ui واضبط رسالة العميل في نص الطلب. انقر على الزر "تنفيذ" عندما تكون مستعدًا لإرسال الطلب إلى Google.

إرسال طلب ارتداد على GSP من خلال 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. اختبار اتصال واجهة برمجة تطبيقات البريد الوارد

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

pgpEncryptor.encrypt(echoResponseString)

عرض الرد

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

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

9. تهانينا!

في هذا الدرس التطبيقي حول الترميز، نجحت في إنشاء اتصال بواجهة Payments API.