إرسال رسالة باستخدام الإصدار 1 من واجهة برمجة تطبيقات HTTP لمراسلة Firebase السحابية

باستخدام الإصدار 1 من واجهة برمجة تطبيقات HTTP لمراسلة FCM السحابية، يمكنك إنشاء طلبات الرسائل وإرسالها إلى هذه الأنواع من الأهداف:

  • اسم الموضوع
  • الشرط
  • الرمز المميّز لتسجيل الجهاز
  • اسم مجموعة الأجهزة (متوقّفة نهائيًا، ستتم إزالتها في 29 سبتمبر 2027)

يمكنك إرسال رسائل تتضمّن حمولة إشعار تتألف من حقول محدّدة مسبقًا، أو حمولة بيانات تتضمّن حقولاً يحدّدها المستخدم، أو رسالة تتضمّن كلا النوعَين من الحمولة. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع الرسائل.

تفويض طلبات الإرسال في الإصدار 1 من HTTP

استنادًا إلى تفاصيل بيئة الخادم، يمكنك استخدام مجموعة من هذه الاستراتيجيات لمنح الإذن لطلبات الخادم إلى خدمات 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 مع مكتبات خادم مدير SDK.

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

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

تتحقّق بيانات الاعتماد التلقائية لتطبيق Google من بيانات الاعتماد الخاصة بك بالترتيب التالي:

  1. تتحقّق ADC مما إذا تم ضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS. إذا تم ضبط المتغيّر، تستخدم "بيانات الاعتماد التلقائية للتطبيق" ملف حساب الخدمة الذي يشير إليه المتغيّر.

  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(),
});

Java

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

#C

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

تقديم بيانات الاعتماد يدويًا

تتيح مشاريع Firebase استخدام حسابات خدمة Google، والتي يمكنك استخدامها لاستدعاء واجهات برمجة تطبيقات خادم Firebase من خادم التطبيق أو البيئة الموثوقة. إذا كنت تطوّر رمزًا برمجيًا محليًا أو تنشر تطبيقك في المؤسسة، يمكنك استخدام بيانات الاعتماد التي تم الحصول عليها باستخدام حساب الخدمة هذا لمنح الإذن لطلبات الخادم.

يمكنك الاطّلاع على جميع حسابات الخدمة لمشروعك على 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.

استخدام بيانات الاعتماد لإنشاء رموز الدخول

إذا لم تكن تستخدم Firebase 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);
    });
  });
}

في هذا المثال، تصادق مكتبة عملاء 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

Java

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();
}

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

لتفويض الوصول إلى FCM، اطلب النطاق https://www.googleapis.com/auth/firebase.messaging.

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

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

node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}

Python

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}

Java

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;

تفويض حساب خدمة من مشروع مختلف

يمكنك إرسال رسائل لمشروع واحد، وهو "المشروع المستهدَف"، أثناء استخدام رمز OAuth 2.0 المميز الذي تم إنشاؤه من حساب خدمة في مشروع مختلف ، وهو "مشروع المُرسِل". يتيح لك ذلك مركزية إدارة حسابات الخدمة في مشروع واحد أثناء إرسال الرسائل نيابةً عن الآخرين. لمعرفة كيفية القيام بذلك، استخدم الخطوات التالية:

  1. في مشروع المُرسِل، تأكَّد من تفعيل واجهة برمجة التطبيقات لمراسلة Firebase السحابية. تحقَّق من تفعيلها في وحدة تحكّم "Firebase" من خلال الانتقال إلى الإعدادات > الإعدادات العامة. بعد ذلك، انقر على علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية.

  2. في مشروع المُرسِل، أنشئ حساب خدمة.

  3. في المشروع المستهدَف، عليك منح دور مشرف واجهة برمجة التطبيقات لمراسلة Firebase السحابية لعنوان البريد الإلكتروني الخاص بحساب الخدمة. يمكنك إجراء ذلك في صفحة إدارة الهوية وإمكانية الوصول والمشرف > إدارة الهوية وإمكانية الوصول في وحدة تحكّم Google Cloud. يسمح هذا الدور لحساب الخدمة من مشروع المُرسِل بإرسال الرسائل إلى المشروع المستهدَف.

  4. أنشئ رمز دخول OAuth 2.0 لحساب الخدمة في مشروع المُرسِل. يمكنك إجراء ذلك باستخدام أحد الخيارات التالية:

    • تنزيل ملف JSON لمفتاح حساب الخدمة واستخدامه
    • استخدام Workload Identity إذا كانت الخدمة تعمل على Google Cloud

  5. استخدِم رمز الدخول الذي حصلت عليه في عنوان Authorization لطلب الإرسال. يجب إرسال الطلب إلى نقطة نهاية HTTP v1 للمشروع المستهدَف:

      POST https://fcm.googleapis.com/v1/TARGET_PROJECT_ID/messages:send

إرسال رسائل إلى أجهزة محدّدة

لإرسال رسالة إلى جهاز واحد محدّد، عليك تمرير الرمز المميّز لتسجيل الجهاز كما هو موضّح.

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

أمر cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "notification":{
     "title":"FCM Message",
     "body":"This is an FCM Message"
   },
   "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

في حال نجاح الطلب، يكون الردّ من الإصدار 1 من واجهة برمجة التطبيقات HTTP عبارة عن عنصر JSON يحتوي على معرّف الرسالة:

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

إرسال رسالة إشعار تجريبية باستخدام الإصدار 1 من واجهة برمجة تطبيقات HTTP لمراسلة Firebase السحابية

يوضّح هذا القسم كيفية إرسال رسالة إشعار تجريبية باستخدام الإصدار 1 من واجهة برمجة تطبيقات HTTP لمراسلة Firebase السحابية.

عنوان URL لطلب HTTP

يتكوّن الطلب من HTTP POST إلى الهدف المحدّد (رمز تسجيل مميّز أو موضوع أو شرط) على عنوان URL التالي:

POST https://fcm.googleapis.com/v1/projectId/messages:send

نموذج JSON لطلب HTTP كامل

في ما يلي مثال كامل يوضّح كيفية نشر إشعار ضمن طلب HTTP POST:

{
  "message": {
    "token": REGISTRATION_TOKEN,
    "notification": {
      "title": "FCM API test",
      "body": "This is the body of the notification.",
      "image": "https://firebase.google.com/static/images/products/cloud-messaging/cloud-messaging-hero_1x.png"
    }
  }
}

الجري

انقر على تشغيل لتجربة النموذج في مستكشف واجهة برمجة التطبيقات.