הפניה לשרת

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

• מידע נוסף על מופעים של אפליקציות לאמת את אסימוני האפליקציה או לקבל מידע נוסף על מופע האפליקציה שיצר את האסימון.
• יצירת מפות קשרים למופעי אפליקציות. יצירת קשרים בין מופעים של אפליקציות לבין ישויות.
• יצירת טוקנים של רישום לטוקנים של APNs. ‫API שמאפשר לייבא בכמות גדולה טוקנים קיימים של APNs ולמפות אותם לטוקנים תקפים של רישום ב-FCM.

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

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

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

באמצעות שיטות אצווה של שירות Instance ID, אפשר לבצע ניהול אצווה של מופעי אפליקציות. לדוגמה, אתם יכולים להוסיף או להסיר בבת אחת כמה מופעים של אפליקציות לנושא ב-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).