السماح بطلبات الإرسال

يجب أن تكون الطلبات المُرسَلة إلى FCM من خادم تطبيقك أو البيئة الموثوق بها مُصرَّحًا بها. يُرجى مراعاة هذه الاختلافات المهمة بين واجهة برمجة التطبيقات HTTP API القديمة المتوقّفة نهائيًا وتفويض واجهة برمجة التطبيقات HTTP v1:

• تفوض واجهة برمجة التطبيقات FCM HTTP v1 الطلبات باستخدام رمز دخول OAuth 2.0 صالح لفترة قصيرة. لإنشاء هذا الرمز المميّز، يمكنك استخدام ملف "سمات Google الافتراضية" لتطبيقك (في بيئات خوادم Google) و/أو الحصول يدويًا على "سمات الاعتماد المطلوبة" من ملف مفتاح خاص بتنسيق JSON تم إنشاؤه لحساب خدمة. إذا كنت تستخدم Firebase Admin SDK لإرسال الرسائل، ستتولى المكتبة التعامل مع الرمز المميّز نيابةً عنك.
• لا يمكن للبروتوكولات القديمة المتوقّفة نهائيًا استخدام مفاتيح واجهة برمجة التطبيقات صالحة لمدة طويلة إلا من خلال وحدة تحكّم Firebase.

السماح بإرسال طلبات HTTP v1

استنادًا إلى تفاصيل بيئة الخادم، استخدِم مجموعة من هذه الاستراتيجيات لتفويض طلبات الخادم إلى خدمات Firebase:

• بيانات الاعتماد التلقائية لتطبيق Google (ADC)
• ملف JSON لحساب الخدمة
• يشير هذا المصطلح إلى رمز دخول قصير الأجل من نوع OAuth 2.0 يتم اشتقاقه من حساب الخدمة.

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

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.

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

ما لم تكن تستخدم SDK للمشرف، التي تعالج التفويض تلقائيًا، ستحتاج إلى إنشاء رمز الدخول وإضافته لإرسال الطلبات.

استخدِم بيانات اعتماد 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

السماح بطلبات إرسال البروتوكول القديم

باستخدام بروتوكول HTTP القديم، يجب أن يشتمل كل طلب على مفتاح الخادم من علامة تبويب المراسلة عبر السحابة الإلكترونية في لوحة الإعدادات في وحدة تحكم Firebase. بالنسبة إلى بروتوكول XMPP، يجب استخدام مفتاح الخادم نفسه لإنشاء اتصال.

نقل مفاتيح الخادم القديم

اعتبارًا من آذار (مارس) 2020، توقّفت FCM عن إنشاء مفاتيح الخادم القديمة. سيستمر عمل مفاتيح الخادم القديمة الحالية، ولكننا ننصح باستخدام الإصدار الأحدث من المفتاح المُصنَّف مفتاح الخادم في وحدة تحكّم Firebase بدلاً من ذلك.

إذا أردت حذف مفتاح خادم قديم حالي، يمكنك إجراء ذلك في console Google Cloud.

السماح بطلبات HTTP

يتألّف طلب الرسالة من جزأين: رأس HTTP ونص HTTP. يجب أن يحتوي رأس HTTP على العناوين التالية:

• Authorization: key=YOUR_SERVER_KEY
  تأكَّد من أنّ هذا هو مفتاح الخادم الذي تتوفّر قيمته في علامة التبويب المراسلة عبر السحابة الإلكترونية ضمن لوحة الإعدادات في وحدة التحكّم في Firebase. تم رفض مفاتيح Android ونظام Apple الأساسي والمتصفّح من قِبل "FCM".
• ‫Content-Type: application/json لتنسيق JSON application/x-www-form-urlencoded;charset=UTF-8 للنص العادي
  في حال حذف Content-Type، يتم افتراض أنّ التنسيق هو نص عادي.

على سبيل المثال:

Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
  "data" : {
    ...
  },
}

راجِع مقالة إنشاء طلبات الإرسال للحصول على التفاصيل الكاملة حول إنشاء طلبات الإرسال. مرجع بروتوكول HTTP القديم: يقدّم قائمة بكل المَعلمات التي يمكن أن تحتوي عليها رسالتك.

api_key=YOUR_SERVER_KEY

curl --header "Authorization: key=$api_key" \
     --header Content-Type:"application/json" \
     https://fcm.googleapis.com/fcm/send \
     -d "{\"registration_ids\":[\"ABC\"]}"

باستخدام بروتوكول XMPP، يمكنك الحفاظ على اتصال دائم وغير متزامن ثنائي الاتجاه بخوادم FCM. يمكن استخدام الاتصال لإرسال الرسائل واستلامها بين خادمك و الأجهزة المتصلة بحساب FCM الخاصة بالمستخدمين.

يمكنك استخدام معظم مكتبات XMPP لإدارة اتصال دائم بخدمة FCM. يتم تشغيل نقطة نهاية XMPP على fcm-xmpp.googleapis.com:5235. عند اختبار الوظائف مع مستخدمين غير مستخدمي الإصدار العلني، عليك الاتصال بالخادم المخصّص للإصدار التجريبي على العنوان التالي: fcm-xmpp.googleapis.com:5236 (يُرجى ملاحظة المنفذ المختلف).

إنّ الاختبار المنتظم في مرحلة ما قبل الإنتاج (وهي بيئة أصغر يتم فيها تشغيل أحدث إصدارات FCM) هو مفيد لعزل المستخدمين الحقيقيين عن رمز الاختبار. يجب استخدام معرّف مُرسِل مختلف في FCM على أجهزة الاختبار ورمز الاختبار للاتصال بـ fcm-xmpp.googleapis.com:5236 لتجنُّب أي مخاطر تتمثل في إرسال رسائل اختبار إلى مستخدمي الإصدار العلني أو إرسال رسائل رئيسية من حركة بيانات الإنتاج عبر اتصالات اختبارية.

هناك شرطان مهمّان للربط:

• عليك بدء اتصال بروتوكول أمان طبقة النقل (TLS). يُرجى العِلم أنّه FCM لا يتيح حاليًا استخدام إضافة STARTTLS.
• تتطلّب FCM آلية مصادقة SASL PLAIN باستخدام <your_FCM_Sender_Id>@fcm.googleapis.com (FCM معرّف المُرسِل) ومفتاح الخادم ككلمة المرور. تتوفر هذه القيم في علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية ضمن لوحة الإعدادات في وحدة تحكم Firebase.

وإذا تعذّر الاتصال في أي وقت، يجب إعادة الاتصال فورًا. لا داعي للتراجع بعد انقطاع الاتصال الذي يحدث بعد المصادقة. بالنسبة إلى كل رقم تعريف مُرسِل، تتيح FCM 2,500 اتصال بالتوازي.

توضِّح المقتطفات التالية كيفية إجراء المصادقة والتفويض لاتصال XMPP بـ FCM.

خادم XMPP

يطلب خادم XMPP الاتصال بخادم FCM

<stream:stream to="fcm.googleapis.com"
        version="1.0" xmlns="jabber:client"
        xmlns:stream="http://etherx.jabber.org/streams">

FCM

يفتح FCM الاتصال ويطلب آلية مصادقة، بما في ذلك طريقة PLAIN.

<stream:features>
  <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl">
    <mechanism>X-OAUTH2</mechanism>
    <mechanism>X-GOOGLE-TOKEN</mechanism>
    <mechanism>PLAIN</mechanism>
  </mechanisms>
</stream:features>

خادم XMPP

يجب أن يستجيب خادم XMPP باستخدام طريقة المصادقة PLAIN، مع تقديم مفتاح الخادم من علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية في لوحة الإعدادات في وحدة تحكُّم Firebase.

<auth mechanism="PLAIN"
xmlns="urn:ietf:params:xml:ns:xmpp-sasl">MTI2MjAwMzQ3OTMzQHByb2plY3RzLmdjbS5hb
mFTeUIzcmNaTmtmbnFLZEZiOW1oekNCaVlwT1JEQTJKV1d0dw==</auth>

FCM

<success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>

خادم XMPP

<stream:stream to="fcm.googleapis.com"
        version="1.0" xmlns="jabber:client"
        xmlns:stream="http://etherx.jabber.org/streams">

FCM

<stream:features>
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"/>
  <session xmlns="urn:ietf:params:xml:ns:xmpp-session"/>
</stream:features>

خادم XMPP

<iq type="set">
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"></bind>
</iq>

FCM

<iq type="result">
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind">
    <jid>SENDER_ID@fcm.googleapis.com/RESOURCE</jid>
  </bind>
</iq>

ملاحظة: لا يستخدم FCM المورد المرتبط أثناء توجيه الرسائل.

راجِع إنشاء طلبات الإرسال للحصول على التفاصيل الكاملة حول إنشاء طلبات الإرسال. يوفر مرجع بروتوكول XMPP القديم قائمة بجميع المعلمات التي يمكن أن تحتوي عليها رسالتك.