הפניה לשרת

הטמעת השרת היא אופציונלית. כדאי להשתמש בשירות מזהה המכונה אם רוצים לבצע את הפעולות הבאות:

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

על מנת לקבל מידע על מופע של אפליקציה, צריך לקרוא לשירות מזהה המכונה בנקודת הקצה הזאת, ולספק את האסימון של מופע האפליקציה, באופן הבא:

 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"}
    }
  }
}

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

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, צריך לבצע קריאה לשירות מזהה המכונה בנקודת הקצה הזו, ולספק את האסימונים של מופע האפליקציה בגוף ה-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 — מספר נושאים גדול מדי לכל מופע של האפליקציה.
  • resources_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"},
    {},
  ]
}

יצירת אסימוני רישום לאסימוני APN

באמצעות השיטה batchImport של שירות מזהה המכונה, אפשר לייבא כמות גדולה של אסימוני APN של iOS אל Firebase Cloud Messaging, ולמפות אותם לאסימוני רישום חוקיים. קוראים לשירות מזהה המכונה בנקודת הקצה הזו, ומספקת רשימה של אסימוני ה-APN בגוף ה-JSON:

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

גוף התגובה מכיל מערך של אסימוני רישום של מזהה מכונה שמוכנים לשימוש לשליחת הודעות FCM אל אסימון המכשיר התואם של ה-APN.

פרמטרים

  • Authorization: Bearer <access_token>. יש להגדיר את הפרמטר הזה בכותרת. יש להוסיף אסימון OAuth2 לטווח קצר כערך של הכותרת Authorization. מידע נוסף על קבלת האסימון הזה זמין במאמר מתן פרטי כניסה באופן ידני.
  • access_token_auth: true. יש להגדיר את הפרמטר הזה בכותרת.
  • application : מזהה החבילה של האפליקציה.
  • sandbox : ערך בוליאני לציון סביבת Sandbox (TRUE) או סביבת ייצור (FALSE)
  • apns_tokens : המערך של אסימוני ה-APN עבור מופעי האפליקציה שרוצים להוסיף או להסיר. עד 100 אסימונים לבקשה.

תוצאות

לאחר הצלחה, הקריאה מחזירה את סטטוס HTTP 200 וגוף התוצאה של JSON. לכל אסימון APN שצוין בבקשה, רשימת התוצאות כוללת:

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