مراجع الخادم

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

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

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

 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 إنشاء خرائط العلاقات لمثيلات التطبيق. على سبيل المثال، يمكنك ربط رمز مميَّز للتسجيل بموضوع "المراسلة عبر السحابة الإلكترونية من Firebase"، واشتراك مثيل التطبيق بالموضوع. توفر واجهة برمجة التطبيقات طرقًا لإنشاء مثل هذه العلاقات بشكل فردي ومجمّع.

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

بناءً على رمز مميز للتسجيل وعلاقة مدعومة، يمكنك إنشاء تعيين. على سبيل المثال، يمكنك اشتراك مثيل تطبيق في موضوع "المراسلة عبر السحابة الإلكترونية من 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 — تم حذف الرمز المميز للتسجيل أو تم إلغاء تثبيت التطبيق.
  • nofollow_verification - رمز التسجيل الذي تم تقديمه غير صالح لمعرّف المرسل.
  • داخلي — تعذّر خادم الخلفية لأسباب غير معروفة. يُرجى إعادة محاولة إرسال الطلب.
  • TOO_MANY_TOPICS — عدد كبير من المواضيع لكل نسخة افتراضية من التطبيق.
  • RI_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 في خدمة معرّف المثيل، يمكنك استيراد الرموز المميّزة الحالية لأسماء نقاط الوصول (APN) لنظام التشغيل iOS إلى خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" بشكل مجمّع، وربطها برموز مميّزة صالحة للتسجيل. استدعِ خدمة معرّف المثيل في نقطة النهاية هذه، مع تقديم قائمة برموز APNs في نص 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) - الخدمة غير متاحة. أعد محاولة الطلب باستخدام الرقود الأسي.