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

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

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

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

السماح بطلبات الإرسال في الإصدار 1 من 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، عليك إنشاء ملف مفتاح خاص بتنسيق 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"

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

في هذا المثال، تصادق مكتبة عميل 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
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 السحابية" في مشروع المُرسِل.
  2. أنشئ حساب خدمة في الـ مشروع المُرسِل.
  3. في المشروع المستهدَف، امنح عنوان البريد الإلكتروني لحساب الخدمة دور مشرف واجهة برمجة تطبيقات مراسلة Firebase السحابية في صفحة "إدارة الهوية وإمكانية الوصول". يسمح ذلك لحساب الخدمة من المشروع الآخر بإرسال رسائل إلى المشروع المستهدَف.
  4. أنشئ رمز دخول OAuth 2.0 لحساب الخدمة في مشروع المُرسِل. يمكنك إجراء ذلك بأحد الطريقتَين التاليتَين:
    • تنزيل ملف JSON لمفتاح حساب الخدمة واستخدامه
    • بدلاً من ذلك، استخدِم ميزة هوية عبء العمل إذا كانت خدمتك تعمل على Google Cloud.
  5. استخدِم رمز الوصول الذي تم الحصول عليه في عنوان Authorization لطلب الإرسال. يجب إرسال الطلب إلى نقطة نهاية الإصدار 1 من 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

في حال النجاح، تكون استجابة الإصدار 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://cat.10515.net/1.jpg"
    }
  }
}

الجري

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