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

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

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

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

בהתאם לפרטים של סביבת השרת שלך, השתמש בשילוב של אסטרטגיות אלה כדי לאשר בקשות שרת לשירותי 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.

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

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

השתמש באישורי 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;

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

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

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

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

אם ברצונך למחוק מפתח שרת מדור קודם, תוכל לעשות זאת במסוף 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" : {
    ...
  },
}

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

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

אם אתה מקבל שגיאות אימות בעת שליחת הודעות, בדוק את תקפות מפתח השרת שלך. לדוגמה, ב-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 אחר כדי למנוע סיכונים כלשהם של שליחת הודעות בדיקה למשתמשי ייצור או שליחת הודעות במעלה הזרם מתעבורת הייצור דרך חיבורי בדיקה.

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

  • עליך ליזום חיבור Transport Layer Security (TLS). שים לב ש-FCM לא תומך כרגע בתוסף STARTTLS .
  • FCM דורש מנגנון אימות SASL PLAIN באמצעות <your_FCM_Sender_Id>@fcm.googleapis.com ( מזהה שולח FCM ) ומפתח השרת כסיסמה. ערכים אלה זמינים בכרטיסייה הודעות ענן בחלונית ההגדרות של מסוף 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 אינו משתמש במשאב המחובר בזמן ניתוב הודעות.

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