مرجع سرور

پیاده‌سازی سرور اختیاری است. اگر می‌خواهید این عملیات را انجام دهید، از سرویس Instance ID استفاده کنید:

دریافت اطلاعات در مورد نمونه‌های برنامه

برای دریافت اطلاعات در مورد یک نمونه برنامه، سرویس Instance ID را در این نقطه پایانی فراخوانی کنید و توکن نمونه برنامه را مطابق شکل ارائه دهید:

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

پارامترها

  • Authorization: Bearer <access_token> . این پارامتر را در هدر تنظیم کنید. یک توکن OAuth2 با عمر کوتاه به عنوان مقدار هدر Authorization اضافه کنید. برای اطلاعات بیشتر در مورد دریافت این توکن، به بخش «ارائه دستی اعتبارنامه‌ها» مراجعه کنید.
  • access_token_auth: true . این پارامتر را در هدر تنظیم کنید.
  • [اختیاری] details بولی: این پارامتر پرس‌وجو را روی true تنظیم کنید تا اطلاعات اشتراک موضوع FCM (در صورت وجود) مرتبط با این توکن را دریافت کنید. در صورت عدم تعیین، به طور پیش‌فرض روی 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"}
    }
  }
}

ایجاد نقشه‌های رابطه برای نمونه‌های برنامه

API شناسه نمونه (Instance ID API) به شما امکان می‌دهد نقشه‌های رابطه‌ای برای نمونه‌های برنامه ایجاد کنید. برای مثال، می‌توانید یک توکن ثبت‌نام را به یک موضوع FCM نگاشت کنید و نمونه برنامه را به آن موضوع اختصاص دهید. این API روش‌هایی را برای ایجاد چنین روابطی هم به صورت جداگانه و هم به صورت انبوه ارائه می‌دهد.

ایجاد یک نگاشت رابطه برای یک نمونه برنامه

با داشتن یک توکن ثبت و یک رابطه‌ی پشتیبانی‌شده، می‌توانید یک نگاشت ایجاد کنید. برای مثال، می‌توانید با فراخوانی سرویس Instance ID در این نقطه‌ی پایانی، یک نمونه‌ی برنامه را در یک تاپیک FCM ثبت نام کنید و توکن نمونه‌ی برنامه را همانطور که نشان داده شده است، ارائه دهید:

 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 انجام دهید. برای به‌روزرسانی حداکثر ۱۰۰۰ نمونه برنامه در هر فراخوانی API، سرویس 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 — توکن ثبت نام ارائه شده برای شناسه فرستنده معتبر نیست.
  • داخلی — سرور backend به دلایل نامعلومی از کار افتاد. درخواست را دوباره امتحان کنید.
  • TOO_MANY_TOPICS — تعداد بیش از حد موضوعات در هر نمونه برنامه.
  • RESOURCE_EXHAUSTED — درخواست‌های اشتراک یا لغو اشتراک بسیار زیاد در مدت زمان کوتاه. با یک backoff نمایی دوباره امتحان کنید.

مثال درخواست 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 موجود iOS را به صورت انبوه به Firebase Cloud Messaging وارد کنید و آنها را به توکن‌های ثبت معتبر نگاشت کنید. سرویس Instance ID را در این نقطه پایانی فراخوانی کنید و لیستی از توکن‌های APN را در بدنه JSON ارائه دهید: 

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

بدنه پاسخ شامل آرایه‌ای از توکن‌های ثبت شناسه نمونه (Instance ID) است که آماده استفاده برای ارسال پیام‌های FCM به توکن دستگاه APN مربوطه می‌باشند.

پارامترها

  • Authorization: Bearer <access_token> . این پارامتر را در هدر تنظیم کنید. یک توکن OAuth2 با عمر کوتاه به عنوان مقدار هدر Authorization اضافه کنید. برای اطلاعات بیشتر در مورد دریافت این توکن، به بخش «ارائه دستی اعتبارنامه‌ها» مراجعه کنید.
  • access_token_auth: true . این پارامتر را در هدر تنظیم کنید.
  • application : شناسه بسته (bundle id) برنامه.
  • sandbox : مقدار بولی برای نشان دادن محیط sandbox (TRUE) یا محیط عملیاتی (FALSE)
  • apns_tokens : آرایه‌ای از توکن‌های APN برای نمونه‌های برنامه‌ای که می‌خواهید اضافه یا حذف کنید. حداکثر ۱۰۰ توکن در هر درخواست.

نتایج

در صورت موفقیت، فراخوانی وضعیت HTTP 200 و یک بدنه نتیجه JSON را برمی‌گرداند. برای هر توکن APN ارائه شده در درخواست، لیست نتایج شامل موارد زیر است:

  • توکن APN ها.
  • وضعیت. یا OK، یا یک پیام خطا که شکست را شرح می‌دهد.
  • برای نتایج موفقیت‌آمیز، توکن ثبت نام که FCM به توکن 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"
        },
     ]
  }

پاسخ‌های خطا

فراخوانی‌های API سرور 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) - سرویس در دسترس نیست. درخواست را با backoff نمایی دوباره امتحان کنید.