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

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

  • تسمح واجهة برمجة التطبيقات FCM HTTP v1 API للطلبات باستخدام رمز وصول 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، أو Cloud Functions (بما في ذلك Cloud Functions for Firebase)، فاستخدم بيانات اعتماد التطبيق الافتراضية (ADC). تستخدم ADC حساب الخدمة الافتراضي الحالي الخاص بك للحصول على بيانات الاعتماد لتخويل الطلبات، وتتيح ADC الاختبار المحلي المرن عبر متغير البيئة GOOGLE_APPLICATION_CREDENTIALS . للحصول على أقصى قدر من الأتمتة لتدفق التفويض، استخدم ADC مع مكتبات خادم Admin 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 من استخدام أي من بيانات الاعتماد المذكورة أعلاه، فسيقوم النظام بإلقاء خطأ.

يوضح مثال كود Admin 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);

بايثون

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.

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

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

  2. انقر فوق "إنشاء مفتاح خاص جديد" ، ثم أكد ذلك بالنقر فوق "إنشاء مفتاح" .

  3. قم بتخزين ملف JSON الذي يحتوي على المفتاح بشكل آمن.

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

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

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

لينكس أو ماك

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 Auth للغتك المفضلة لاسترداد رمز وصول 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 .

بايثون

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

بايثون

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 القديم، يجب أن يحتوي كل طلب على مفتاح الخادم من علامة التبويب Cloud Messaging في جزء إعدادات وحدة تحكم Firebase. بالنسبة إلى XMPP، يجب عليك استخدام نفس مفتاح الخادم لتأسيس اتصال.

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

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

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

تفويض طلبات HTTP

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

  • Authorization : المفتاح=YOUR_SERVER_KEY
    تأكد من أن هذا هو مفتاح الخادم ، الذي تتوفر قيمته في علامة التبويب Cloud Messaging في جزء إعدادات وحدة تحكم 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 لا يدعم حاليًا امتداد 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 الاتصال وتطلب آلية مصادقة، بما في ذلك طريقة 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>

إف سي إم

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

إف سي إم

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

إف سي إم

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

ملاحظة: لا يستخدم FCM المورد المنضم أثناء توجيه الرسائل.

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