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

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

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

السماح بطلبات الإرسال من خلال الإصدار 1 من بروتوكول HTTP

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

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

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

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

Node.js

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

Java

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

FirebaseApp.initializeApp(options);

Python

default_app = firebase_admin.initialize_app()

Go

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

C#‎

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

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

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

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

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

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

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

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

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

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

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

Linux أو macOS

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

شبابيك

باستخدام PowerShell:

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

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

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

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

استخدِم بيانات اعتماد 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);
    });
  });
}
index.js

في هذا المثال، تصادق مكتبة برامج واجهة 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
messaging.py

Java

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

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

لمنح الإذن بالوصول إلى خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، عليك طلب النطاق https://www.googleapis.com/auth/firebase.messaging.

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

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

عقدة.js

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

Python

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

Java

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، توقّفت خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" عن إنشاء مفاتيح الخادم القديمة. وسيستمر عمل مفاتيح الخادم القديمة الحالية، ولكن ننصحك بدلاً من ذلك باستخدام الإصدار الأحدث من المفتاح الذي يحمل اسم مفتاح الخادم في وحدة تحكُّم Firebase.

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

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

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

  • Authorization: key=YOUR_SERVER_KEY
    تأكَّد من أنّ هذا هو مفتاح الخادم الذي تتوفر قيمته في علامة التبويب المراسلة عبر السحابة الإلكترونية ضمن لوحة الإعدادات في وحدة تحكُّم Firebase. رفضت ميزة "المراسلة عبر السحابة الإلكترونية من Firebase" مفاتيح Android ونظام Apple الأساسي والمتصفّح.
  • 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 القديم قائمة بجميع المعلمات التي يمكن أن تحتوي عليها رسالتك.

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

إذا ظهرت لك أخطاء في المصادقة عند إرسال الرسائل، تحقَّق من صلاحية مفتاح الخادم. على سبيل المثال، على نظام التشغيل Linux، شغِّل الأمر التالي:

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\"]}"

إذا تلقيت رمز حالة HTTP 401، فإن مفتاح الخادم غير صالح.

تفويض اتصال XMPP

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

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

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

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

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

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

توضح المقتطفات التالية كيفية إجراء المصادقة والتفويض لاتصال XMPP بخدمة "المراسلة عبر السحابة الإلكترونية من Firebase".

خادم XMPP

يطلب خادم XMPP الاتصال بميزة "المراسلة عبر السحابة الإلكترونية من Firebase"

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

المراسلة عبر السحابة الإلكترونية من Firebase

تفتح خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" الاتصال وتطلب آلية للمصادقة، بما في ذلك طريقة 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>

المراسلة عبر السحابة الإلكترونية من Firebase

<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">

المراسلة عبر السحابة الإلكترونية من Firebase

<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>

المراسلة عبر السحابة الإلكترونية من Firebase

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

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

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