הפניה לשרת

ההטמעה בשרת היא אופציונלית. אם רוצים לבצע את הפעולות הבאות, צריך להשתמש בשירות Instance ID:

קבלת מידע על מופעים של אפליקציות

כדי לקבל מידע על מופע של אפליקציה, צריך להתקשר לשירות Instance ID בנקודת הקצה (endpoint) הזו, ולספק את האסימון של מופע האפליקציה כמו שמוצג כאן:

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

פרמטרים

  • ‫Authorization: Bearer <access_token>. מגדירים את הפרמטר הזה בכותרת. מוסיפים טוקן OAuth2 לזמן קצר כערך של הכותרת Authorization. מידע נוסף על קבלת האסימון הזה זמין במאמר בנושא הזנת פרטי כניסה באופן ידני.
  • ‫access_token_auth: true. מגדירים את הפרמטר הזה בכותרת.
  • ‫[optional] boolean 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"}
    }
  }
}

יצירת מפות קשרים למופעים של אפליקציות

‫Instance ID API מאפשר ליצור מפות קשרים למופעי אפליקציות. לדוגמה, אפשר למפות טוקן הרשמה לנושא ב-FCM, ובכך לרשום את מופע האפליקציה לנושא. ה-API מספק שיטות ליצירת קשרים כאלה באופן פרטני וגם בכמות גדולה.

יצירת מיפוי קשרים למופע של אפליקציה

אם יש לכם טוקן רישום וקשר נתמך, תוכלו ליצור מיפוי. לדוגמה, אפשר לרשום מופע של אפליקציה לנושא ב-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
{}

ניהול מפות קשרים למספר מופעים של אפליקציות

באמצעות שיטות אצווה של שירות מזהה המופע, אפשר לבצע ניהול אצווה של מופעי אפליקציות. לדוגמה, אפשר להוסיף או להסיר בבת אחת כמה מופעים של אפליקציות לנושא ב-FCM. כדי לעדכן עד 1, 000 מופעים של אפליקציות בכל קריאה ל-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 – טוקן ההרשמה שסופק לא תקף עבור מזהה השולח.
  • פנימי – השרת העורפי נכשל מסיבות לא ידועות. מנסים לשלוח את הבקשה שוב.
  • ‫TOO_MANY_TOPICS – מספר הנושאים לכל מופע של אפליקציה גדול מדי.
  • RESOURCE_EXHAUSTED – יותר מדי בקשות להרשמה או לביטול הרשמה נשלחו בפרק זמן קצר. ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential 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"},
    {},
  ]
}

יצירת טוקנים של רישום לטוקנים של APNs

באמצעות השיטה batchImport של שירות Instance ID, אפשר לייבא בכמות גדולה אסימוני APNs קיימים של iOS אל 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 : מזהה ה-Bundle של האפליקציה.
  • ‫sandbox : ערך בוליאני שמציין סביבת ארגז חול (TRUE) או סביבת ייצור (FALSE)
  • ‫apns_tokens : מערך של טוקנים של APN עבור מופעי האפליקציה שרוצים להוסיף או להסיר. מקסימום 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 server API מחזירות את קודי השגיאה הבאים של 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) – השירות לא זמין. צריך לנסות לשלוח שוב את הבקשה עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).