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

الطلبات المُرسَلة إلى خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" من خادم تطبيقك أو البيئة الموثوق بها موافقًا عليه. لاحظ هذه الاختلافات المهمة بين تفويض واجهة برمجة التطبيقات HTTP API و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 بينما توفر وظائف السحابة الإلكترونية للتطبيقات التي تعمل على هذه الخدمات.

  3. إذا لم يتمكن 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)
}
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"

Windows

باستخدام 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

جافا

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

جافا

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: المفتاح=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") مفيدًا لعزل المستخدمين الحقيقيين عن رمز الاختبار. اختبار الأجهزة واختبار الرمز للاتصال بها على fcm-xmpp.googleapis.com:5236 استخدام معرّف مختلف للمُرسِل في خدمة "المراسلة عبر السحابة الإلكترونية من 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 القديم قائمة بجميع المَعلمات التي يمكن أن تحتوي عليها رسالتك.