مراجع الخادم

إنّ تنفيذ الخادم اختياري. استخدِم خدمة Instance ID إذا كنت تريد تنفيذ العمليات التالية:

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

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

 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" من خلال مثيل تطبيق عن طريق استدعاء خدمة Instance ID على نقطة النهاية هذه، مع تقديم الرمز المميز لمثيل التطبيق كما هو موضّح أدناه:

 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، يمكنك إجراء إدارة مجمّعة لمثيلات التطبيق. على سبيل المثال، يمكنك إجراء إضافة أو إزالة مجمّعة لمثيلات التطبيق إلى موضوع في FCM. لتعديل ما يصل إلى 1,000 مثيل تطبيق لكل طلب من واجهة برمجة التطبيقات، يمكنك استدعاء خدمة Instance ID عند نقطة النهاية هذه، مع توفير رموز مميزة لمثيلات التطبيق في نص 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 — تم حذف رمز التسجيل أو إلغاء تثبيت التطبيق.
  • INVALID_ARGUMENT — رمز التسجيل المقدَّم غير صالح لرقم تعريف المرسِل.
  • INTERNAL: تعذّر الوصول إلى خادم الخلفية لأسباب غير معروفة. أعِد محاولة إرسال الطلب.
  • 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"},
    {},
  ]
}

إنشاء رموز تسجيل لرموز APNs

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

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

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

المعلمات

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

النتائج

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

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

مثال على طلب 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"
        },
     ]
  }

ردود الأخطاء

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