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

تفويض إرسال الطلبات

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

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

تفويض إرسال طلبات HTTP v1

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

بيانات الاعتماد الافتراضية لتطبيق Google (ADC)
ملف JSON لحساب الخدمة
رمز دخول OAuth 2.0 قصير العمر مشتق من حساب خدمة

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

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

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

تتحقق بيانات الاعتماد الافتراضية لتطبيق Google (ADC) من بيانات الاعتماد الخاصة بك بالترتيب التالي:

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

يوضح المثال التالي لرمز Admin 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);

بايثون

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.

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

في وحدة تحكم Firebase ، افتح الإعدادات> حسابات الخدمة .
انقر فوق إنشاء مفتاح خاص جديد ، ثم قم بالتأكيد بالنقر فوق إنشاء مفتاح .
قم بتخزين ملف JSON الذي يحتوي على المفتاح بشكل آمن.

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

لتعيين متغير البيئة:

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

Linux أو macOS

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.

استخدم بيانات الاعتماد لصك رموز الوصول

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

استخدم بيانات اعتماد Firebase مع مكتبة مصادقة Google للغتك المفضلة لاسترداد رمز وصول 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 الطلب باستخدام رمز ويب JSON أو JWT. لمزيد من المعلومات ، راجع رموز الويب JSON .

بايثون

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.refreshAccessToken();
  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

بايثون

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 " + getAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;Messaging.java

تخويل بروتوكول قديم إرسال الطلبات

باستخدام بروتوكول HTTP القديم ، يجب أن يحتوي كل طلب على مفتاح الخادم من علامة التبويب Cloud Messaging في جزء إعدادات وحدة تحكم Firebase. بالنسبة إلى XMPP ، يجب عليك استخدام نفس مفتاح الخادم لإنشاء اتصال.

ترحيل مفاتيح الخادم القديم

بدءًا من مارس 2020 ، توقف FCM عن إنشاء مفاتيح خادم قديمة. ستستمر مفاتيح الخادم القديمة الحالية في العمل ، لكننا نوصي باستخدام الإصدار الأحدث من مفتاح الخادم المسمى مفتاح Server في وحدة تحكم Firebase بدلاً من ذلك.

إذا كنت ترغب في حذف مفتاح خادم قديم موجود ، فيمكنك القيام بذلك في Google Cloud Console .

تفويض طلبات HTTP

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

Authorization : مفتاح = YOUR_SERVER_KEY
تأكد من أن هذا هو مفتاح الخادم ، الذي تتوفر قيمته في علامة التبويب Cloud Messaging في جزء إعدادات وحدة تحكم Firebase. يتم رفض مفاتيح Android و Apple Platform والمتصفح بواسطة FCM.
Content-Type : application/json for 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) ومفتاح الخادم ككلمة مرور. تتوفر هذه القيم في علامة التبويب Cloud Messaging في جزء إعدادات وحدة تحكم 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 ، مع توفير مفتاح الخادم من علامة التبويب Cloud Messaging في جزء إعدادات وحدة تحكم 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 القديم قائمة بجميع المعلمات التي يمكن أن تحتويها رسالتك.