بروتوكول HTTP لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase"

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

يوفر هذا المستند مرجعًا لبنية HTTP المستخدمة لتمرير الرسائل من خادم تطبيقك إلى تطبيقات العميل من خلال "المراسلة عبر السحابة الإلكترونية من Firebase".

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

عند استخدام بروتوكول HTTP القديم، يجب أن يوجّه خادم التطبيق جميع طلبات HTTP إلى نقطة النهاية هذه:

https://fcm.googleapis.com/fcm/send

تندرج المعلمات والخيارات المتاحة ضمن الفئات الواسعة التالية:

• بنية الرسائل بعد البث
• رموز الاستجابة للأخطاء في رسائل أثناء البث

بنية الرسالة بعد استلامها

يوفّر هذا القسم بنية إرسال الرسائل النهائية وتفسير استجابات HTTP من خدمة "المراسلة عبر السحابة الإلكترونية من Firebase".

رسائل HTTP المتسلسلة بتنسيق JSON

يسرد الجدول التالي الأهداف والخيارات وحمولة رسائل HTTP JSON.

الجدول 1. الأهداف والخيارات وحمولة رسائل HTTP النهائية (JSON).

المَعلمة	الاستخدام	الوصف
الأهداف
to	اختياري، سلسلة	تحدّد هذه المعلمة مُستلِم الرسالة. يمكن أن تكون القيمة رمزًا مميّزًا لتسجيل جهاز أو مفتاح إشعارات لمجموعة أجهزة أو موضوعًا واحدًا (مسبقًا بـ /topics/). لإرسالها إلى مواضيع متعددة، استخدِم المَعلمة condition.
registration_ids	اختياري، مصفوفة من السلاسل	تحدد هذه المعلمة مستلم رسالة البث المتعدد، وهي رسالة يتم إرسالها إلى أكثر من رمز مميَّز للتسجيل. يجب أن تكون القيمة مصفوفة من الرموز المميّزة للتسجيل المطلوب إرسال رسالة البث المتعدد إليها. يجب أن تحتوي المصفوفة على رمز مميز واحد على الأقل و1,000 رمز تسجيل على الأكثر. لإرسال رسالة إلى جهاز واحد، استخدِم المَعلمة to. لا يُسمح برسائل البث المتعدد إلا باستخدام تنسيق HTTP JSON.
condition	اختياري، سلسلة	تحدّد هذه المعلمة تعبيرًا منطقيًا للشروط التي تحدد هدف الرسالة. الشرط المتوافق: موضوع، تم تنسيقه كـ "'yourTopic' في المواضيع". وهذه القيمة غير حساسة لحالة الأحرف. عوامل التشغيل المتوافقة: && و|| يُسمح بعاملَي تشغيل كحدّ أقصى لكل رسالة موضوع.
notification_key متوقّفة نهائيًا	اختياري، سلسلة	تم إيقاف هذه المعلمة نهائيًا. بدلاً من ذلك، يمكنك استخدام to لتحديد مستلمي الرسالة. لمزيد من المعلومات حول كيفية إرسال رسائل إلى أجهزة متعددة، راجِع المستندات الخاصة بالنظام الأساسي الذي تستخدمه.
الخيارات
collapse_key	اختياري، سلسلة	تحدد هذه المعلمة مجموعة من الرسائل (مثلاً، مع collapse_key: "Updates Available") يمكن تصغيرها، بحيث يتم إرسال الرسالة الأخيرة فقط عند استئناف التسليم. ويهدف ذلك إلى تجنُّب إرسال عدد كبير جدًا من الرسائل نفسها عندما يتصل الجهاز بالإنترنت مرة أخرى أو عندما يصبح نشطًا. يُرجى العِلم أنّه ليس هناك ما يضمن ترتيب إرسال الرسائل. ملاحظة: يُسمح باستخدام 4 مفاتيح تصغير مختلفة كحد أقصى في أي وقت. ويعني هذا أنّه يمكن لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" تخزين 4 رسائل مختلفة في الوقت نفسه لكل تطبيق عميل. وفي حال تجاوز هذا العدد، ليس هناك ما يضمن الاحتفاظ بـ 4 مفاتيح مصغّرة للتصغير.
priority	اختياري، سلسلة	لضبط أولوية الرسالة. القيمتان الصالحتان هما "عادي" و "مرتفع". على منصات Apple، تتوافق هذه مع الأولويات 5 و10 لأسماء نقاط الوصول. بشكل افتراضي، يتم إرسال رسائل الإشعارات ذات أولوية عالية، ويتم إرسال رسائل البيانات بأولوية عادية. تعمل الأولوية العادية على تحسين استهلاك بطارية تطبيق العميل ويجب استخدامها ما لم يكن التسليم الفوري مطلوبًا. بالنسبة إلى الرسائل ذات الأولوية العادية، قد يتلقّى التطبيق الرسالة بتأخير غير محدّد. عند إرسال رسالة ذات أولوية عالية، يتم إرسالها على الفور، ويمكن للتطبيق عرض إشعار.
content_available	اختياري، منطقية	على منصات Apple، استخدِم هذا الحقل لتمثيل content-available في حمولة أسماء نقاط الوصول (APN). عند إرسال إشعار أو رسالة وضبطهما على true، يتم تنشيط تطبيق عميل غير نشط، ويتم إرسال الرسالة من خلال أسماء نقاط الوصول (APN) كإشعار صامت وليس من خلال خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". يُرجى العِلم أنّه لا يمكن ضمان تلقّي الإشعارات الصامتة في أسماء نقاط الوصول (APN)، ويمكن أن تعتمد على عدة عوامل، مثل تفعيل المستخدم لوضع الطاقة المنخفضة أو فرض إنهاء التطبيق وما إلى ذلك. وعلى نظام التشغيل Android، تعمل رسائل البيانات على تنشيط التطبيق تلقائيًا. على Chrome، هذه الميزة غير متاحة حاليًا.
mutable_content	اختياري، قيمة JSON منطقية	على منصات Apple، استخدِم هذا الحقل لتمثيل mutable-content في حمولة أسماء نقاط الوصول (APN). عند إرسال إشعار وضبطه على true، يمكن تعديل محتوى الإشعار قبل عرضه، وذلك باستخدام إضافة تطبيق "خدمة الإشعارات". وسيتم تجاهل هذه المَعلمة لنظام التشغيل Android وعلى الويب.
time_to_live	اختياري، رقم	تحدد هذه المعلمة المدة (بالثواني) التي يجب الاحتفاظ بالرسالة في مساحة تخزين FCM إذا كان الجهاز غير متصل بالإنترنت. الحد الأقصى لوقت توفّر الدعم هو 4 أسابيع، والقيمة التلقائية هي 4 أسابيع. لمزيد من المعلومات، يُرجى الاطّلاع على ضبط عمر الرسالة.
restricted_package_ name (نظام التشغيل Android فقط)	اختياري، سلسلة	تحدّد هذه المعلمة اسم حزمة التطبيق التي يجب أن تتطابق الرموز المميزة للتسجيل فيها لاستلام الرسالة.
dry_run	اختياري، منطقية	وعند ضبط هذه المَعلمة على true، تتيح للمطوّرين اختبار الطلب بدون إرسال رسالة محدّدة. ستكون القيمة التلقائية false.
الحمولة
data	عنصر اختياري	تحدد هذه المعلمة أزواج المفتاح/القيمة المخصصة لحمولة الرسالة. مثلاً، باستخدام "data:{"score":"3x1"}:" على أنظمة Apple الأساسية، إذا تم إرسال الرسالة عبر أسماء نقاط الوصول (APN)، فإنّها تمثِّل حقول البيانات المخصّصة. وإذا تم إرسالها عبر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، سيتم تمثيلها كقاموس قيمة رئيسية في AppDelegate application:didReceiveRemoteNotification:. على Android، سيؤدي ذلك إلى إضافة intent إضافية باسم score مع قيمة السلسلة 3x1. يجب ألا يكون المفتاح كلمة محجوزة ("from" أو "message_type" أو أي كلمة تبدأ بـ "google" أو "gcm"). لا تستخدِم أيًا من الكلمات المحدّدة في هذا الجدول (مثل collapse_key). ويُنصَح باستخدام القيم في أنواع السلاسل. وعليك تحويل القيم في العناصر أو أنواع البيانات الأخرى التي ليست سلسلة (مثل الأعداد الصحيحة أو القيم المنطقية) إلى سلسلة.
notification	عنصر اختياري	تحدّد هذه المَعلمة أزواج المفتاح/القيمة المحدّدة مسبقًا والمرئية للمستخدم لحمولة الإشعارات. يمكنك الاطّلاع على إمكانية استخدام حمولة الإشعارات لمعرفة التفاصيل. لمزيد من المعلومات حول خيارات رسائل الإشعار ورسائل البيانات، يمكنك الاطّلاع على أنواع الرسائل. في حال تقديم حمولة الإشعارات أو ضبط الخيار content_available على true لإرسال رسالة إلى جهاز Apple، يتم إرسال الرسالة من خلال أسماء نقاط الوصول (APN)، وإلا يتم إرسالها من خلال خدمة "المراسلة عبر السحابة الإلكترونية من Firebase".

إتاحة حمولة الإشعارات

وتسرد الجداول التالية المفاتيح المحدَّدة مسبقًا والمتاحة لإنشاء رسائل إشعارات لنظامَي التشغيل iOS وAndroid.

الجدول 2 أ. نظام التشغيل iOS - مفاتيح رسائل الإشعارات

المَعلمة	الاستخدام	الوصف
title	اختياري، سلسلة	عنوان الإشعار. لا يظهر هذا الحقل على الهواتف والأجهزة اللوحية.
body	اختياري، سلسلة	النص الأساسي للإشعار.
sound	اختياري، سلسلة	الصوت الذي سيتم تشغيله عندما يتلقّى الجهاز الإشعار. سلسلة تحدّد الملفات الصوتية في الحزمة الرئيسية للتطبيق العميل أو في مجلد Library/Sounds لحاوية بيانات التطبيق راجِع مكتبة مطوّري برامج iOS للحصول على مزيد من المعلومات.
badge	اختياري، سلسلة	قيمة الشارة التي تظهر على رمز تطبيق الشاشة الرئيسية. وفي حال عدم تحديد هذه السمة، لن تتغيّر الشارة. وإذا تم ضبط قيمة الشارة على 0، ستتم إزالة الشارة.
click_action	اختياري، سلسلة	يشير ذلك المصطلح إلى الإجراء المرتبط بالمستخدم الذي ينقر على الإشعار. يتطابق مع القيمة category في حمولة أسماء نقاط الوصول (APN).
subtitle	اختياري، سلسلة	العنوان الفرعي للإشعار.
body_loc_key	اختياري، سلسلة	تمثّل هذه السمة مفتاح السلسلة الأساسية في موارد سلسلة التطبيق لاستخدامها في أقلمة النص الأساسي بما يناسب الأقلمة الحالية للمستخدم. يتطابق مع القيمة loc-key في حمولة أسماء نقاط الوصول (APN). يمكنك الاطّلاع على مرجع مفتاح حمولة البيانات و ترجمة محتوى الإشعارات عن بُعد للحصول على مزيد من المعلومات.
body_loc_args	اختياري، مصفوفة JSON كسلسلة	قيم سلسلة متغيرة لاستخدامها بدلاً من محددات التنسيق في body_loc_key بغرض ترجمة النص الأساسي بما يناسب الأقلمة الحالية للمستخدم يتطابق مع القيمة loc-args في حمولة أسماء نقاط الوصول (APN). يمكنك الاطّلاع على مرجع مفتاح حمولة البيانات و ترجمة محتوى الإشعارات عن بُعد للحصول على مزيد من المعلومات.
title_loc_key	اختياري، سلسلة	تمثّل هذه السمة مفتاح سلسلة العنوان في موارد سلسلة التطبيق المطلوب استخدامها لترجمة نص العنوان حسب الترجمة الحالية للمستخدم. يتطابق مع القيمة title-loc-key في حمولة أسماء نقاط الوصول (APN). يمكنك الاطّلاع على مرجع مفتاح حمولة البيانات و ترجمة محتوى الإشعارات عن بُعد للحصول على مزيد من المعلومات.
title_loc_args	اختياري، مصفوفة JSON كسلسلة	قيم سلسلة المتغيّرات التي سيتم استخدامها بدلاً من محدّدات التنسيقات في title_loc_key من أجل استخدام هذه القيم لأقلمة نص العنوان بما يناسب الأقلمة الحالية لدى المستخدم يتطابق مع القيمة title-loc-args في حمولة أسماء نقاط الوصول (APN). يمكنك الاطّلاع على مرجع مفتاح حمولة البيانات و ترجمة محتوى الإشعارات عن بُعد للحصول على مزيد من المعلومات.

