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

على التطبيقات التي تستخدم واجهات برمجة التطبيقات القديمة للمراسلة عبر السحابة الإلكترونية من Firebase لبروتوكول HTTP وXMPP نقل بياناتها إلى الإصدار 1 من واجهة برمجة التطبيقات لبروتوكول HTTP في أقرب فرصة ممكنة. تم إيقاف ميزة إرسال الرسائل (بما في ذلك الرسائل الرئيسية) باستخدام واجهات برمجة التطبيقات هذه نهائيًا في 20 حزيران (يونيو) 2023 وستبدأ عملية الإيقاف في 22 تموز (يوليو) 2024.

مزيد من المعلومات حول الميزات المتأثّرة

بالإضافة إلى الدعم المستمر والميزات الجديدة، توفّر واجهة برمجة التطبيقات HTTP v1 الميزات التالية مقارنةً بواجهات برمجة التطبيقات القديمة:

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

• تخصيص الرسائل بفعالية أكبر على جميع المنصات: بالنسبة إلى جسد الرسالة، تحتوي واجهة برمجة التطبيقات HTTP v1 API على مفاتيح شائعة تنتقل إلى جميع النُسخ المستهدَفة، بالإضافة إلى مفاتيح خاصة بالمنصة تتيح لك تخصيص الرسالة على جميع المنصات. يتيح لك ذلك إنشاء "عمليات إلغاء" تُرسِل حمولات بيانات مختلفة قليلاً إلى الأنظمة الأساسية المختلفة للعملاء في رسالة واحدة.

• إمكانية توسيع نطاق استخدامها بشكل أكبر وملاءمتها للمستقبل مع الإصدارات الجديدة من منصّات العملاء: تتيح واجهة برمجة التطبيقات HTTP v1 خيارات المراسلة المتاحة بالكامل على منصات Apple وAndroid و الويب. بما أنّ كل نظام أساسي يتضمّن وحدة محدّدة في الحمولة بتنسيق JSON، يمكن لـ FCM توسيع نطاق واجهة برمجة التطبيقات ليشمل الإصدارات الجديدة والأنظمة الأساسية الجديدة حسب الحاجة.

تعديل نقطة نهاية الخادم

يختلف عنوان URL لنقطة النهاية لواجهة برمجة تطبيقات HTTP v1 عن نقطة النهاية القديمة بالطرق التالية:

• وهو متوفر بإصدارات مختلفة، مع تضمين /v1 في المسار.
• يحتوي المسار على رقم تعريف مشروع Firebase لتطبيقك بالتنسيق /projects/myproject-ID/. يتوفّر هذا المعرّف في علامة التبويب الإعدادات العامة للمشروع في وحدة تحكّم Firebase.
• ويحدِّد صراحةً طريقة send على أنّها :send.

لتعديل نقطة نهاية الخادم لإصدار HTTP 1، أضِف هذه العناصر إلى نقطة النهاية في عنوان طلبات الإرسال.

طلبات 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 Functions (بما في ذلك Cloud Functions for Firebase)، استخدِم "بيانات الاعتماد التلقائية للتطبيق" (ADC). يستخدم "موفِّر بيانات اعتماد التطبيقات" حساب الخدمة التلقائي الحالي لحصول على بيانات الاعتماد لتفويض الطلبات، ويتيح "موفِّر بيانات اعتماد التطبيقات" الاختبار المحلي المرن من خلال متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS. للحصول على أقصى قدر من التشغيل الآلي لمسار التفويض، استخدِم أداة "إدارة الأذونات" مع مكتبات خادم حزمة "SDK للمشرف".

إذا كان تطبيقك قيد التشغيل في بيئة خادم غير تابع لشركة Google، ستحتاج إلى تنزيل ملف JSON لحساب الخدمة من مشروعك على Firebase. ما دام بإمكانك الوصول إلى نظام ملفات يحتوي علىملف المفتاح الخاص، يمكنك استخدام متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS لتفويض الطلبات باستخدام بيانات الاعتماد التي تم الحصول عليها يدويًا. إذا لم يكن لديك إذن الوصول إلى هذا الملف، عليك الإشارة إلى ملف حساب الخدمة في الرمز البرمجي، ويجب إجراء ذلك بحذر شديد بسبب خطر تعريض بيانات الاعتماد الخاصة بك للخطر.

