הפניה לשרת

הטמעה בשרת היא אופציונלית. כדאי להשתמש בשירות 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 – projectId עם הרשאה לשלוח לאסימון.
  • 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 – מספר נושאים מוגזם לכל מכונה של אפליקציה.
  • 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 של שירות מזהה המכונה, אפשר לייבא בכמות גדולה אסימונים קיימים של 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 : מזהה החבילה של האפליקציה.
  • 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"
        },
     ]
  }

תגובות שגיאה

קריאות ל-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).