الجدول 2 (ب). Android: مفاتيح تلقّي الإشعارات

المَعلمة	الاستخدام	الوصف
title	اختياري، سلسلة	عنوان الإشعار.
body	اختياري، سلسلة	النص الأساسي للإشعار.
android_channel_id	اختياري، سلسلة	معرّف القناة للإشعار (جديد في Android O). يجب أن ينشئ التطبيق قناة باستخدام معرّف القناة هذا قبل أن نتلقّى أي إشعار يتضمّن معرّف القناة هذا. إذا لم ترسل معرّف القناة هذا في الطلب، أو إذا لم ينشئ التطبيق معرّف القناة الذي قدّمته بعد، ستستخدم خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" معرّف القناة المحدّد في بيان التطبيق.
icon	اختياري، سلسلة	رمز الإشعار. يتم ضبط رمز الإشعار على myicon للمورد القابل للرسم myicon. إذا لم ترسِل هذا المفتاح في الطلب، ستعرض خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" رمز مشغّل التطبيقات المحدّد في بيان التطبيق.
sound	اختياري، سلسلة	الصوت الذي سيتم تشغيله عندما يتلقّى الجهاز الإشعار. تتيح هذه السمة استخدام "default" أو اسم ملف مورد صوتي مجمّع في التطبيق. يجب أن تتوفّر الملفات الصوتية في /res/raw/.
tag	اختياري، سلسلة	المعرّف المستخدم لاستبدال الإشعارات الحالية في درج الإشعارات. في حال عدم تحديد قيمة، سينشئ كل طلب إشعارًا جديدًا. في حال تحديد هذا الحقل وظهور إشعار بالعلامة نفسها، سيحلّ الإشعار الجديد محلّ الإشعار الحالي في درج الإشعارات.
color	اختياري، سلسلة	لون رمز الإشعار، والذي يتم التعبير عنه بالتنسيق #rrggbb.
click_action	اختياري، سلسلة	يشير ذلك المصطلح إلى الإجراء المرتبط بالمستخدم الذي ينقر على الإشعار. وفي حال تحديد هذا الخيار، يتم تشغيل نشاط بفلتر أهداف مطابق عندما ينقر المستخدم على الإشعار.
body_loc_key	اختياري، سلسلة	تمثّل هذه السمة مفتاح السلسلة الأساسية في موارد سلسلة التطبيق لاستخدامها في أقلمة النص الأساسي بما يناسب الأقلمة الحالية للمستخدم. يُرجى الاطّلاع على موارد السلسلة للحصول على مزيد من المعلومات.
body_loc_args	اختياري، مصفوفة JSON كسلسلة	قيم سلسلة متغيرة لاستخدامها بدلاً من محددات التنسيق في body_loc_key بغرض ترجمة النص الأساسي بما يناسب الأقلمة الحالية للمستخدم راجِع التنسيق والنمط للاطّلاع على مزيد من المعلومات.
title_loc_key	اختياري، سلسلة	تمثّل هذه السمة مفتاح سلسلة العنوان في موارد سلسلة التطبيق المطلوب استخدامها لترجمة نص العنوان حسب الترجمة الحالية للمستخدم. يُرجى الاطّلاع على موارد السلسلة للحصول على مزيد من المعلومات.
title_loc_args	اختياري، مصفوفة JSON كسلسلة	قيم سلسلة المتغيّرات التي سيتم استخدامها بدلاً من محدّدات التنسيقات في title_loc_key من أجل استخدام هذه القيم لأقلمة نص العنوان بما يناسب الأقلمة الحالية لدى المستخدم راجِع التنسيق والنمط للاطّلاع على مزيد من المعلومات.

الجدول 2 (ج). الويب (JavaScript) - مفاتيح رسائل الإشعارات

المَعلمة	الاستخدام	الوصف
title	اختياري، سلسلة	عنوان الإشعار.
body	اختياري، سلسلة	النص الأساسي للإشعار.
icon	اختياري، سلسلة	عنوان URL الذي سيتم استخدامه لرمز الإشعار.
click_action	اختياري، سلسلة	يشير ذلك المصطلح إلى الإجراء المرتبط بالمستخدم الذي ينقر على الإشعار. يجب استخدام HTTPS لجميع قيم عناوين URL.

رسائل HTTP المتحوّلة سريعًا (نص عادي)

يسرد الجدول التالي بنية الأهداف والخيارات والحمولة في رسائل HTTP التي تتمّ معالجتها بنص عادي.

الجدول 3. الأهداف والخيارات والحمولة لرسائل HTTP النصية العادية التي يتم إرسالها تلقائيًا

المَعلمة	الاستخدام	الوصف
الأهداف
registration_id	مطلوب، سلسلة	تحدِّد هذه المَعلمة تطبيقات العميل (الرموز المميّزة للتسجيل) التي تتلقّى الرسالة. يُسمح بإرسال الرسائل التي تتضمّن أكثر من رمز مميّز واحد للتسجيل) باستخدام تنسيق HTTP JSON فقط.
الخيارات
collapse_key	اختياري، سلسلة	راجِع الجدول 1 للحصول على التفاصيل.
time_to_live	اختياري، رقم	راجِع الجدول 1 للحصول على التفاصيل.
restricted_package_name	اختياري، سلسلة	راجِع الجدول 1 للحصول على التفاصيل.
dry_run	اختياري، منطقية	راجِع الجدول 1 للحصول على التفاصيل.
الحمولة
data.<key>	اختياري، سلسلة	تحدد هذه المعلمة أزواج المفتاح/القيمة لحمولة الرسالة. ليس هناك حدّ أقصى لعدد مَعلمات القيم والمفاتيح، ولكن هناك حدّ أقصى لإجمالي حجم الرسالة يبلغ 4096 بايت. على سبيل المثال، في Android، سيؤدي إدخال "data.score"."3x1" إلى إضافة عنصر باسم score بقيمة السلسلة 3x1. يجب ألا يكون المفتاح كلمة محجوزة ("from" أو "message_type" أو أي كلمة تبدأ بـ "google" أو "gcm"). لا تستخدم أيًا من الكلمات الواردة في هذا الجدول (مثل collapse_key).

تفسير الرد على رسالة استلام الطلب

يجب أن يقيّم خادم التطبيق كلاً من عنوان استجابة الرسالة والنص لتفسير استجابة الرسالة المُرسَلة من خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". يصف الجدول التالي الردود المحتملة.

الجدول 4. عنوان استجابة رسالة HTTP المنتقل إليها لاحقًا

الردّ	الوصف
200	تمت معالجة الرسالة بنجاح. سيحتوي نص الاستجابة على مزيد من التفاصيل حول حالة الرسالة، ولكن سيعتمد تنسيقها على ما إذا كان الطلب بتنسيق JSON أو نص عادي. راجِع الجدول 5 لمزيد من التفاصيل.
400	لا ينطبق هذا الإعداد إلا على طلبات JSON. يشير ذلك إلى تعذّر تحليل الطلب كملف JSON أو أنّه يحتوي على حقول غير صالحة (على سبيل المثال، تمرير سلسلة حيث كان من المتوقّع إدخال رقم). يتم وصف السبب الدقيق للفشل في الرد ويجب معالجة المشكلة قبل إعادة محاولة الطلب.
401	حدث خطأ أثناء مصادقة حساب المُرسِل.
5xx	تشير الأخطاء التي تقع في النطاق 500-599 (مثل 500 أو 503) إلى حدوث خطأ داخلي في الواجهة الخلفية للمراسلة عبر السحابة الإلكترونية من Firebase أثناء محاولة معالجة الطلب، أو أنّ الخادم غير متاح مؤقتًا (بسبب حالات انتهاء المهلة مثلاً). على المُرسِل إعادة المحاولة لاحقًا، التزامًا بأي عنوان Retry-After تم تضمينه في الردّ. يجب أن تنفذ خوادم التطبيقات وظيفة الرقود الأسي الثنائي.

يسرد الجدول التالي الحقول في نصّ استجابة الرسالة (JSON).

الجدول 5: نص استجابة رسالة HTTP المتسلسلة (JSON)

المَعلمة	الاستخدام	الوصف
multicast_id	مطلوب، رقم	المعرّف الفريد (الرقم) الذي يعرّف رسالة البث المتعدد
success	مطلوب، رقم	عدد الرسائل التي تمت معالجتها بدون خطأ.
failure	مطلوب، رقم	عدد الرسائل التي تعذَّرت معالجتها.
results	مطلوب، مصفوفة الكائنات	مصفوفة من العناصر التي تمثّل حالة الرسائل التي تمت معالجتها. ويتم إدراج العناصر بنفس ترتيب الطلب (أي سيتم إدراج نتيجتها في الفهرس نفسه ضمن الاستجابة لكل رقم تعريف تسجيل في الطلب). message_id: سلسلة تحدّد معرّفًا فريدًا لكل رسالة تمت معالجتها بنجاح. error: سلسلة تحدد الخطأ الذي حدث عند معالجة رسالة المُستلِم. يمكن العثور على القيم المحتملة في الجدول 9.

الجدول 6. نص استجابة HTTP لرسالة الموضوع (JSON).

المَعلمة	الاستخدام	الوصف
message_id	اختياري، رقم	معرّف رسالة الموضوع عند استلام خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" الطلب بنجاح وستحاول تسليمه إلى جميع الأجهزة التي تم الاشتراك فيها.
error	اختياري، سلسلة	حدث خطأ أثناء معالجة الرسالة. يمكن العثور على القيم المحتملة في الجدول 9.

الجدول 7: استجابة ناجحة لنص استجابة رسالة HTTP المنتقل إليها (نص عادي)

المَعلمة	الاستخدام	الوصف
id	مطلوب، سلسلة	تحدّد هذه المَعلمة المعرّف الفريد للرسالة في "المراسلة عبر السحابة الإلكترونية من Firebase" الذي تمت معالجته بنجاح.
registration_id	اختياري، سلسلة	تحدّد هذه المعلمة الرمز المميّز للتسجيل لتطبيق العميل الذي تمت معالجة الرسالة وإرسالها إليه.

الجدول 8. استجابة خطأ لنص استجابة رسالة HTTP المتنقلة (نص عادي).

المَعلمة	الاستخدام	الوصف
Error	مطلوب، سلسلة	تُحدِّد هذه المَعلمة قيمة الخطأ أثناء معالجة الرسالة للمستلِم. راجِع الجدول 9 للحصول على التفاصيل.

رموز الاستجابة للأخطاء التي تحدث في مرحلة متأخرة من الوقت

يسرد الجدول التالي رموز الاستجابة للأخطاء للرسائل التي تلي استلام البريد.

الجدول 9. رموز الاستجابة لأخطاء رسائل البريد المتأخّر.

خطأ	رمز HTTP	الإجراء المقترَح
الرمز المميّز للتسجيل غير متوفّر	200 + الخطأ:التسجيل غير موجود	تأكَّد من أنّ الطلب يتضمّن رمزًا مميّزًا للتسجيل (في registration_id في رسالة نصية عادية، أو في الحقل to أو registration_ids بتنسيق JSON).
الرمز المميّز للتسجيل غير صالح	200 + خطأ:تسجيل غير صالح	تحقَّق من تنسيق الرمز المميّز للتسجيل الذي تمرِّره إلى الخادم. تأكد من تطابقه مع الرمز المميز للتسجيل الذي يتلقاه تطبيق العميل من التسجيل باستخدام إشعارات Firebase. لا تقتطع أحرفًا أو تدرجها.
جهاز غير مسجَّل	200 + الخطأ:غير مسجَّل	قد يصبح الرمز المميّز الحالي للتسجيل غير صالح في عدد من السيناريوهات، بما في ذلك: إذا ألغى تطبيق العميل التسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase": إذا تم إلغاء تسجيل تطبيق العميل تلقائيًا، وقد يحدث ذلك إذا ألغى المستخدم تثبيت التطبيق. على سبيل المثال، في أجهزة iOS، إذا أبلغت "خدمة ملاحظات أسماء نقاط الوصول" (APN) أنّ الرمز المميّز لأسماء نقاط الوصول غير صالح. في حال انتهاء صلاحية الرمز المميّز للتسجيل (على سبيل المثال، قد تقرِّر Google إعادة تحميل الرموز المميّزة للتسجيل أو قد انتهت صلاحية الرموز المميّزة لأسماء نقاط الوصول (APN) لأجهزة iOS). إذا تم تحديث تطبيق العميل، ولكن لم يتم ضبط الإصدار الجديد على تلقّي الرسائل. في جميع هذه الحالات، عليك إزالة الرمز المميّز للتسجيل من خادم التطبيق والتوقّف عن استخدامه لإرسال الرسائل.
اسم الحزمة غير صالح	200 أكثر من الخطأ:UnknownPackageName	تأكد من أن الرسالة موجهة إلى رمز مميز للتسجيل يتطابق اسم حزمته مع القيمة التي تم تمريرها في الطلب.
خطأ في المصادقة	401	تعذّرت مصادقة حساب المُرسِل المستخدَم لإرسال رسالة. الأسباب المحتمَلة هي: عنوان التفويض مفقود أو يحتوي على بنية غير صالحة في طلب HTTP. مشروع Firebase الذي ينتمي إليه مفتاح الخادم المحدّد غير صحيح. مفاتيح الخادم القديمة فقط: نشأ الطلب من خادم غير مُدرَج في القائمة البيضاء في عناوين IP لمفاتيح الخادم. تأكَّد من أنّ الرمز المميّز الذي ترسله داخل عنوان المصادقة هو مفتاح الخادم الصحيح المرتبط بمشروعك. يمكنك الاطّلاع على مقالة التحقق من صلاحية مفتاح الخادم لمعرفة التفاصيل. وإذا كنت تستخدم مفتاح خادم قديمًا، ننصحك بالترقية إلى مفتاح جديد لا يفرض أي قيود على عناوين IP. راجِع القسم نقل مفاتيح الخادم القديمة.
المُرسِل غير متطابق	200 + الخطأ:MismatchSenderId	ويرتبط الرمز المميّز للتسجيل بمجموعة معيّنة من المُرسِلين. عندما يسجِّل تطبيق عميل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، يجب تحديد المرسِلين المسموح لهم بإرسال الرسائل. يجب استخدام أحد معرّفات المُرسِلين هذه عند إرسال الرسائل إلى تطبيق العميل. إذا بدّلت إلى مُرسِل مختلف، لن تعمل الرموز المميّزة الحالية للتسجيل.
ملف JSON غير صالح	400	تحقَّق من أنّ رسالة JSON منسّقة بشكلٍ صحيح وتحتوي على حقول صالحة (على سبيل المثال، التأكّد من إدخال نوع البيانات الصحيح).
مَعلمات غير صالحة	400 + الخطأ:غير صالح	تحقَّق من أن المَعلمات المقدّمة لها الاسم والنوع الصحيحَين.
الرسالة كبيرة جدًا.	200 + خطأ:MessageTooBig	تحقَّق من أن الحجم الإجمالي لبيانات الحمولة المضمّنة في الرسالة لا يتجاوز حدود "المراسلة عبر السحابة الإلكترونية من Firebase": 4096 بايت لمعظم الرسائل، أو 2048 بايت في حالة الرسائل الموجَّهة إلى المواضيع. يتضمن ذلك كلاً من المفاتيح والقيم.
مفتاح بيانات غير صالح	200 أكثر من الخطأ: UnknownDataKey	تأكَّد من أنّ بيانات الحمولة لا تحتوي على مفتاح (مثل from أو gcm، أو أي قيمة تبدأ بـ google) تستخدمها خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" داخليًا. تجدر الإشارة إلى أنّ بعض الكلمات (مثل collapse_key) تستخدمها خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" أيضًا، ولكن يُسمح باستخدامها في الحمولة، وفي هذه الحالة ستتجاهل قيمة "المراسلة عبر السحابة الإلكترونية من Firebase" قيمة الحمولة.
مدة البقاء غير صالحة	200 + خطأ:غير صالحTtl	تأكَّد من أنّ القيمة المستخدَمة في time_to_live هي عدد صحيح يمثّل مدة بالثواني بين 0 و2419,200 (4 أسابيع).
وقت مستقطع	5xx أو 200 + الخطأ:غير متاح	لم يتمكّن الخادم من معالجة الطلب في الوقت المناسب. يُرجى إعادة محاولة الطلب نفسه، ولكن يجب: عليك تنفيذ عنوان Retry-After إذا تم تضمينه في الاستجابة من خادم اتصال "المراسلة عبر السحابة الإلكترونية من Firebase". تنفيذ الرقود الأسي في آلية إعادة المحاولة. (على سبيل المثال، إذا انتظرت ثانية واحدة قبل إعادة المحاولة الأولى، فانتظر ثانيتين على الأقل قبل الثانية التالية، ثم 4 ثوانٍ وما إلى ذلك). في حال إرسالك رسائل متعددة، عليك تأخير كل رسالة على حدة بمبلغ عشوائي إضافي لتجنُّب إصدار طلب جديد لجميع الرسائل في الوقت نفسه. قد يُدرج المُرسِلون الذين يسببون مشاكل في قائمة سوداء.
خطأ في الخادم الداخلي	500 أو 200 + خطأ:internalServerError	حدث خطأ في الخادم أثناء محاولة معالجة الطلب. يمكنك إعادة محاولة تقديم الطلب نفسه باتّباع المتطلبات المذكورة في "المهلة" (راجِع الصف أعلاه). في حال استمرار ظهور الخطأ، يُرجى التواصل مع فريق دعم Firebase.
تم تجاوز معدّل الرسائل على الجهاز	200 + خطأ: DeviceMessageRate تم تجاوز	معدّل الرسائل إلى جهاز معيّن مرتفع جدًا. إذا كان أحد تطبيقات Apple يرسل رسائل بمعدل يتجاوز حدود أسماء نقاط الوصول (APN)، قد تظهر رسالة الخطأ هذه. عليك تقليل عدد الرسائل المُرسَلة إلى هذا الجهاز واستخدام ميزة الرقود الأسي لإعادة محاولة الإرسال.
تم تجاوز معدل رسائل الموضوعات	200 أكثر من الخطأ: TopicsMessageRate تم تجاوز	معدل الرسائل الموجهة إلى المشتركين في موضوع معين مرتفع جدًا. قلِّل عدد الرسائل المُرسَلة حول هذا الموضوع واستخدِم ميزة التراجع exponential لإعادة محاولة الإرسال.
بيانات اعتماد أسماء نقاط الوصول غير صالحة.	200 أكثر من الخطأ: ValidApnsCredential	تعذَّر إرسال رسالة موجَّهة إلى جهاز Apple بسبب عدم تحميل مفتاح مصادقة أسماء نقاط الوصول المطلوب أو انتهاء صلاحيته. تحقق من صلاحية بيانات اعتماد التطوير والإنتاج.

إدارة مجموعة الأجهزة

يسرد الجدول التالي المفاتيح لإنشاء مجموعات الأجهزة وإضافة الأعضاء وإزالتهم. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على الدليل الخاص بالنظام الأساسي الذي تستخدمه، +iOS أو Android.

الجدول 10. مفاتيح إدارة مجموعات الأجهزة.

المَعلمة	الاستخدام	الوصف
operation	مطلوب، سلسلة	العملية المطلوب تنفيذها هي القيم الصالحة create وadd وremove.
notification_key_name	مطلوب، سلسلة	الاسم الذي حدّده المستخدم لمجموعة الأجهزة المطلوب إنشاؤها أو تعديلها.
notification_key	مطلوبة (باستثناء عملية create، سلسلة	المعرّف الفريد لمجموعة الأجهزة يتم عرض هذه القيمة في الاستجابة لعملية create ناجحة، وهي مطلوبة لجميع العمليات اللاحقة على مجموعة الأجهزة.
registration_ids	مطلوب، مصفوفة من السلاسل	الرموز المميّزة للجهاز المطلوب إضافتها أو إزالتها إذا أزلت جميع الرموز المميّزة للتسجيل الحالية من مجموعة أجهزة، ستحذف خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" مجموعة الأجهزة.