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 من خلال إكمال المتطلبات الأساسية قبل بدء هذا البرنامج التعليمي.
- انتقِل إلى
src/main/resources/application.properties
في دليل المشروع. - اضبط الخاصية
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.
- انتقِل إلى
src/main/resources/application.properties
في دليل المشروع. - يمكنك ضبط السمة
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
وأضِف عبارة المرور السرية إلى الملف.
لتفعيل تشفير المفتاحَين، يجب إضافة المفتاح العام الثاني إلى "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.
تلقّي الردّ
سيؤدي طلب البيانات بنجاح من خلال واجهة برمجة التطبيقات إلى تلقّي الرد التالي من 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.