העבר ממשקי API מדור קודם של FCM ל-HTTP v1

אפליקציות המשתמשות בממשקי ה-API מדור קודם של FCM עבור HTTP ו-XMPP צריכות לעבור אל ה-API של HTTP v1 בהזדמנות המוקדמת ביותר. שליחת הודעות (כולל הודעות במעלה הזרם) עם ממשקי API אלה הוצאה משימוש ב-20 ביוני 2023, והיא תוסר ביוני 2024 .

בנוסף לתמיכה מתמשכת ותכונות חדשות, ל-API של HTTP v1 יש את היתרונות הבאים על פני ממשקי ה-API מדור קודם:

  • אבטחה טובה יותר באמצעות אסימוני גישה ה-API של HTTP v1 משתמש באסימוני גישה קצרי מועד בהתאם למודל האבטחה OAuth2. במקרה שאסימון גישה הופך לציבורי, ניתן להשתמש בו בזדון רק כשעה לפני שפג תוקפו. אסימוני רענון אינם מועברים באותה תדירות כמו מפתחות האבטחה המשמשים ב-API מדור קודם, כך שיש סיכוי נמוך יותר שהם ייתפסו.

  • התאמה אישית יעילה יותר של הודעות על פני פלטפורמות עבור גוף ההודעה, ל-API של HTTP v1 יש מפתחות נפוצים המגיעים לכל המופעים הממוקדים, בתוספת מפתחות ספציפיים לפלטפורמה המאפשרים לך להתאים אישית את המסר בין הפלטפורמות. זה מאפשר לך ליצור "עקיפות" ששולחות עומסים שונים במקצת לפלטפורמות לקוח שונות בהודעה אחת.

  • ניתן להרחבה וחסינות יותר לעתיד עבור גרסאות חדשות של פלטפורמת לקוח ה-API של HTTP v1 תומך באופן מלא באפשרויות העברת הודעות הזמינות בפלטפורמות אפל, אנדרואיד ואינטרנט. מכיוון שלכל פלטפורמה יש בלוק מוגדר משלה במטען ה-JSON, FCM יכול להרחיב את ה-API לגרסאות חדשות ולפלטפורמות חדשות לפי הצורך.

עדכן את נקודת הקצה של השרת

כתובת האתר של נקודת הקצה עבור ה-API של HTTP v1 שונה מנקודת הקצה מדור קודם בדרכים הבאות:

  • זה מנוסח, עם /v1 בנתיב.
  • הנתיב מכיל את מזהה הפרויקט של פרויקט Firebase עבור האפליקציה שלך, בפורמט /projects/myproject-ID/ . מזהה זה זמין בכרטיסייה הגדרות פרויקט כלליות של מסוף Firebase.
  • זה מציין במפורש את שיטת השליחה ציין את שיטת send כ- :send .

כדי לעדכן את נקודת הקצה של השרת עבור HTTP v1, הוסף אלמנטים אלה לנקודת הקצה בכותרת של בקשות השליחה שלך.

בקשות HTTP לפני

POST https://fcm.googleapis.com/fcm/send

בקשות XMPP לפני

הודעות XMPP מדור קודם נשלחות דרך חיבור לנקודת הקצה הבאה:

fcm-xmpp.googleapis.com:5235

לאחר

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

עדכון הרשאה של בקשות שליחה

במקום מחרוזת מפתח השרת המשמשת בבקשות מדור קודם, בקשות שליחת HTTP v1 דורשות אסימון גישה של OAuth 2.0. אם אתה משתמש ב-Admin SDK כדי לשלוח הודעות, הספרייה מטפלת באסימון עבורך. אם אתה משתמש בפרוטוקול גולמי, השג את האסימון כמתואר בסעיף זה והוסף אותו לכותרת בתור Authorization: Bearer <valid Oauth 2.0 token> .

לפני

Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA

לאחר

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

בהתאם לפרטים של סביבת השרת שלך, השתמש בשילוב של אסטרטגיות אלה כדי לאשר בקשות שרת לשירותי Firebase:

  • אישורי ברירת המחדל של Google Application (ADC)
  • קובץ JSON של חשבון שירות
  • אסימון גישה ל-OAuth 2.0 קצר מועד הנגזר מחשבון שירות

