تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

يتم تحديد إصدارها من خلال /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

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

بدلاً من سلسلة مفتاح الخادم المستخدَمة في الطلبات القديمة، تتطلّب طلبات الإرسال في الإصدار 1 من بروتوكول HTTP رمز دخول 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:

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

إذا كان تطبيقك يعمل على 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) من بيانات الاعتماد الخاصة بك بالترتيب التالي:

يتحقّق ADC مما إذا تم ضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS. إذا تم ضبط المتغيّر، ستستخدِم ADC ملف حساب الخدمة الذي يشير إليه المتغيّر.
إذا لم يتم ضبط متغيّر البيئة، تستخدم ADC حساب الخدمة التلقائي الذي توفّره Compute Engine وGoogle Kubernetes Engine وApp Engine وCloud Functions للتطبيقات التي تعمل على هذه الخدمات.
إذا تعذّر على 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)
}init.go

#C

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

توفير بيانات الاعتماد يدويًا

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

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

لإنشاء ملف مفتاح خاص لحساب الخدمة، اتّبِع الخطوات التالية:

في وحدة تحكّم Firebase، افتح الإعدادات > حسابات الخدمة.
انقر على إنشاء مفتاح خاص جديد، ثم أكِّد ذلك بالنقر على إنشاء مفتاح.
تخزين ملف 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 للغتك المفضّلة من أجل استرداد رمز وصول قصير الأمد عبر بروتوكول 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.tokenmessaging.py

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

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;FirebaseMessagingSnippets.java

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

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

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

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

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

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

لتفعيل استهداف أنظمة أساسية متعددة، كانت واجهة برمجة التطبيقات القديمة تجري عمليات إلغاء في الخلفية. في المقابل، يوفّر الإصدار 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 الإصدار 1 المرونة لتخصيص الرسائل لكل منصة.

قبل

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

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

لاستهداف أجهزة معيّنة باستخدام الإصدار 1 من واجهة برمجة التطبيقات HTTP، قدِّم الرمز المميّز الحالي للتسجيل الخاص بالجهاز في المفتاح 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 الإصدار 1، يُرجى الاطّلاع على ما يلي:

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