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

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

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

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

تقديم بيانات الاعتماد باستخدام أداة إدارة الاعتماد

تتحقّق بيانات الاعتماد التلقائية لتطبيق 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 أو السحابة الإلكترونية

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.

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

ما لم تكن تستخدِم حزمة 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

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

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

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

• Authorization: المفتاح=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-xmpp.googleapis.com:5236 معرّف مُرسِل FCM مختلفًا لتجنُّب أي مخاطر متعلقة بتلقّي رسائل اختبارية من مستخدمي الإصدار العلني أو إرسال رسائل من الإصدار العلني عبر اتصالات اختبارية.

لهذا الاتصال متطلبان مهمان:

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

إذا تعذّر الاتصال في أي وقت، عليك إعادة الاتصال على الفور. لا داعي للتراجع بعد انقطاع الاتصال الذي يحدث بعد المصادقة. لكل معرّف مُرسِل، يسمح FCM بإجراء 2500 عملية اتصال في الوقت نفسه.

توضح المقتطفات التالية كيفية إجراء المصادقة تفويض لاتصال 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 القديم: يقدّم قائمة بجميع المَعلمات التي يمكن أن تحتوي عليها رسالتك.