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

يجب نقل التطبيقات التي تستخدم واجهتَي برمجة تطبيقات المراسلة عبر السحابة الإلكترونية من Firebase القديمة المتوقّفة نهائيًا للبروتوكولَين HTTP وXMPP إلى واجهة برمجة التطبيقات HTTP v1 في أقرب وقت ممكن. تم إيقاف ميزة إرسال الرسائل (بما في ذلك الرسائل الرئيسية) باستخدام واجهات برمجة التطبيقات هذه نهائيًا في 20 حزيران (يونيو) 2023 وستبدأ عملية الإيقاف في 22 تموز (يوليو) 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

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

بدلاً من سلسلة مفتاح الخادم المستخدمة في الطلبات القديمة، تتطلب طلبات الإرسال HTTP v1 رمز الدخول OAuth 2.0. إذا كنت تستخدم SDK للمشرف لإرسال الرسائل، ستتعامل المكتبة مع الرمز المميز لك. إذا كنت تستخدم بروتوكول Raw، يمكنك الحصول على الرمز المميّز كما هو موضّح في هذا القسم وإضافته إلى العنوان باسم 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 (بما في ذلك وظائف السحابة الإلكترونية لبرنامج 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 Functions للتطبيقات التي تعمل على تلك الخدمات.

  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 من بروتوكول HTTP في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" تغييرًا كبيرًا في بنية حمولة رسائل JSON. بشكل أساسي، تضمن هذه التغييرات معالجة الرسائل بشكل صحيح عند استلامها على منصات عملاء مختلفة. وبالإضافة إلى ذلك، تمنحك التغييرات مرونة إضافية لتخصيص حقول الرسائل أو "إلغاءها" لكل نظام أساسي.

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

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

في ما يلي مقارنة لحمولة إشعارات بسيطة جدًا تحتوي على الحقول title وbody وdata فقط، مع توضيح الاختلافات الأساسية في حمولات البيانات الأساسية القديمة والإصدار الأول من 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"
    }
  }
}

مثال: بيانات 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!",
      "time": "FCM Message"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }

بعد

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

لمزيد من النماذج والمعلومات حول واجهة برمجة التطبيقات للإصدار 1 من خدمة FCM HTTP، يمكنك الاطّلاع على ما يلي: