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

على التطبيقات التي تستخدم واجهات برمجة التطبيقات القديمة للمراسلة عبر السحابة الإلكترونية من Firebase لكل من HTTP وXMPP الانتقال إلى واجهة برمجة التطبيقات HTTP v1 في أقرب وقت ممكن. في 20 حزيران (يونيو) 2023، تم نهائيًا إيقاف إرسال الرسائل (بما في ذلك الرسائل قبل إرسال الرسائل) باستخدام واجهات برمجة التطبيقات هذه، وستتم إزالته في 21 حزيران (يونيو) 2024.

يمكنك الاطّلاع على مزيد من المعلومات عن الميزات المتأثرة المحدّدة.

بالإضافة إلى الدعم المستمر والميزات الجديدة، تتميز واجهة برمجة التطبيقات HTTP v1 هذه بالمزايا التي تفوق واجهات برمجة التطبيقات القديمة:

  • أمان أفضل عبر رموز الدخول تستخدم واجهة برمجة التطبيقات HTTP v1 رموز دخول قصيرة الأجل وفقًا لنموذج أمان OAuth2. في حال أصبح رمز الدخول عامًا، يمكن استخدامه بشكل ضار لمدة ساعة تقريبًا قبل انتهاء صلاحيته. لا يتم إرسال رموز إعادة التحميل بالمعدّل نفسه الذي يتم به نقل مفاتيح الأمان المستخدمة في واجهة برمجة التطبيقات القديمة، وبالتالي يقل احتمال الحصول عليها.

  • تخصيص أكثر فاعلية للرسائل على المنصّات: بالنسبة إلى نص الرسالة، تحتوي واجهة برمجة التطبيقات HTTP v1 على مفاتيح شائعة تصل إلى جميع المثيلات المستهدَفة، بالإضافة إلى مفاتيح خاصة بالنظام الأساسي تتيح لك تخصيص الرسالة على جميع المنصّات. ويتيح لك هذا الإجراء إنشاء "عمليات إلغاء" تؤدي إلى إرسال حمولات مختلفة قليلاً إلى الأنظمة الأساسية المختلفة للعميل في رسالة واحدة.

  • المزيد من القابلية للتمديد والمواكبة في المستقبل لإصدارات الأنظمة الأساسية للعملاء الجدد: توفّر واجهة برمجة التطبيقات HTTP v1 دعمًا كاملاً لخيارات المراسلة المتوفرة على أنظمة Apple الأساسية وAndroid والويب. بما أنّ لكل نظام أساسي كتلة محدّدة خاصة بها في حمولة JSON، يمكن للمراسلة عبر السحابة الإلكترونية من Firebase توسيع نطاق واجهة برمجة التطبيقات لتشمل الإصدارات الجديدة والأنظمة الأساسية الجديدة حسب الحاجة.

تعديل نقطة نهاية الخادم

يختلف عنوان URL لنقطة النهاية لواجهة برمجة التطبيقات HTTP v1 عن نقطة النهاية القديمة في الطرق التالية:

  • يتضمّن هذا الإصدار إصدارًا، مع توفُّر /v1 في مساره.
  • يحتوي المسار على رقم تعريف مشروع Firebase لتطبيقك، بالتنسيق /projects/myproject-ID/. يتوفّر هذا المعرّف في علامة تبويب الإعدادات العامة للمشروع في وحدة تحكُّم Firebase.
  • يتم تحديد طريقة send صراحةً على أنّها :send.

لتحديث نقطة نهاية الخادم للإصدار 1 من بروتوكول HTTP، أضِف هذه العناصر إلى نقطة النهاية في عنوان طلبات الإرسال.

طلبات HTTP السابقة

POST https://fcm.googleapis.com/fcm/send

طلبات XMPP قبل

يتم إرسال رسائل XMPP القديمة عبر الاتصال بنقطة النهاية التالية:

fcm-xmpp.googleapis.com:5235

بعد

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

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

