مراجع الخادم

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

الحصول على معلومات عن نُسخ التطبيق

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

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

المَعلمات

  • Authorization: Bearer <access_token>: يجب ضبط هذه المَعلمة في العنوان. أضِف رمز OAuth2 مميزًا قصير الأجل كقيمة لعنوان Authorization. لمزيد من المعلومات حول الحصول على هذا الرمز المميّز، يُرجى الاطّلاع على توفير بيانات الاعتماد يدويًا.
  • access_token_auth: true: يجب ضبط هذه المَعلمة في العنوان.
  • [اختياري] القيمة المنطقية details: يجب ضبط معلَمة طلب البحث هذه على true للحصول على معلومات حول الاشتراك في موضوع "المراسلة عبر السحابة الإلكترونية من Firebase" (إن وجدت) مرتبطة بهذا الرمز المميّز. وفي حال عدم تحديدها، يتم ضبطها تلقائيًا على false.

النتائج

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

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

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

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

مثال على طلب GET

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true

مثال على النتيجة

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

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

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

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

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

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

المَعلمات

  • Authorization: Bearer <access_token>: يجب ضبط هذه المَعلمة في العنوان. أضِف رمز OAuth2 مميزًا قصير الأجل كقيمة لعنوان Authorization. لمزيد من المعلومات حول الحصول على هذا الرمز المميّز، يُرجى الاطّلاع على توفير بيانات الاعتماد يدويًا.
  • access_token_auth: true: يجب ضبط هذه المَعلمة في العنوان.

النتائج

عند نجاح الطلب، تعرض الاستدعاء حالة HTTP 200.

مثال على طلب POST

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true

مثال على النتيجة

HTTP 200 OK
{}

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

يمكنك استخدام طرق دُفعة خدمة Instance ID لإجراء إدارة مجمّعة لمثيلات التطبيق. على سبيل المثال، يمكنك إضافة أو إزالة مثيلات التطبيق بشكل مجمّع إلى موضوع "المراسلة عبر السحابة الإلكترونية من Firebase". لتحديث ما يصل إلى 1000 نسخة تطبيق لكل طلب بيانات من واجهة برمجة التطبيقات، استدعِ خدمة "رقم تعريف المثيل" في نقطة النهاية هذه، مع توفير الرموز المميزة لنسخة التطبيق في نص JSON:

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

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

المَعلمات

  • Authorization: Bearer <access_token>: يجب ضبط هذه المَعلمة في العنوان. أضِف رمز OAuth2 مميزًا قصير الأجل كقيمة لعنوان Authorization. لمزيد من المعلومات حول الحصول على هذا الرمز المميّز، يُرجى الاطّلاع على توفير بيانات الاعتماد يدويًا.
  • access_token_auth: true: يجب ضبط هذه المَعلمة في العنوان.
  • to : اسم الموضوع
  • registration_tokens : مصفوفة رموز IID المميَّزة لمثيلات التطبيق التي تريد إضافتها أو إزالتها

النتائج

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

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

مثال على طلب POST

https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true
{
   "to": "/topics/movies",
   "registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}

مثال على النتيجة

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

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

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

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

يحتوي نص الاستجابة على مصفوفة من الرموز المميّزة لتسجيل رقم تعريف المثيل الجاهزة للاستخدام لإرسال رسائل "المراسلة عبر السحابة الإلكترونية من Firebase" إلى الرمز المميز للجهاز المتوافق مع أسماء نقاط الوصول (APN).

المَعلمات

  • Authorization: Bearer <access_token>: يجب ضبط هذه المَعلمة في العنوان. أضِف رمز OAuth2 مميزًا قصير الأجل كقيمة لعنوان Authorization. لمزيد من المعلومات حول الحصول على هذا الرمز المميّز، يُرجى الاطّلاع على توفير بيانات الاعتماد يدويًا.
  • access_token_auth: true: يجب ضبط هذه المَعلمة في العنوان.
  • application : معرِّف حزمة التطبيق
  • sandbox : قيمة منطقية للإشارة إلى بيئة وضع الحماية (TRUE) أو مرحلة الإنتاج (FALSE)
  • apns_tokens : مصفوفة من رموز APN لمثيلات التطبيق التي تريد إضافتها أو إزالتها. يمكن إدخال 100 رمز مميّز كحدّ أقصى لكل طلب.

النتائج

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

  • الرمز المميز لنقاط الوصول (APN)
  • الحالة. إما "حسنًا"، أو رسالة خطأ تصف الفشل.
  • للحصول على نتائج ناجحة، يتم ربط الرمز المميّز للتسجيل الذي يتم ربطه بخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" بالرمز المميّز لرموز APN.

مثال على طلب POST

https://iid.googleapis.com/iid/v1:batchImport
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth:true
{
  "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"
        },
     ]
  }

الردود التي تتضمّن خطأ

تؤدي الاستدعاءات إلى واجهة برمجة تطبيقات خادم معرف المثيل إلى عرض رموز خطأ 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) - الخدمة غير متاحة. أعد محاولة الطلب باستخدام خوارزمية الرقود الأسي الثنائي.