الترحيل من واجهات برمجة التطبيقات FCM القديمة إلى HTTP v1

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

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

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

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

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

قم بتحديث نقطة نهاية الخادم

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

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

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

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

تحديث إذن إرسال الطلبات

بدلاً من سلسلة مفاتيح الخادم المستخدمة في الطلبات القديمة، تتطلب طلبات إرسال HTTP v1 رمز وصول OAuth 2.0. إذا كنت تستخدم Admin 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 Functions (بما في ذلك Cloud Functions for Firebase)، فاستخدم بيانات اعتماد التطبيق الافتراضية (ADC). تستخدم ADC حساب الخدمة الافتراضي الحالي الخاص بك للحصول على بيانات الاعتماد لتخويل الطلبات، وتتيح ADC الاختبار المحلي المرن عبر متغير البيئة GOOGLE_APPLICATION_CREDENTIALS . للحصول على أقصى قدر من الأتمتة لتدفق التفويض، استخدم ADC مع مكتبات خادم Admin 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 من استخدام أي من بيانات الاعتماد المذكورة أعلاه، فسيقوم النظام بإلقاء خطأ.

يوضح مثال كود Admin 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);

بايثون

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

ج#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

تقديم بيانات الاعتماد يدويا

تدعم مشاريع Firebase حسابات خدمة Google، والتي يمكنك استخدامها للاتصال بواجهات برمجة تطبيقات خادم Firebase من خادم التطبيق الخاص بك أو البيئة الموثوقة. إذا كنت تقوم بتطوير التعليمات البرمجية محليًا أو نشر التطبيق الخاص بك محليًا، فيمكنك استخدام بيانات الاعتماد التي تم الحصول عليها عبر حساب الخدمة هذا لتخويل طلبات الخادم.

لمصادقة حساب خدمة وتخويله للوصول إلى خدمات Firebase، يجب عليك إنشاء ملف مفتاح خاص بتنسيق JSON.

لإنشاء ملف مفتاح خاص لحساب الخدمة الخاص بك:

  1. في وحدة تحكم Firebase، افتح الإعدادات > حسابات الخدمة .

  2. انقر فوق "إنشاء مفتاح خاص جديد" ، ثم أكد ذلك بالنقر فوق "إنشاء مفتاح" .

  3. قم بتخزين ملف JSON الذي يحتوي على المفتاح بشكل آمن.

عند التفويض عبر حساب الخدمة، لديك خياران لتوفير بيانات الاعتماد لتطبيقك. يمكنك إما تعيين متغير البيئة GOOGLE_APPLICATION_CREDENTIALS ، أو يمكنك تمرير المسار بشكل صريح إلى مفتاح حساب الخدمة في التعليمات البرمجية. الخيار الأول أكثر أمانًا ويوصى به بشدة.

لتعيين متغير البيئة:

قم بتعيين متغير البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار الملف لملف JSON الذي يحتوي على مفتاح حساب الخدمة الخاص بك. ينطبق هذا المتغير فقط على جلسة الصدفة الحالية الخاصة بك، لذلك إذا قمت بفتح جلسة جديدة، فقم بتعيين المتغير مرة أخرى.

لينكس أو ماك

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

شبابيك

مع باورشيل:

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

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

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

استخدم بيانات اعتماد 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، أو JWT. لمزيد من المعلومات، راجع رموز الويب JSON .

بايثون

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

بايثون

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

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

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

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

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

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

قبل

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

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

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

قبل

// 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 API، قم بتوفير رمز التسجيل الحالي للجهاز في مفتاح 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 API، راجع ما يلي: