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

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

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

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

3. إذا لم يتمكن ADC من استخدام أي من بيانات الاعتماد أعلاه، فسيعرض النظام خطأ.

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

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 لاسترداد رمز الدخول إلى 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);
    });
  });
}
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>:

عقدة.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 من بروتوكول 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 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 API يوفر المرونة لتخصيص الرسائل لكل نظام أساسي.

قبل

// 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 API جميع "REST" تستخدم المقتطفات v1 API ما لم يُذكر خلاف ذلك على وجه التحديد.

• مدونة Firebase