تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

إذا كان تطبيقك قيد التشغيل على Compute Engine، وظائف Google Kubernetes Engine أو App Engine أو السحابة الإلكترونية (بما في ذلك Cloud Functions for Firebase)، استخدم بيانات الاعتماد التلقائية للتطبيق (ADC). يستخدم ADC الخدمة التلقائية الحالية حساب للحصول على بيانات الاعتماد اللازمة لمصادقة الطلبات، وتتيح ADC اختبار محلي مرن عبر متغير البيئة GOOGLE_APPLICATION_CREDENTIALS للحصول على أكبر قدر من التشغيل الآلي تدفق التفويض، يمكنك استخدام ADC مع مكتبات خوادم SDK للمشرف.

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

تقديم بيانات الاعتماد باستخدام ADC

تتحقّق بيانات الاعتماد التلقائية لتطبيق Google (ADC) من بيانات الاعتماد. بالترتيب التالي:

تتحقق ADC مما إذا كان متغير البيئة تم ضبط GOOGLE_APPLICATION_CREDENTIALS. وإذا تم تعيين المتغير، يستخدم ADC ملف حساب الخدمة الذي يشير إليه المتغير.
إذا لم يتم ضبط متغيّر البيئة، ستستخدم ADC حساب الخدمة التلقائي. أن Compute Engine، Google Kubernetes Engine، App Engine، بينما توفر وظائف السحابة الإلكترونية للتطبيقات التي تعمل على تلك الخدمات.
إذا لم يتمكن ADC من استخدام أي من بيانات الاعتماد أعلاه، سيعرض النظام خطأ.

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

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 .

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

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

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

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

إذا ظهرت لك أخطاء في المصادقة عند إرسال الرسائل، تحقَّق من الصلاحية. من مفتاح الخادم. على سبيل المثال، على نظام التشغيل 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 حاليًا مع STARTإضافة بروتوكول أمان طبقة النقل (TLS).
يتطلب 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 القديم قائمة بجميع المَعلمات التي يمكن أن تحتوي عليها رسالتك.