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

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

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

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

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

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

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

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

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

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

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

طلبات 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

ملاحظة: في مسارات نقل البيانات المعتادة، يجب تفعيل واجهة برمجة التطبيقات FCM v1 تلقائيًا. إذا واجهت أخطاء في الاتصال بنقطة النهاية، تحقّق من أنّه تم تفعيل "Firebase Cloud Messaging API" في قائمة واجهات برمجة التطبيقات والخدمات في وحدة تحكّم Google Cloud.

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

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

ملاحظة: كما هو الحال مع واجهات برمجة التطبيقات القديمة، يجب إرسال رسائل HTTP‏ 1.0 من خلال بيئة موثوق بها، مثل خادم تطبيقك أو Cloud Functions لـ Firebase باستخدام بروتوكول HTTP أو حزمة Admin SDK لإنشاء طلبات الرسائل. إنّ الإرسال مباشرةً من منطق تطبيق العميل يشكّل خطرًا شديدًا على الأمان ولا يُسمَح به.

قبل

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

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

تقديم بيانات الاعتماد باستخدام أداة "إدارة الاعتمادات"

تتحقّق بيانات الاعتماد التلقائية لتطبيق Google (ADC) من بيانات اعتمادك بالترتيب التالي:

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

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

3. إذا لم يتمكّن "موفِّر خدمات إدارة البيانات" من استخدام أيّ من بيانات الاعتماد أعلاه، يُرسِل النظام رسالة خطأ.

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

Node.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

جافا

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"

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

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

استخدِم بيانات اعتماد Firebase مع مكتبة Google Auth Library بلغتك المفضّلة لاسترداد رمز وصول صالح لفترة قصيرة من خلال بروتوكول 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

جافا

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

جافا

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

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

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

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

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

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

قبل

{
  "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"
    }
  }
}

مثال: بيانات JSON متداخلة

على عكس واجهة برمجة التطبيقات القديمة للرسائل، لا تتيح واجهة برمجة التطبيقات HTTP v1 استخدام قيم JSON المتداخلة في الحقل data. يجب إجراء تحويل من تنسيق JSON إلى سلسلة.

قبل

{
  ...
  "data": {
    "keysandvalues": {"key1": "value1", "key2": 123}
  }
}

بعد

{
  "message": {
   ...
    "data": {
      "keysandvalues": "{\"key1\": \"value1\", \"key2\": 123}"
    }
  }
}

مثال: استهداف منصات متعددة

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

قبل

// 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!",
      "title": "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 API، يُرجى الاطّلاع على ما يلي:

• إرشادات حول كيفية إنشاء طلبات إرسال خادم التطبيقات باستخدام واجهة برمجة التطبيقات HTTP v1 تستخدم جميع المقتطفات من أسلوب "REST" واجهة برمجة التطبيقات v1 ما لم يُذكر خلاف ذلك.

• مدوّنة Firebase