הפניה לשרת

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

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

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

 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. באמצעות קריאה לשירות מזהה המכונה בכתובת את נקודת הקצה (endpoint) הזו, ומספקת את אסימון המופע של האפליקציה כפי שמוצג:

 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"},
    {},
  ]
}

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

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