على التطبيقات التي تستخدم واجهات برمجة التطبيقات القديمة للمراسلة عبر السحابة الإلكترونية من Firebase لبروتوكول HTTP وXMPP نقل بياناتها إلى الإصدار 1 من واجهة برمجة التطبيقات لبروتوكول HTTP في أقرب فرصة ممكنة. تم إيقاف إرسال الرسائل (بما في ذلك الرسائل الواردة) باستخدام واجهات برمجة التطبيقات هذه نهائيًا في 20 حزيران (يونيو) 2023، وسيبدأ الإيقاف نهائيًا في 22 تموز (يوليو) 2024.
مزيد من المعلومات حول الميزات المتأثّرة
بالإضافة إلى الدعم المستمر والميزات الجديدة، توفّر واجهة برمجة التطبيقات HTTP v1 هذه المزايا عن واجهات برمجة التطبيقات القديمة:
تحسين الأمان من خلال رموز الدخول تستخدم واجهة برمجة التطبيقات HTTP v1 رموز وصول قصيرة الأجل وفقًا لنموذج الأمان OAuth2. في حال أصبحت علامة أمان الوصول علنية، لا يمكن استخدامها بشكل ضار إلا لمدة ساعة أو نحو ذلك قبل أن تنتهي صلاحيتها. لا يتم إرسال رموز إعادة التنشيط بنفس معدل مفاتيح الأمان المستخدَمة في واجهة برمجة التطبيقات القديمة، لذا من غير المرجّح أن يتم الاستيلاء عليها.
تخصيص أكثر فعالية للرسائل على الأنظمة الأساسية: بالنسبة إلى نص الرسالة، تحتوي واجهة برمجة التطبيقات HTTP v1 على مفاتيح شائعة تؤدي إلى جميع المثيلات المستهدَفة، بالإضافة إلى مفاتيح خاصة بالنظام الأساسي تتيح لك تخصيص الرسالة على جميع الأنظمة الأساسية. يتيح لك ذلك إنشاء "عمليات إلغاء" تُرسِل حمولات بيانات مختلفة قليلاً إلى الأنظمة الأساسية المختلفة للعملاء في رسالة واحدة.
إمكانية توسيع نطاق استخدامها بشكل أكبر وملاءمتها للمستقبل مع الإصدارات الجديدة من منصّات العملاء: تتيح واجهة برمجة التطبيقات HTTP v1 خيارات المراسلة المتاحة بالكامل على منصات Apple وAndroid و الويب. بما أنّ كل نظام أساسي يتضمّن وحدة محدّدة في الحمولة بتنسيق JSON، يمكن لـ FCM توسيع نطاق واجهة برمجة التطبيقات ليشمل الإصدارات الجديدة والأنظمة الأساسية الجديدة حسب الحاجة.
تعديل نقطة نهاية الخادم
يختلف عنوان URL لنقطة النهاية لواجهة برمجة تطبيقات HTTP v1 عن نقطة النهاية القديمة بالطرق التالية:
- وهو متوفر بإصدارات مختلفة، مع تضمين
/v1
في المسار. - يحتوي المسار على رقم تعريف مشروع Firebase لتطبيقك بالتنسيق
/projects/myproject-ID/
. يتوفّر هذا المعرّف في علامة التبويب الإعدادات العامة للمشروع في وحدة تحكّم Firebase. - ويحدِّد صراحةً طريقة
send
على أنّها:send
.
لتعديل نقطة نهاية الخادم للإصدار 1 من HTTP، أضِف هذه العناصر إلى نقطة النهاية في عنوان طلبات الإرسال.
طلبات HTTP قبل ذلك
POST https://fcm.googleapis.com/fcm/send
طلبات XMPP قبل
يتم إرسال رسائل XMPP القديمة عبر اتصال بنقطة النهاية التالية:
fcm-xmpp.googleapis.com:5235
بعد
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
تعديل تفويض طلبات الإرسال
بدلاً من سلسلة مفتاح الخادم المستخدمة في الطلبات القديمة، تتطلب طلبات الإرسال HTTP v1 رمز الدخول OAuth 2.0. إذا كنت تستخدم SDK للمشرف لإرسال الرسائل،
ستتعامل المكتبة مع الرمز المميز لك. إذا كنت تستخدم بروتوكول Authorization: Bearer <valid Oauth 2.0 token>
الخام، احصل على الرمز المميّز كما هو موضّح في هذا القسم وأضفه إلى Authorization: Bearer <valid Oauth 2.0 token>
.
قبل
Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA
بعد
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
اعتمادًا على تفاصيل بيئة الخادم، يمكنك استخدام مجموعة من هذه الاستراتيجيات لمصادقة طلبات الخادم لخدمات Firebase:
- بيانات الاعتماد التلقائية لتطبيقات Google (ADC)
- ملف JSON لحساب الخدمة
- يشير هذا المصطلح إلى رمز دخول قصير الأجل من نوع OAuth 2.0 يتم اشتقاقه من حساب الخدمة.
إذا كان تطبيقك يعمل على Compute Engine أو Google Kubernetes Engine أو App Engine أو دوال Cloud (بما في ذلك Cloud Functions for Firebase)، استخدِم بيانات الاعتماد التلقائية للتطبيق (ADC). يستخدم "موفِّر بيانات اعتماد التطبيقات" حساب الخدمة التلقائي الحالي لحصول على بيانات الاعتماد لتفويض الطلبات، ويتيح "موفِّر بيانات اعتماد التطبيقات" الاختبار المحلي المرن من خلال متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS. للحصول على أكبر قدر من التشغيل الآلي لتدفق التفويض، استخدِم ADC مع مكتبات خوادم SDK للمشرف.
إذا كان تطبيقك قيد التشغيل في بيئة خادم غير تابع لشركة Google، ستحتاج إلى تنزيل ملف JSON لحساب الخدمة من مشروعك على Firebase. ما دام لديك إذن الوصول إلى نظام ملفات يحتوي على ملف المفتاح الخاص، يمكنك استخدام متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS للسماح بالطلبات باستخدام بيانات الاعتماد هذه التي تم الحصول عليها يدويًا. إذا لم يكن لديك إذن الوصول إلى هذا الملف، عليك الإشارة إلى ملف حساب الخدمة في الرمز البرمجي، ويجب إجراء ذلك بحذر شديد بسبب خطر تعريض بيانات الاعتماد الخاصة بك للخطر.
تقديم بيانات الاعتماد باستخدام أداة إدارة الاعتماد
تتحقق بيانات الاعتماد التلقائية لتطبيق Google (ADC) من بيانات الاعتماد بالترتيب التالي:
يتحقّق ADC مما إذا تم ضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS. في حال ضبط المتغيّر، يستخدم ADC ملف حساب الخدمة الذي يشير إليه المتغيّر.
في حال عدم ضبط متغيّر البيئة، يستخدم ADC حساب الخدمة التلقائي الذي يوفّرهCompute Engine وGoogle Kubernetes Engine وApp Engine و Cloud Functions للتطبيقات التي تعمل على هذه الخدمات.
إذا لم يتمكن ADC من استخدام أي من بيانات الاعتماد أعلاه، فسيعرض النظام خطأ.
يوضح المثال التالي على رمز حزمة تطوير البرامج (SDK) للمشرف هذه الاستراتيجية. لا يحدّد المثال بوضوح بيانات اعتماد التطبيق. ومع ذلك، يمكن لخدمة ADC العثور على بيانات الاعتماد بشكل ضمني ما دامت متغيّرة البيئة مضبوطة، أو ما دام التطبيق قيد التشغيل على Compute Engine أو Google Kubernetes Engine أو App Engine أو Cloud Functions.
Node.js
admin.initializeApp({
credential: admin.credential.applicationDefault(),
});
جافا
FirebaseOptions options = FirebaseOptions.builder()
.setCredentials(GoogleCredentials.getApplicationDefault())
.setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
.build();
FirebaseApp.initializeApp(options);
Python
default_app = firebase_admin.initialize_app()
انتقال
app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
log.Fatalf("error initializing app: %v\n", err)
}
#C
FirebaseApp.Create(new AppOptions()
{
Credential = GoogleCredential.GetApplicationDefault(),
});
تقديم بيانات الاعتماد يدويًا
تتوافق مشاريع Firebase مع حسابات خدمة Google، التي يمكنك استخدامها لطلب واجهات برمجة تطبيقات خادم Firebase من خادم تطبيقك أو بيئة موثوق بها. إذا كنت تُطوّر الرمز البرمجي على الجهاز أو تنشر تطبيقك على الأجهزة، يمكنك استخدام بيانات الاعتماد التي تم الحصول عليها من خلال حساب الخدمة هذا لتفويض طلبات الخادم.
لمصادقة حساب خدمة وتفويضه للوصول إلى خدمات Firebase، عليك إنشاء ملف مفتاح خاص بتنسيق JSON.
لإنشاء ملف مفتاح خاص لحساب الخدمة:
في وحدة تحكّم Firebase، افتح الإعدادات > حسابات الخدمة.
انقر على إنشاء مفتاح خاص جديد، ثم أكِّد بالنقر على إنشاء مفتاح.
تخزين ملف JSON الذي يحتوي على المفتاح بأمان
عند التفويض من خلال حساب خدمة، لديك خياران لتقديم ملف ملف تعريف الاعتماد لتطبيقك. يمكنك ضبط متغيّر بيئة GOOGLE_APPLICATION_CREDENTIALS أو تمرير المسار بشكلٍ صريح إلى مفتاح حساب الخدمة في الرمز البرمجي. الخيار الأول أكثر أمانًا وننصح به بشدة.
لضبط متغيّر البيئة:
اضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار ملف JSON الذي يحتوي على مفتاح حساب الخدمة لا ينطبق هذا المتغير إلا على جلسة الغلاف الحالية، لذا إذا فتحت جلسة جديدة، اضبط المتغيّر مرة أخرى.
نظام التشغيل Linux أو macOS
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"
Windows
باستخدام PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"
بعد إكمال الخطوات أعلاه، يمكن لـ "بيانات الاعتماد التلقائية للتطبيقات" (ADC) تحديد بيانات اعتمادك بشكل ضمني، ما يتيح لك استخدام بيانات اعتماد حساب الخدمة عند الاختبار أو التشغيل في بيئات غير تابعة لشركة Google.
استخدام بيانات الاعتماد لإنشاء رموز الدخول
استخدِم بيانات اعتماد Firebase مع مكتبة مصادقة Google بلغتك المفضّلة لاسترداد رمز دخول OAuth 2.0 قصير الأجل:
عقدة.js
function getAccessToken() {
return new Promise(function(resolve, reject) {
const key = require('../placeholders/service-account.json');
const jwtClient = new google.auth.JWT(
key.client_email,
null,
key.private_key,
SCOPES,
null
);
jwtClient.authorize(function(err, tokens) {
if (err) {
reject(err);
return;
}
resolve(tokens.access_token);
});
});
}
في هذا المثال، تُجري مكتبة برامج Google API مصادقة الطلب باستخدام رمز مميّز على شبكة JSON أو JWT. لمزيد من المعلومات، راجِع رموز JSON المميّزة للويب.
Python
def _get_access_token():
"""Retrieve a valid access token that can be used to authorize requests.
:return: Access token.
"""
credentials = service_account.Credentials.from_service_account_file(
'service-account.json', scopes=SCOPES)
request = google.auth.transport.requests.Request()
credentials.refresh(request)
return credentials.token
جافا
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();
}
بعد انتهاء صلاحية رمز الدخول، يتم استدعاء طريقة إعادة تحميل الرمز تلقائيًا لاسترداد رمز دخول معدَّل.
لمنح الإذن بالوصول إلى FCM، يُرجى طلب النطاق
https://www.googleapis.com/auth/firebase.messaging
.
لإضافة رمز الوصول إلى عنوان طلب HTTP:
أضِف الرمز المميّز كقيمة للعنوان Authorization
بالتنسيق Authorization: Bearer <access_token>
:
node.js
headers: {
'Authorization': 'Bearer ' + accessToken
}
Python
headers = {
'Authorization': 'Bearer ' + _get_access_token(),
'Content-Type': 'application/json; UTF-8',
}
جافا
URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getServiceAccountAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;
تعديل الحمولة لطلبات الإرسال
يُجري الإصدار 1 من FCM HTTP تغييرًا كبيرًا في بنية حمولة رسالة JSON. تضمن هذه التغييرات في المقام الأول معالجة الرسائل بشكلٍ صحيح عند استلامها على منصات العملاء المختلفة. بالإضافة إلى ذلك، تمنحك التغييرات مرونة إضافية لتخصيص حقول الرسائل أو "تجاوزها" لكل منصة.
بالإضافة إلى فحص الأمثلة الواردة في هذا القسم، يمكنك الاطّلاع على مقالة تخصيص رسالة على جميع المنصات ومراجعة مرجع واجهة برمجة التطبيقات للتعرّف على HTTP v1.
مثال: رسالة إشعار بسيطة
في ما يلي مقارنة بين بيانات أساسية بسيطة جدًا للإشعار، تحتوي على الحقول
title
وbody
وdata
فقط، توضّح الاختلافات الأساسية
في بيانات HTTP القديمة والإصدار 1.
قبل
{
"to": "/topics/news",
"notification": {
"title": "Breaking News",
"body": "New news story available."
},
"data": {
"story_id": "story_12345"
}
}
بعد
{
"message": {
"topic": "news",
"notification": {
"title": "Breaking News",
"body": "New news story available."
},
"data": {
"story_id": "story_12345"
}
}
}
مثال: بيانات JSON متداخلة
على عكس واجهة برمجة التطبيقات القديمة للمراسلة، لا تتيح واجهة برمجة التطبيقات HTTP v1 قيم JSON المضمّنة في الحقل data
.
يجب إجراء تحويل من تنسيق JSON إلى سلسلة.
قبل
{
...
"data": {
"keysandvalues": {"key1": "value1", "key2": 123}
}
}
بعد
{
"message": {
...
"data": {
"keysandvalues": "{\"key1\": \"value1\", \"key2\": 123}"
}
}
}
مثال: استهداف أنظمة أساسية متعددة
لتفعيل استهداف الأنظمة الأساسية المتعددة، كانت واجهة برمجة التطبيقات القديمة تُجري عمليات إلغاء في الخلفية. على النقيض من ذلك، يوفّر الإصدار HTTP 1 كتل مفاتيح خاصة بالنظام الأساسي تصنع أي اختلافات بين الأنظمة الأساسية بشكل صريح ومرئي للمطوّر. يتيح لك ذلك استهداف منصات متعدّدة دائمًا بطلب واحد، كما هو موضّح في العينة التالية.
قبل
// Android
{
"to": "/topics/news",
"notification": {
"title": "Breaking News",
"body": "New news story available.",
"click_action": "TOP_STORY_ACTIVITY"
},
"data": {
"story_id": "story_12345"
}
}
// Apple
{
"to": "/topics/news",
"notification": {
"title": "Breaking News",
"body": "New news story available.",
"click_action": "HANDLE_BREAKING_NEWS"
},
"data": {
"story_id": "story_12345"
}
}
بعد
{
"message": {
"topic": "news",
"notification": {
"title": "Breaking News",
"body": "New news story available."
},
"data": {
"story_id": "story_12345"
},
"android": {
"notification": {
"click_action": "TOP_STORY_ACTIVITY"
}
},
"apns": {
"payload": {
"aps": {
"category" : "NEW_MESSAGE_CATEGORY"
}
}
}
}
}
مثال: التخصيص باستخدام عمليات إلغاء النظام الأساسي
بالإضافة إلى تبسيط استهداف الرسائل من عدّة منصات، توفّر واجهة برمجة التطبيقات HTTP v1 API المرونة لتخصيص الرسائل لكل نظام أساسي.
قبل
// Android
{
"to": "/topics/news",
"notification": {
"title": "Breaking News",
"body": "Check out the Top Story.",
"click_action": "TOP_STORY_ACTIVITY"
},
"data": {
"story_id": "story_12345"
}
}
// Apple
{
"to": "/topics/news",
"notification": {
"title": "Breaking News",
"body": "New news story available.",
"click_action": "HANDLE_BREAKING_NEWS"
},
"data": {
"story_id": "story_12345"
}
}
بعد
{
"message": {
"topic": "news",
"notification": {
"title": "Breaking News",
"body": "New news story available."
},
"data": {
"story_id": "story_12345"
},
"android": {
"notification": {
"click_action": "TOP_STORY_ACTIVITY",
"body": "Check out the Top Story"
}
},
"apns": {
"payload": {
"aps": {
"category" : "NEW_MESSAGE_CATEGORY"
}
}
}
}
}
مثال: استهداف أجهزة معيّنة
لاستهداف أجهزة محدّدة باستخدام واجهة برمجة التطبيقات HTTP v1، قدِّم رمز تسجيل الجهاز
الحالي في مفتاح token
بدلاً من
مفتاح to
.
قبل
{ "notification": {
"body": "This is an FCM notification message!",
"title": "FCM Message"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
بعد
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"body":"This is an FCM notification message!",
"title":"FCM Message"
}
}
}
للاطّلاع على مزيد من النماذج والمعلومات حول واجهة برمجة التطبيقات FCM HTTP v1 API، يمكنك الاطّلاع على ما يلي:
إرشادات حول طريقة إنشاء طلبات إرسال خادم التطبيق باستخدام HTTP v1 API تستخدم جميع المقتطفات من أسلوب "REST" واجهة برمجة التطبيقات v1 ما لم يُذكر خلاف ذلك.