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

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

  • تفوض واجهة برمجة التطبيقات 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. للحصول على أقصى قدر من التشغيل الآلي لمسار التفويض، استخدِم أداة "إدارة الأذونات" مع مكتبات خادم حزمة "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) الخاص بالمشرف هذه الاستراتيجية. لا يحدّد المثال بيانات اعتماد التطبيق صراحةً. ومع ذلك، يمكن لخدمة "إدارة بيانات اعتماد التطبيقات" العثور على بيانات الاعتماد بشكل ضمني ما دامت متغيّرة البيئة مضبوطة، أو ما دام التطبيق قيد التشغيل على 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 الذي يحتوي على مفتاح حساب الخدمة. لا ينطبق هذا المتغيّر إلا على جلسة Shell الحالية، لذا إذا فتحت جلسة جديدة، اضبط المتغيّر مرة أخرى.

نظام التشغيل 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 Auth Library بلغتك المفضّلة لاسترداد رمز وصول صالح لفترة قصيرة من خلال بروتوكول OAuth 2.0:

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

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

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

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

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

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

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

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

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

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

إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0‏ ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0‏. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers‏. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.

تاريخ التعديل الأخير: 2024-11-22 (حسب التوقيت العالمي المتفَّق عليه)