مراجع الخادم

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

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

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

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

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

إدارة خرائط العلاقات لنُسخ متعددة من التطبيق

باستخدام طرق الحِزم لخدمة "معرّف المثيل"، يمكنك تنفيذ معالجة ملفّات برمجية ل إدارة نُسخ التطبيق. على سبيل المثال، يمكنك إجراء عملية ملفّ تعريف مستخدمين جماعية لإضافة نُسخ التطبيق أو إزالتها من موضوع في "نظام إرسال الرسائل إلى الأجهزة الجوّالة من Google". لتعديل ما يصل إلى 1,000 مثيل تطبيق لكل طلب بيانات من واجهة برمجة التطبيقات، يمكنك استدعاء خدمة رقم تعريف المثيل في نقطة النهاية هذه، مع تقديم الرموز المميّزة لمثيل التطبيق في نص 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 : مصفوفة الرموز المميزة لأرقام تعريف الأجهزة لمثيلات التطبيق التي تريد إضافتها أو إزالتها.

النتائج

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

  • ‫NOT_FOUND: تم حذف الرمز المميّز للتسجيل أو تم إلغاء تثبيت التطبيق.
  • INVALID_ARGUMENT: الرمز المميّز للتسجيل الذي تم تقديمه غير صالح لرقم تعريف المُرسِل.
  • داخلي: تعذّر على خادم الخلفية تنفيذ الطلب لأسباب غير معروفة. يُرجى إعادة إرسال الطلب.
  • 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، يمكنك استيراد علامات iOS APNs الحالية بشكلٍ مجمّع إلى Firebase Cloud Messaging، وربطها بعلامات تسجيل صالحة. اتصل بخدمة 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 : صفيف الرموز المميزة لنقاط الوصول (APN) لمثيلات التطبيق التي تريد إضافتها أو إزالتها. الحد الأقصى لعدد الرموز المميّزة هو 100 رمز لكل طلب.

النتائج

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

  • الرمز المميّز لأسماء نقاط الوصول (APN)
  • الحالة. إما "حسنًا" أو رسالة خطأ توضّح سبب تعذُّر الإجراء
  • بالنسبة إلى النتائج الناجحة، يشير رمز تسجيل يربطه إطار عمل "إرسال الرسائل إلى الأجهزة الجوّالة من Google" برمز 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"
        },
     ]
  }

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

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