אם האפליקציה שלך פועלת ב-Compute Engine, Google Kubernetes Engine, App Engine או Cloud Functions (כולל Cloud Functions for Firebase), השתמש באישורי ברירת המחדל של Application (ADC). ADC משתמש בחשבון שירות ברירת המחדל הקיים שלך כדי להשיג אישורים כדי לאשר בקשות, ו-ADC מאפשר בדיקה מקומית גמישה באמצעות משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS . לאוטומציה המלאה ביותר של זרימת ההרשאה, השתמש ב-ADC יחד עם ספריות שרתי Admin SDK.

אם האפליקציה שלך פועלת על סביבת שרת שאינה של Google , יהיה עליך להוריד קובץ JSON של חשבון שירות מפרויקט Firebase שלך. כל עוד יש לך גישה למערכת קבצים המכילה את קובץ המפתח הפרטי, תוכל להשתמש במשתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS כדי לאשר בקשות עם אישורים אלה שהושגו באופן ידני. אם חסרה לך גישה כזו לקובץ, עליך להתייחס לקובץ חשבון השירות בקוד שלך - מה שצריך להיעשות בזהירות רבה בגלל הסיכון לחשיפת האישורים שלך.

ספק אישורים באמצעות ADC

אישורי ברירת המחדל של Google Application (ADC) בודק את האישורים שלך בסדר הבא:

  1. ADC בודק אם משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS מוגדר. אם המשתנה מוגדר, ADC משתמש בקובץ חשבון השירות שאליו המשתנה מצביע.

  2. אם משתנה הסביבה לא מוגדר, ADC משתמש בחשבון שירות ברירת המחדל ש-Compute Engine, Google Kubernetes Engine, App Engine ו-Cloud Functions מספקים עבור יישומים הפועלים בשירותים אלה.

  3. אם ADC לא יכול להשתמש באף אחד מהאישורים שלעיל, המערכת זורקת שגיאה.

דוגמה הבאה של קוד Admin SDK ממחישה אסטרטגיה זו. הדוגמה אינה מציינת במפורש את אישורי היישום. עם זאת, ADC מסוגלת למצוא באופן מרומז את האישורים כל עוד משתנה הסביבה מוגדר, או כל עוד האפליקציה פועלת על Compute Engine, Google Kubernetes Engine, App Engine או Cloud Functions.

Node.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

פִּיתוֹן

default_app = firebase_admin.initialize_app()

ללכת

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

ספק אישורים באופן ידני

פרויקטים של Firebase תומכים בחשבונות שירות של Google , שבהם אתה יכול להשתמש כדי לקרוא לממשקי API של שרת Firebase משרת האפליקציות או מהסביבה המהימנה שלך. אם אתה מפתח קוד באופן מקומי או פורס את היישום שלך במקום, אתה יכול להשתמש באישורים שהושגו דרך חשבון שירות זה כדי לאשר בקשות שרת.

כדי לאמת חשבון שירות ולהעניק לו הרשאה לגשת לשירותי Firebase, עליך ליצור קובץ מפתח פרטי בפורמט JSON.

כדי ליצור קובץ מפתח פרטי עבור חשבון השירות שלך:

  1. במסוף Firebase, פתח את הגדרות > חשבונות שירות .

  2. לחץ על צור מפתח פרטי חדש ולאחר מכן אשר על ידי לחיצה על צור מפתח .

  3. אחסן בצורה מאובטחת את קובץ ה-JSON המכיל את המפתח.

בעת הרשאה באמצעות חשבון שירות, יש לך שתי אפשרויות למתן האישורים ליישום שלך. אתה יכול להגדיר את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS , או שאתה יכול להעביר במפורש את הנתיב למפתח חשבון השירות בקוד. האפשרות הראשונה מאובטחת יותר ומומלצת בחום.

כדי להגדיר את משתנה הסביבה:

הגדר את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS לנתיב הקובץ של קובץ ה-JSON שמכיל את מפתח חשבון השירות שלך. משתנה זה חל רק על הפעלת המעטפת הנוכחית שלך, אז אם אתה פותח הפעלה חדשה, הגדר שוב את המשתנה.

לינוקס או macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