وبدلاً من سلسلة مفتاح الخادم المستخدمة في الطلبات القديمة، تتطلب طلبات إرسال الإصدار 1 من HTTP رمز دخول OAuth 2.0. إذا كنت تستخدم SDK للمشرف لإرسال الرسائل، ستتولى المكتبة معالجة الرمز المميز نيابةً عنك. إذا كنت تستخدم بروتوكولاً غير رسمي، احصل على الرمز المميّز كما هو موضّح في هذا القسم وأضِفه إلى العنوان كـ Authorization: Bearer <valid Oauth 2.0 token>.

قبل

Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA

بعد

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

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

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

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

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

Go

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، يجب إنشاء ملف مفتاح خاص بتنسيق 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"

شبابيك

باستخدام PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

بعد إكمال الخطوات الواردة أعلاه، ستتمكن "بيانات اعتماد التطبيق التلقائية" (ADC) من تحديد بيانات الاعتماد ضمنيًا، ما يسمح لك باستخدام بيانات اعتماد حساب الخدمة عند الاختبار أو التشغيل في بيئات غير تابعة لشركة Google.

استخدام بيانات الاعتماد لاستخراج رموز الدخول

استخدِم بيانات اعتماد Firebase مع مكتبة مصادقة Google للغتك المفضّلة لاسترداد رمز دخول OAuth 2.0 قصير الأجل:

عقدة.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();
}

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

للسماح بالوصول إلى "المراسلة عبر السحابة الإلكترونية من Firebase"، اطلب النطاق https://www.googleapis.com/auth/firebase.messaging.

لإضافة رمز الدخول إلى عنوان طلب HTTP:

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

عقدة.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;

تعديل حمولة طلبات الإرسال

يقدّم الإصدار 1 من بروتوكول FCM HTTP تغييرًا كبيرًا في بنية حمولة رسالة JSON. تضمن هذه التغييرات في المقام الأول معالجة الرسائل بشكل صحيح عند تلقّيها على الأنظمة الأساسية المختلفة للعملاء. بالإضافة إلى ذلك، تمنحك التغييرات مرونة إضافية في تخصيص أو "تجاهل" حقول الرسائل لكل نظام أساسي.

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

مثال: رسالة إشعار بسيطة

في ما يلي مقارنة بين حمولة إشعارات بسيطة جدًا تحتوي على حقول title وbody وdata فقط، مع توضيح الاختلافات الأساسية في حمولات البيانات القديمة والإصدار 1 من HTTP.

قبل

{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available."
  },
  "data": {
    "story_id": "story_12345"
  }
}

بعد

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    }
  }
}

مثال: استهداف أنظمة أساسية متعددة

لتفعيل ميزة استهداف أنظمة أساسية متعدّدة، نفّذت واجهة برمجة التطبيقات القديمة عمليات إلغاء في الخلفية. على النقيض من ذلك، يوفّر الإصدار 1 من HTTP مجموعات مفاتيح خاصة بالنظام الأساسي تجعل أي اختلافات بين الأنظمة الأساسية واضحة ومرئية للمطوّر. يسمح لك ذلك باستهداف منصات متعددة دائمًا من خلال طلب واحد، كما هو موضّح في النموذج التالي.

قبل

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

بعد

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

مثال: التخصيص مع إلغاءات النظام الأساسي

بالإضافة إلى تبسيط استهداف الرسائل عبر الأنظمة الأساسية، توفّر واجهة برمجة التطبيقات HTTP v1 مرونة في تخصيص الرسائل لكل نظام أساسي.

قبل

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "Check out the Top Story.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

بعد

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY",
        "body": "Check out the Top Story"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

مثال: استهداف أجهزة معيّنة

لاستهداف أجهزة محدّدة باستخدام واجهة برمجة التطبيقات HTTP v1، عليك تقديم الرمز المميّز الحالي للتسجيل في مفتاح token بدلاً من المفتاح to.

قبل

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

بعد

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

لمزيد من النماذج والمعلومات حول واجهة برمجة تطبيقات FCM HTTP v1، يُرجى الاطّلاع على ما يلي: