Catch up on everthing we announced at this year's Firebase Summit. Learn more

מאשר לשלוח בקשות

בקשות שנשלחות ל-FCM משרת האפליקציה או מהסביבה המהימנה שלך חייבות להיות מאושרות. שים לב להבדלים החשובים האלה בין הרשאת HTTP מדור קודם ל-HTTP v1 API:

  • FCM HTTP v1 API מאשר בקשות עם אסימון גישה OAuth 2.0 קצר מועד. כדי להטביע את האסימון הזה, אתה יכול להשתמש באישורי ברירת המחדל של יישומי Google (בסביבות שרתים של Google) ו/או להשיג באופן ידני את האישורים הנדרשים מקובץ מפתח פרטי JSON שנוצר עבור חשבון שירות. אם אתה משתמש ב-SDK של Firebase Admin כדי לשלוח הודעות, הספרייה מטפלת באסימון עבורך.
  • הפרוטוקולים מדור קודם יכולים להשתמש רק במפתחות API ארוכי חיים המתקבלים ממסוף Firebase.

אשר בקשות שליחת HTTP v1

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

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

אם היישום שלך פועל על מנוע מחשוב, Google Kubernetes מנוע, App Engine, או פונקציות ענן (כולל פונקציות ענן עבור 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 חשבונות השירות , שבו ניתן להשתמש כדי לקרוא APIs שרת 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.

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

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

שימוש באישורי Firebase שלך יחד עם ספריית מחבר גוגל עבור השפה המועדפת עליך לאחזר גישת 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 = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token

Java

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  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 " + getAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;

אשר בקשות שליחת פרוטוקול מדור קודם

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

העבר מפתחות שרת מדור קודם

החל ממרץ 2020, FCM הפסיקה ליצור מפתחות שרת מדור קודם. מפתחות שרת הישן קיימות תמשכנה לעבוד, אבל אנחנו ממליצים במקום להשתמש בגרסה החדשה יותר של מפתח שרת שכותרתו מפתח קונסולת Firebase .

אם אתה רוצה למחוק מפתח שרת הישן קיים, אתה יכול לעשות זאת Console של Google Cloud .

אשר בקשות HTTP

בקשת הודעה מורכבת משני חלקים: כותרת ה-HTTP וגוף ה-HTTP. כותרת ה-HTTP חייבת להכיל את הכותרות הבאות:

  • Authorization : key = YOUR_SERVER_KEY
    לוודא שזהו המפתח השרת, שערכם זמין Cloud Messaging הלשונית של חלונית הגדרות קונסולת Firebase. מפתחות אנדרואיד, פלטפורמת אפל ומפתחות הדפדפן נדחים על ידי FCM.
  • Content-Type : application/json עבור JSON; application/x-www-form-urlencoded;charset=UTF-8 עבור טקסט רגיל.
    אם Content-Type מושמט, בפורמט ההנחה היא להיות טקסט רגיל.

לדוגמה:

Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
  "data" : {
    ...
  },
}

ראה בקשות שלחו Build לפרטים מלאים על יצירת בקשות לשלוח. הפניה Legacy HTTP Protocol מספק רשימה של כל הפרמטרים בהודעה יכול להכיל.

בדיקת תקפות מפתח שרת

אם אתה מקבל שגיאות אימות בעת שליחת הודעות, בדוק את תקפות מפתח השרת שלך. לדוגמה, ב-Linux, הפעל את הפקודה הבאה:

api_key=YOUR_SERVER_KEY

curl --header "Authorization: key=$api_key" \
     --header Content-Type:"application/json" \
     https://fcm.googleapis.com/fcm/send \
     -d "{\"registration_ids\":[\"ABC\"]}"

אם אתה מקבל קוד סטטוס 401 HTTP, מפתח השרת שלך אינו חוקי.

אשר חיבור XMPP

עם XMPP, אתה יכול לשמור על חיבור מתמשך, אסינכרוני, דו-כיווני לשרתי FCM. ניתן להשתמש בחיבור כדי לשלוח ולקבל הודעות בין השרת שלך לבין המכשירים המחוברים ל-FCM של המשתמשים שלך.

אתה יכול להשתמש ברוב ספריות XMPP כדי לנהל חיבור ארוך טווח ל-FCM. XMPP נקודות הקצה רץ לעבר fcm-xmpp.googleapis.com:5235 . כאשר נבדק תפקוד עם משתמשים שאינם ייצור, כדאי במקום להתחבר לשרת טרום ההפקה fcm-xmpp.googleapis.com:5236 (לב הנמל שונים).

בדיקות רגילות בקדם-ייצור (סביבה קטנה יותר שבה פועלות ה-FCM ה-builds העדכניים ביותר) מועילות לבידוד משתמשים אמיתיים מקוד הבדיקה. מכשירי בדיקת קוד בדיקת התחברות fcm-xmpp.googleapis.com:5236 צריכים להשתמש זיהוי שולח FCM שונה כדי למנוע סיכונים כלשהם של שליחת הודעות מבחן למשתמשי ייצור או שליחת הודעות upstream מתנועת ייצור בחיבורי מבחן.

לחיבור יש שתי דרישות חשובות:

  • עליך ליזום חיבור Transport Layer Security (TLS). הערה כי FCM אינו תומך כרגע הארכה STARTTLS .
  • FCM דורש מנגנון אימות PLAIN SASL באמצעות <your_FCM_Sender_Id>@fcm.googleapis.com (FCM זיהוי השולח ) ואת המפתח שרת כסיסמה. ערכים אלה זמינים Cloud Messaging הלשונית של חלונית הגדרות קונסולת Firebase.

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

הקטעים הבאים ממחישים כיצד לבצע אימות והרשאה עבור חיבור XMPP ל-FCM.

שרת XMPP

שרת XMPP מבקש חיבור ל-FCM

<stream:stream to="fcm.googleapis.com"
        version="1.0" xmlns="jabber:client"
        xmlns:stream="http://etherx.jabber.org/streams">

FCM

FCM פותחת את הקשר ומבקשת מנגנון אימות, כולל PLAIN השיטה.

<stream:features>
  <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl">
    <mechanism>X-OAUTH2</mechanism>
    <mechanism>X-GOOGLE-TOKEN</mechanism>
    <mechanism>PLAIN</mechanism>
  </mechanisms>
</stream:features>

שרת XMPP

שרת XMPP חייב להשיב באמצעות PLAIN שיטת אימות, מתן שרת המפתח מן Cloud Messaging הלשונית של חלונית הגדרות קונסולת Firebase.

<auth mechanism="PLAIN"
xmlns="urn:ietf:params:xml:ns:xmpp-sasl">MTI2MjAwMzQ3OTMzQHByb2plY3RzLmdjbS5hb
mFTeUIzcmNaTmtmbnFLZEZiOW1oekNCaVlwT1JEQTJKV1d0dw==</auth>

FCM

<success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>

שרת XMPP

<stream:stream to="fcm.googleapis.com"
        version="1.0" xmlns="jabber:client"
        xmlns:stream="http://etherx.jabber.org/streams">

FCM

<stream:features>
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"/>
  <session xmlns="urn:ietf:params:xml:ns:xmpp-session"/>
</stream:features>

שרת XMPP

<iq type="set">
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"></bind>
</iq>

FCM

<iq type="result">
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind">
    <jid>SENDER_ID@fcm.googleapis.com/RESOURCE</jid>
  </bind>
</iq>

הערה: FCM אינו משתמש במשאב המחובר בזמן ניתוב הודעות.

ראה בקשות שלחו Build לפרטים מלאים על יצירת בקשות לשלוח. פניית Legacy XMPP הפרוטוקול מספקת רשימה של כול הפרמטרים בהודעה יכולה להכיל.