הפניה לשרת

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

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

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

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

ניהול מפות של קשרי גומלין עבור מופעי אפליקציה מרובים

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

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

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