تقديم بيانات الاعتماد باستخدام ADC

تتحقّق بيانات الاعتماد التلقائية لتطبيق Google (ADC) من بيانات اعتمادك بالترتيب التالي:

1. تتحقّق ADC مما إذا تم ضبط متغير البيئة GOOGLE_APPLICATION_CREDENTIALS أم لا. في حال ضبط المتغيّر، يستخدم ADC ملف حساب الخدمة الذي يشير إليه المتغيّر.

2. في حال عدم ضبط متغيّر البيئة، يستخدم ADC حساب الخدمة التلقائي الذي يوفّرهCompute Engine وGoogle Kubernetes Engine وApp Engine و Cloud Functions للتطبيقات التي تعمل على هذه الخدمات.

3. إذا لم يتمكّن "موفِّر خدمات إدارة البيانات" من استخدام أيّ من بيانات الاعتماد أعلاه، يُرسِل النظام رسالة خطأ.

يوضّح مثال رمز حزمة تطوير البرامج (SDK) الخاص بالمشرف هذه الاستراتيجية. لا يحدّد المثال بوضوح بيانات اعتماد التطبيق. ومع ذلك، يمكن لخدمة ADC العثور على بيانات الاعتماد بشكل ضمني ما دامت متغيّرة البيئة مضبوطة، أو ما دام التطبيق قيد التشغيل على Compute Engine أو Google Kubernetes Engine أو App Engine أو Cloud Functions.

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

default_app = firebase_admin.initialize_app()

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}
init.go

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

تقديم بيانات الاعتماد يدويًا

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

لمصادقة حساب خدمة وتفويضه للوصول إلى خدمات Firebase، عليك إنشاء ملف مفتاح خاص بتنسيق JSON.

لإنشاء ملف مفتاح خاص لحساب الخدمة:

1. في وحدة تحكّم Firebase، افتح الإعدادات > حسابات الخدمة.

2. انقر على إنشاء مفتاح خاص جديد، ثم أكِّد ذلك بالنقر على إنشاء مفتاح.

3. تخزين ملف JSON الذي يحتوي على المفتاح بأمان

عند التفويض من خلال حساب خدمة، لديك خياران لتقديم ملف ملف تعريف الاعتماد لتطبيقك. يمكنك ضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS أو يمكنك تمرير المسار إلى مفتاح حساب الخدمة في الرمز البرمجي بشكل صريح. الخيار الأول أكثر أمانًا وننصح به بشدة.

لضبط متغيّر البيئة:

اضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار ملف JSON الذي يحتوي على مفتاح حساب الخدمة لا ينطبق هذا المتغيّر إلا على جلسة shell الحالية، لذا إذا فتحت جلسة جديدة، اضبط المتغيّر مرة أخرى.

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

بعد إكمال الخطوات أعلاه، يمكن لـ "بيانات الاعتماد التلقائية للتطبيقات" (ADC) تحديد بيانات اعتمادك بشكل ضمني، ما يتيح لك استخدام بيانات اعتماد حساب الخدمة عند الاختبار أو التشغيل في بيئات غير تابعة لشركة Google.

استخدام بيانات الاعتماد لإنشاء رموز وصول

استخدِم بيانات اعتماد Firebase مع مكتبة Google Auth Library بلغتك المفضّلة لاسترداد رمز وصول صالح لفترة قصيرة من خلال بروتوكول OAuth 2.0:

 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);
    });
  });
}
index.js

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
messaging.py

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();
}
Messaging.java

بعد انتهاء صلاحية رمز الدخول، يتم استدعاء طريقة إعادة تحميل الرمز تلقائيًا لاسترداد رمز دخول معدَّل.

لمنح الإذن بالوصول إلى FCM، يُرجى طلب النطاق https://www.googleapis.com/auth/firebase.messaging.

لإضافة رمز الوصول إلى عنوان طلب HTTP:

أضِف الرمز المميّز كقيمة لعنوان Authorization بالتنسيق Authorization: Bearer <access_token>:

headers: {
  'Authorization': 'Bearer ' + accessToken
}
index.js

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}
messaging.py

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;
FirebaseMessagingSnippets.java

تعديل الحمولة لطلبات الإرسال

يُجري الإصدار 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 ما لم يُذكر خلاف ذلك.

• مدونة Firebase