חלונות

עם PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

לאחר השלמת השלבים שלעיל, אישורי ברירת המחדל של יישומים (ADC) מסוגלים לקבוע באופן מרומז את האישורים שלך, מה שמאפשר לך להשתמש באישורי חשבון שירות בעת בדיקה או הפעלה בסביבות שאינן של Google.

השתמש באישורים כדי להטביע אסימוני גישה

השתמש באישורי Firebase שלך ​​יחד עם ספריית האימות של Google עבור השפה המועדפת עליך כדי לאחזר אסימון גישה ל-OAuth 2.0 קצר מועד:

node.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    const key = require('../placeholders/service-account.json');
    const jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}

בדוגמה זו, ספריית הלקוח של Google API מאמתת את הבקשה באמצעות אסימון אינטרנט של JSON, או JWT. למידע נוסף, ראה אסימוני אינטרנט של JSON .

פִּיתוֹן

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = service_account.Credentials.from_service_account_file(
    'service-account.json', scopes=SCOPES)
  request = google.auth.transport.requests.Request()
  credentials.refresh(request)
  return credentials.token

Java

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refresh();
  return googleCredentials.getAccessToken().getTokenValue();
}

לאחר שפג תוקפו של אסימון הגישה שלך, שיטת רענון האסימון נקראת באופן אוטומטי כדי לאחזר אסימון גישה מעודכן.

כדי לאשר גישה ל-FCM, בקש את ההיקף https://www.googleapis.com/auth/firebase.messaging .

כדי להוסיף את אסימון הגישה לכותרת בקשת HTTP:

הוסף את האסימון כערך של כותרת Authorization בפורמט Authorization: Bearer <access_token> :

node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}

פִּיתוֹן

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}

Java

URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getServiceAccountAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;

עדכן את המטען של בקשות השליחה

FCM HTTP v1 מציג שינוי משמעותי במבנה של מטען הודעות JSON. בעיקר, שינויים אלה מבטיחים שהודעות יטופלו בצורה נכונה כשהן מתקבלות בפלטפורמות לקוח שונות; בנוסף, השינויים מעניקים לך גמישות נוספת להתאמה אישית או "לעקוף" שדות הודעות לכל פלטפורמה.

בנוסף לבדיקת הדוגמאות בסעיף זה, ראה התאמה אישית של הודעה בין פלטפורמות וסקור את ההתייחסות ל-API כדי להכיר את HTTP v1.

דוגמה: הודעת התראה פשוטה

הנה השוואה של מטען הודעות פשוט מאוד - המכיל שדות title , body data בלבד - המדגים את ההבדלים הבסיסיים במטעני מדור קודם ו-HTTP v1.

לפני

{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available."
  },
  "data": {
    "story_id": "story_12345"
  }
}

לאחר

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    }
  }
}

דוגמה: מיקוד לפלטפורמות מרובות

כדי לאפשר מיקוד לפלטפורמות מרובות, ה-API מדור קודם ביצע דרישות ב-backend. לעומת זאת, HTTP v1 מספק בלוקים ספציפיים לפלטפורמה של מפתחות שעושים כל הבדל בין פלטפורמות למפורש וגלוי למפתח. זה מאפשר לך למקד לפלטפורמות מרובות תמיד עם בקשה אחת, כפי שמוצג בדוגמה הבאה.

לפני

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

לאחר

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

דוגמה: התאמה אישית עם עקיפות פלטפורמה

בנוסף לפישוט מיקוד חוצה פלטפורמות של הודעות, ה-API של HTTP v1 מספק גמישות להתאמה אישית של הודעות לכל פלטפורמה.

לפני

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "Check out the Top Story.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

לאחר

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY",
        "body": "Check out the Top Story"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

דוגמה: מיקוד למכשירים ספציפיים

כדי למקד למכשירים ספציפיים עם ה-API של HTTP v1, ספק את אסימון הרישום הנוכחי של המכשיר במפתח token במקום במפתח to .

לפני

  { "notification": {
      "body": "This is an FCM notification message!",
      "time": "FCM Message"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }

לאחר

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

לדוגמאות נוספות ומידע על FCM HTTP v1 API, ראה את הפרטים הבאים: