مرجع الخادم

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تنفيذ الخادم اختياري. استخدم خدمة معرّف المثيل إذا كنت تريد تنفيذ هذه العمليات:

الحصول على معلومات عن مثيلات التطبيق

للحصول على معلومات عن مثيل تطبيق، يمكنك استدعاء خدمة معرّف النسخة الافتراضية على نقطة النهاية هذه، مع تقديم الرمز المميز لتطبيق التطبيق على النحو الموضّح:

 https://iid.googleapis.com/iid/info/IID_TOKEN

المعلَمات

  • Authorization: key=YOUR_API_KEY. عيّن هذه المعلمة في العنوان.
  • [اختياري] المنطقية details: عيِّن معلمة طلب البحث هذه على true للحصول على معلومات اشتراك FCM أو GCM (إن وجدت) المرتبطة بهذا الرمز المميز. وعند عدم تحديدها، يتم تعيينها تلقائيًا على false.

النتائج

عند نجاح العملية، تعرض المكالمة حالة HTTP 200 وكائن JSON يحتوي على:

  • application - اسم الحزمة المرتبط بالرمز المميز.
  • authorizedEntity - تم تفويض رقم تعريف المشروع للإرسال إلى الرمز المميز.
  • applicationVersion - إصدار التطبيق.
  • الملف المرجعي للحزمة المطبَّقة على الحزمة من appSigner إلى sha1 يشير إلى الطرف الذي وقّع على التطبيق، مثل Play Store.
  • platform: تعرض ANDROID أو IOS أو CHROME للإشارة إلى النظام الأساسي للجهاز الذي ينتمي إليه الرمز المميّز.

في حال ضبط علامة details:

  • rel - العلاقات المقترنة بالرمز المميز. على سبيل المثال، قائمة باشتراكات المواضيع.

مثال على طلب GET

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

مثال للنتيجة

HTTP 200 OK
{
  "application":"com.iid.example",
  "authorizedEntity":"123456782354",
  "platform":"Android",
  "appSigner":"1a2bc3d4e5"
  "rel":{
    "topics":{
      "topicname1":{"addDate":"2015-07-30"},
      "topicname2":{"addDate":"2015-07-30"},
      "topicname3":{"addDate":"2015-07-30"},
      "topicname4":{"addDate":"2015-07-30"}
    }
  }
}

إنشاء خرائط علاقات لمثيلات التطبيق

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

إنشاء تعيين للعلاقة لأحد مثيلات التطبيق

بالنظر إلى رمز مميز للتسجيل وعلاقة معتمدة، يمكنك إنشاء تعيين. على سبيل المثال، يمكنك الاشتراك في مثيل تطبيق على موضوع خدمة مراسلة عبر السحابة الإلكترونية من Google من خلال طلب خدمة رقم تعريف المثيل على نقطة النهاية هذه، وتقديم الرمز المميّز لنسخة التطبيق كما هو موضّح:

 https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME

المعلَمات

  • Authorization: key=YOUR_API_KEY. عيّن هذه المعلمة في العنوان.

النتائج

عند نجاح العملية، تعرض المكالمة حالة HTTP 200.

مثال على طلب POST

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

مثال للنتيجة

HTTP 200 OK
{}

إدارة خرائط العلاقات لمثيلات تطبيقات متعددة

وباستخدام طرق تجميع خدمة معرّف المثيل، يمكنك إجراء إدارة مجمّعة لمثيلات التطبيقات. على سبيل المثال، يمكنك إجراء إضافة مجمّعة أو إزالة مثيلات التطبيق إلى موضوع FCM أو GCM. لتعديل ما يصل إلى 1000 نسخة من التطبيق لكل استدعاء لواجهة برمجة التطبيقات، يمكنك استدعاء خدمة معرّف النسخة الافتراضية في نقطة النهاية هذه، وتقديم الرموز المميزة لنسخة التطبيق في نص JSON:

 https://iid.googleapis.com/iid/v1:batchAdd

 https://iid.googleapis.com/iid/v1:batchRemove

المعلَمات

  • Authorization: key=YOUR_API_KEY. عيّن هذه المعلمة في العنوان.
  • to : اسم الموضوع.
  • registration_tokens : صفيف من رموز IID المميزة لمثيلات التطبيق التي تريد إضافتها أو إزالتها.

النتائج

عند نجاح العملية، تعرض المكالمة حالة HTTP 200. تشير النتائج الفارغة إلى نجاح الاشتراك في الرمز المميز. بالنسبة إلى الاشتراكات التي أخفقت، تحتوي النتيجة على أحد رموز الخطأ التالية:

  • NOT_FOUND — تم حذف الرمز المميز للتسجيل أو تمت إزالة التطبيق.
  • INVALID_ARGUMENT - الرمز المميز للتسجيل المقدَّم غير صالح لمُعرِّف المُرسِل.
  • داخلي — فشل خادم الخلفية لأسباب غير معروفة. أعِد محاولة الطلب.
  • TOO_MANY_TOPICS — عدد زائد من المواضيع لكل مثيل تطبيق.
  • RESOURCE_EXHAUSTED — هناك عدد كبير جدًا من طلبات الاشتراك أو إلغاء الاشتراك في فترة زمنية قصيرة. إعادة المحاولة باستخدام التراجع الأسي.

مثال على طلب POST

https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization:key=API_KEY
{
   "to": "/topics/movies",
   "registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}

مثال للنتيجة

HTTP 200 OK
{
  "results":[
    {},
    {"error":"NOT_FOUND"},
    {},
  ]
}

إنشاء رموز مميّزة للتسجيل الخاصّة برموز APN المميزة

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

 https://iid.googleapis.com/iid/v1:batchImport

يحتوي نص الاستجابة على مصفوفة من الرموز المميزة لتسجيل رقم تعريف المثيل الجاهزة للاستخدام لإرسال رسائل FCM أو GCM إلى الرمز المميز المقابل لأجهزة APN.

المعلَمات

  • Authorization: key=YOUR_API_KEY. عيّن هذه المعلمة في العنوان.
  • application : معرّف حزمة التطبيق.
  • sandbox : قيمة منطقية للإشارة إلى بيئة وضع الحماية (TRUE) أو الإنتاج (FALSE)
  • apns_tokens : صفيف من رموز APN المميزة لمثيلات التطبيق التي تريد إضافتها أو إزالتها. الحد الأقصى 100 رمز مميّز لكل طلب.

النتائج

عند نجاح العملية، تعرض المكالمة حالة HTTP 200 ونص نتيجة JSON. لكل رمز مميز لخدمة APN تم تقديمه في الطلب، تتضمن قائمة النتائج ما يلي:

  • رمز APN المميز.
  • الحالة. إما موافق أو رسالة خطأ تصف الإخفاق.
  • للحصول على النتائج الناجحة، يتم تعيين الرمز المميز للتسجيل الذي تم تعيينه بواسطة FCM أو GCM إلى الرمز المميز لبروتوكول APN.

مثال على طلب POST

https://iid.googleapis.com/iid/v1:batchImport
{
  "application": "com.google.FCMTestApp",
  "sandbox":false,
  "apns_tokens":[
      "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
      "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
   ]
  }
}

مثال للنتيجة

HTTP 200 OK
{
 "results":[
       {
        "apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
         "status": "OK",
         "registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
       },
       {
         "apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
         "status":"Internal Server Error"
        },
     ]
  }

إدارة الرموز المميّزة للتسجيل لاشتراكات Push

باستخدام طرق الويب لخدمة معرّف المثيل، يمكنك استيراد الاشتراكات الحالية لـ Firebase Cloud Messaging. يمكنك أيضًا تحديثها وحذفها.

عند استيراد اشتراك الدفع، ستتلقى رمزًا مميزًا للتسجيل. يتيح لك هذا الرمز المميز استخدام ميزات FCM مثل مراسلة الموضوع والمراسلة الجماعية على الجهاز لتوجيه الإشعارات إلى تطبيقات الويب.

استيراد اشتراكات الدفع

يمكنك استيراد الاشتراكات الفورية باستخدام نقطة نهاية الويب في InstanceID:

 https://iid.googleapis.com/v1/web/iid

يجب أن يتضمّن الطلب رأس تفويض تم ضبطه على رمز دخول OAuth 2.0، وعنوان مفتاح تشفير معيّن على مفتاح خادم التطبيق، وكائن PushSubscription في نص الطلب.

يحتوي نص الاستجابة على رمز مميّز للتسجيل جاهز للاستخدام لإرسال رسائل FCM أو GCM إلى مثيل تطبيق الويب المقابل بدون الحاجة إلى تشفير الحمولة.

تحميل زوج المفاتيح VAPID إلى وحدة التحكم

لاستيراد المفاتيح، يجب أن يكون لديك حق وصول المالك على مستوى مشروع Firebase. استورد المفتاح العام والخاص الحالي في نموذج تشفير base64 URL الآمن:

  1. افتح علامة تبويب Cloud Messaging من لوحة إعدادات وحدة تحكم Firebase ومرر إلى قسم تهيئة الويب.
  2. في علامة التبويب شهادات Web Push، ابحث عن نص الرابط، واختر "استيراد زوج من المفاتيح الحالية" واختره.
  3. في مربع الحوار استيراد زوج مفاتيح، قدِّم المفاتيح العامة والخاصة في الحقول المقابلة وانقر على استيراد. تعرض وحدة التحكم سلسلة المفتاح العمومي وتاريخ إضافته.

استرداد رمز OAuth2 المميز: استخدام بيانات الاعتماد للحصول على رموز الدخول المميزة

ولإنشاء رمز دخول لهذا الطلب، ستحتاج إلى إضافة رمز الدخول إلى طلب HTTP وإضافته إلى طلب HTTP.

عقدة js.

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}
index.js

لغة Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token
configure.py

لغة Java

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}
Configure.java

للسماح بالوصول إلى FCM، اطلب النطاق https://www.googleapis.com/auth/firebase.messaging.

المعلَمات

  • التفويض: Bearer <access_token>. عيّن هذه المعلمة في العنوان.
  • مفتاح التشفير: p256ecdsa=APPLICATION_PUBLIC_KEY. عيّن هذه المعلمة في العنوان.
  • نص الطلب: PushSubscription.toJson(). تمرير اشتراك الدفع إلى نص HTTP بدون تحليله. يطابق المحتوى ترميز W3C لـ PushSubscription.

الإجابة

عند الاستدعاء بنجاح، تعرض الاستدعاءة حالة HTTP 200 OK ونص نتيجة JSON يحتوي على الرمز المميز IID.

مثال على طلب POST

 https://iid.googleapis.com/v1/web/iid
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

مثال للنتيجة

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

تحديث اشتراكات الدفع

يمكنك تحديث الاشتراك الفوري المرتبط بالرمز المميز للتسجيل باستخدام نقطة النهاية التالية:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh

المعلَمات

  • التفويض: Bearer <access_token>. عيّن هذه المعلمة في العنوان.
  • مفتاح التشفير: p256ecdsa=APPLICATION_PUBLIC_KEY. عيّن هذه المعلمة في العنوان.
  • نص الطلب: PushSubscription.toJson(). تمرير اشتراك الدفع إلى نص HTTP بدون تحليله. يطابق المحتوى ترميز W3C لـ PushSubscription.

النتائج

عند النجاح في المكالمة، يتم عرض حالة HTTP 200 ورمز مميز للتسجيل. وقد يكون هذا هو الرمز المميز نفسه الذي مررت به في الطلب أو رمزًا مميزًا جديدًا.

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

مثال على طلب POST

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CKrh_PC...cl:refresh
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q"",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

مثال للنتيجة

 HTTP 200 OK
 {
  "token":"KctODamlM4:CI2k_HHw...3P1"
 }

حذف اشتراكات الدفع

يؤدي طلب DELETE إلى إزالة تفاصيل اشتراك الدفع من قاعدة بيانات FCM. ولا يزال بإمكانك تلقي رسائل في تطبيق الويب باستخدام بروتوكول Push API.

لحذف اشتراك فوري، أرسِل طلب DELETE إلى:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN

مثال على طلب DELETE

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

مثال للنتيجة

 HTTP 200 OK {}

الردود على الأخطاء

تؤدي الطلبات إلى واجهة برمجة تطبيقات خادم معرّف المثيل إلى عرض رموز خطأ HTTP التالية:

  • HTTP status 400 (Bad request) - معلمات الطلب مفقودة أو غير صالحة. تحقق من رسائل الخطأ للحصول على معلومات تفصيلية.
  • HTTP status 401 (Unauthorized) - عنوان التفويض غير صالح.
  • HTTP status 403 (Forbidden) - لا يتطابق عنوان التفويض مع authorizedEntity.
  • HTTP status 404 (Not found) - لم يتم العثور على مسار HTTP أو رمز IID المميز غير صالح. تحقق من رسائل الخطأ للحصول على معلومات تفصيلية.
  • HTTP status 503 (Service unavailable) - الخدمة غير متوفرة. أعد تجربة الطلب باستخدام التراجع الأسي.