استخدام واجهة برمجة التطبيقات FCM HTTP v1 مع رموز الدخول عبر OAuth 2

1. مقدمة

مقارنةً بواجهة برمجة التطبيقات القديمة للمراسلة عبر السحابة الإلكترونية من Firebase، توفّر واجهة برمجة التطبيقات HTTP v1 للمراسلة عبر السحابة الإلكترونية من Firebase نموذجًا أكثر أمانًا لمنح الأذونات باستخدام رموز مميزة قصيرة الأمد للوصول. تختلف خطوات إنشاء رمز الدخول إلى الإصدار 1 من واجهة برمجة التطبيقات FCM API بشكل كبير عن خطوات إنشاء رمز الدخول إلى واجهة برمجة التطبيقات القديمة.

يوضّح لك هذا الدرس التطبيقي حول الترميز كيفية إعداد البرنامج والخادم لتفعيل إرسال الإشعارات الفورية إلى تطبيق Android باستخدام واجهة برمجة التطبيقات FCM HTTP v1. توضّح هذه الصفحة الخطوة الأساسية لإنشاء بيانات الاعتماد الخاصة بالإصدار 1 من واجهة برمجة التطبيقات.

يمكنك الاطّلاع على مزيد من المعلومات على:

• الفيديو: مقدمة عن خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"
• نظرة عامة على بنية FCM

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

• فهم أساسي لتطوير Java وAndroid

أهداف الدورة التعليمية

• خطوات تفصيلية لإعداد كلّ من البرنامج والخادم من أجل تفعيل إرسال الإشعارات الفورية إلى تطبيق Android باستخدام واجهة برمجة التطبيقات FCM HTTP v1
• إنشاء بيانات اعتماد لواجهة برمجة التطبيقات HTTP الإصدار 1 باستخدام حسابات الخدمة
• إرسال رسائل اختبارية من خلال HTTP v1 API

المتطلبات

أحدث إصدار ثابت من "استوديو Android"

أحد الأجهزة التالية:

• جهاز Android فعلي متصل بجهاز الكمبيوتر
• محاكي Android (راجِع تشغيل التطبيقات على محاكي Android)

بيئة تطوير Java أو محرِّر رموز برمجية من اختيارك

2. إعداد مشروع Firebase وتطبيق Android

في نهاية جلسة التدريب العملي، ستتمكّن من إرسال رسائل إلى تطبيقك باستخدام خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". قبل إجراء ذلك، عليك إنشاء مشروع Firebase. يوفر هذا الدرس العملي أيضًا تطبيق Android يحتوي على نموذج رمز برمجي للتكامل مع FCM.

إعداد مشروع Firebase

• اتّبِع "الخطوة 1: إنشاء مشروع على Firebase" لإنشاء مشروعك الخاص على Firebase لهذا الدرس العملي.

إعداد تطبيق Android

تمّ دمج تطبيق Android النموذجي المقدَّم في هذا الدرس العملي مع خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" (FCM). بعد البدء، سيتم التسجيل في خادم FCM والاشتراك في موضوع. في الخطوات اللاحقة من هذا الدرس التطبيقي حول الترميز، سترسل رسالة موضوع إلى الموضوع وسيتلقّاها تطبيقك.

• نزِّل نموذج التشغيل السريع لتطبيق Android على Firebase.
• استورِد المشروع من https://github.com/firebase/quickstart-android/tree/master/messaging إلى "استوديو Android".
• سجِّل التطبيق في "وحدة تحكّم Firebase". اسم التطبيق هو com.google.firebase.quickstart.fcm. سجِّل هذا التطبيق في مشروعك على Firebase باتّباع الخطوات الواردة في القسم "الخطوة 2: تسجيل تطبيقك في Firebase".
• اتّبِع الجزء 1 من "الخطوة 3: إضافة ملف إعداد Firebase" لتنزيل google-services.json وإضافته إلى مشروعك. إنشاء المشروع وتشغيله

3- إعداد خادم التطبيق

بعد إعداد تطبيقك، عليك تنزيل نموذج رمز من جهة الخادم لإرسال الرسائل إلى تطبيقك باستخدام الإصدار 1 من واجهة برمجة التطبيقات FCM. تحمّل هذه التعليمة البرمجية بيانات اعتماد واجهة برمجة التطبيقات (الموضّحة في القسم التالي) لإنشاء رمز دخول. بعد ذلك، يتم إرسال رسالة إلى تطبيقك باستخدام ميزة المراسلة حسب الموضوع في "المراسلة عبر السحابة الإلكترونية من Firebase".

• استورِد رمز الخادم المبدئي من خلال تنزيل مشروع Github. مشروع "المراسلة" هو مشروع Java يستند إلى Gradle ويتضمّن تبعية لحزمة تطوير البرامج (SDK) الخاصة بـ firebase-admin، والتي توفّر وظائف لإرسال الرسائل.

