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

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

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

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

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

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

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

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

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

توفير بيانات الاعتماد باستخدام بيانات الاعتماد التلقائية للتطبيق

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

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

  2. إذا لم يتم ضبط متغيّر البيئة، تستخدِم بيانات الاعتماد التلقائية للتطبيق حساب الخدمة التلقائي الذي يوفّره Compute Engine وGoogle Kubernetes Engine وApp Engine و وCloud Functions للتطبيقات التي تعمل على هذه الخدمات.

  3. إذا تعذّر على بيانات الاعتماد التلقائية للتطبيق استخدام أيّ من بيانات الاعتماد أعلاه، يعرض النظام خطأً.

يوضّح مثال الرمز البرمجي التالي لحزمة تطوير البرامج (SDK) للمشرف هذه الاستراتيجية. لا يحدّد المثال بيانات اعتماد التطبيق بشكلٍ صريح. ومع ذلك، يمكن لبيانات الاعتماد التلقائية للتطبيق العثور على بيانات الاعتماد ضمنيًا طالما تم ضبط متغيّر البيئة، أو طالما كان التطبيق يعمل على 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)
}
init.go

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

بعد إكمال الخطوات أعلاه، ستتمكّن بيانات الاعتماد التلقائية للتطبيق من تحديد بيانات اعتمادك ضمنيًا، ما يتيح لك استخدام بيانات اعتماد حساب الخدمة عند الاختبار أو التشغيل في بيئات غير تابعة لـ 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);
    });
  });
}
index.js

في هذا المثال، تصادق مكتبة عميل Google API الطلب باستخدام JSON Web Token أو JWT. لمزيد من المعلومات، اطّلِع على JSON Web Tokens.

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
messaging.py

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

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

للسماح بالوصول إلى FCM، اطلب النطاق https://www.googleapis.com/auth/firebase.messaging.

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

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

node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}
index.js

Python

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

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;
FirebaseMessagingSnippets.java

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

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

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

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

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

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

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

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

      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 عبارة عن عنصر JSON يحتوي على رقم تعريف الرسالة:

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

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

يوضّح هذا القسم كيفية إرسال رسالة إشعار اختبارية باستخدام الإصدار الأول من واجهة برمجة تطبيقات 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"
    }
  }
}

الجري

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