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

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

  • اسم الموضوع
  • الشرط
  • الرمز المميّز لتسجيل الجهاز
  • اسم مجموعة الأجهزة (البروتوكول فقط)

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

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

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

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

إذا كان تطبيقك يعمل على Compute Engine أو Google Kubernetes Engine أو App Engine أو Cloud Functions (بما في ذلك Cloud Functions for Firebase)، استخدِم بيانات الاعتماد التلقائية للتطبيق (ADC). تستخدم ميزة "بيئة التطبيقات التلقائية" حساب الخدمة التلقائي الحالي للحصول على بيانات الاعتماد اللازمة لتفويض الطلبات، كما تتيح إجراء اختبارات محلية مرنة من خلال متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS. لتحقيق أقصى قدر من التشغيل الآلي في تدفّق منح الإذن، استخدِم ADC مع مكتبات خادم مدير 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 استخدام أيّ من بيانات الاعتماد المذكورة أعلاه، سيُظهر النظام رسالة خطأ.

يوضّح مثال الرمز التالي لحزمة 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 الذي يحتوي على مفتاح حساب الخدمة. لا ينطبق هذا المتغيّر إلا على جلسة 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.

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

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

في هذا المثال، تصادق مكتبة برامج &quot;واجهة Google API&quot; على الطلب باستخدام رمز مميّز على الويب بتنسيق 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 Cloud Messaging API. تحقَّق من تفعيلها في وحدة تحكّم Firebase من خلال الانتقال إلى الإعدادات > الإعدادات العامة. بعد ذلك، انقر على علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية.

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

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

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

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

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

      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

عند النجاح، يكون ردّ HTTP v1 API عبارة عن عنصر 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://cat.10515.net/1.jpg"
    }
  }
}

الجري

انقر على تنفيذ لتجربة العيّنة في API Explorer.