يمكنك العثور على مزيد من التفاصيل حول كيفية عمل خادم التطبيق مع "المراسلة عبر السحابة الإلكترونية من Firebase" في المستند بيئة الخادم و"المراسلة عبر السحابة الإلكترونية من Firebase".

4. الحصول على بيانات اعتماد الإصدار 1

تستخدِم واجهة برمجة التطبيقات FCM HTTP v1 رموز الدخول القصيرة الأمد وفقًا لنموذج أمان OAuth2. مقارنةً بمفتاح واجهة برمجة التطبيقات الثابت المستخدَم في واجهة برمجة التطبيقات القديمة لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، يكون رمز الدخول القصير الأجل أقل عرضة لخطر تسرُّب بيانات الاعتماد. يوضّح هذا القسم بالتفصيل خطوات إنشاء بيانات اعتماد لإنشاء رمز الدخول المستخدَم في طلب البيانات من واجهة برمجة التطبيقات.

1. إعداد حساب خدمة في Firebase للسماح لحزمة تطوير البرامج (SDK) للمشرف في Firebase بتفويض طلبات إلى واجهات برمجة التطبيقات في خدمة المراسلة عبر السحابة الإلكترونية (FCM) افتح إعدادات المشروع في "وحدة تحكّم Firebase" واختَر علامة التبويب حسابات الخدمة. انقر على إنشاء مفتاح خاص جديد لتنزيل مقتطف الإعدادات.
2. في مشروع Github الذي تم تنزيله، أعِد تسمية الملف الذي تم تنزيله إلى service-account.json وانسخه إلى مسار messaging/ الخاص بالمشروع.
3. تنشئ طريقة getAccessToken() (الموضّحة أدناه) في الفئة Messaging.java رمز OAuth2 صالحًا لمدة ساعة واحدة.

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials.fromStream(new FileInputStream("service-account.json")).createScoped(Arrays.asList(SCOPES));
  googleCredentials.refresh();
  return googleCredentials.getAccessToken().getTokenValue();
}

4. غيِّر الطريقة الرئيسية لإضافة السطر التالي:

public static void main(String[] args) throws IOException {
  System.out.println(getAccessToken());
  ...
}

5. انتقِل إلى دليل المراسلة أو المشروع في نافذة Terminal، واكتب ما يلي:

./gradlew run -Pmessage=common-message

لطباعة الرمز المميز لبروتوكول OAuth2.

يمكنك الاطّلاع على مزيد من المعلومات في مقالة تفويض إرسال الطلبات.

5- إرسال رسالة باستخدام واجهة برمجة تطبيقات REST

أنت الآن جاهز لإرسال رسالة من خلال HTTP v1 API. اتبع الخطوات التالية:

• لإضافة رمز الدخول إلى عنوان طلب HTTP، اتّبِع الخطوات التالية:
• أضِف الرمز المميّز كقيمة لعنوان Authorization بالتنسيق Authorization: Bearer <access_token>
• أرسِل طلب HTTP إلى الإصدار 1 من واجهة برمجة التطبيقات FCM API باستخدام curl:

curl -s -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $OAuth2_token" -H "X-GFE-SSL: yes" -d  "{\"message\": {\"topic\": \"$topic_name\", \"notification\": {\"title\": \"breaking news\", \"body\": \"This is breaking news\"}}}" https://fcm.googleapis.com/v1/projects/[PROJECT_NAME]/messages:send

يمكن العثور على $topic_name أعلاه في رمز تطبيق Android المذكور في مشروع Firebase وإعداد تطبيق Android. القيمة التلقائية هي "weather".

• بعد تسليم الرسالة بنجاح، من المفترض أن يظهر إشعار منبثق على شاشتك، على غرار الصورة أدناه:

6. الخاتمة

تهانينا! لقد أكملت بنجاح تجربة الترميز من خلال اتّباع الخطوات التالية:

• إعداد مشروع Firebase
• دمج Firebase مع تطبيق Android
• إنشاء بيانات اعتماد للإصدار 1 من واجهة برمجة تطبيقات HTTP الخاصة بخدمة "المراسلة عبر السحابة الإلكترونية من Firebase"
• إرسال رسالة إلى تطبيقك من خلال الإصدار 1 من واجهة برمجة التطبيقات HTTP الخاصة بخدمة "المراسلة عبر السحابة الإلكترونية من Firebase"

لاستكشاف الميزات المتقدّمة التي يوفّرها FCM، يمكنك الاستفادة من المراجع التالية:

• إنشاء إشعارات مرئية باستخدام "المراسلة عبر السحابة الإلكترونية من Firebase"
• كيفية الحصول على إحصاءات أفضل حول تسليم الإشعارات الفورية
• استهداف شرائح الجمهور باستخدام Cloud Messaging