שליחת הודעה באמצעות FCM HTTP v1 API

באמצעות FCM HTTP v1 API, אתם יכולים ליצור בקשות להודעות ולשלוח אותן ליעדים מהסוגים הבאים:

  • שם הנושא
  • תנאי
  • טוקן רישום מכשיר
  • שם קבוצת המכשירים (הוצא משימוש, יוסר ב-29 בספטמבר 2027)

אתם יכולים לשלוח הודעות עם מטען ייעודי (payload) של התראות שמורכב משדות מוגדרים מראש, מטען ייעודי של נתונים מהשדות שהגדרתם בעצמכם או הודעה שמכילה את שני סוגי המטענים הייעודיים. למידע נוסף, קראו את המאמר סוגי הודעות.

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

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

  • ‫Application Default Credentials‏ (ADC) של Google
  • קובץ JSON של חשבון שירות
  • אסימון גישה לטווח קצר מסוג OAuth 2.0 שנוצר מחשבון שירות

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

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

מתן פרטי כניסה באמצעות ADC

השירות Application Default Credentials‏ (ADC) של Google בודק את פרטי הכניסה בסדר הבא:

  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);

Python

default_app = firebase_admin.initialize_app()

Go

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 בכרטיסייה Settings > Service accounts.

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

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

  1. במסוף Firebase, נכנסים לכרטיסייה Settings > Service accounts.

  2. לוחצים על Generate New Private Key ואז על Generate Key כדי לאשר.

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

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

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

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

Linux או macOS

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

Windows

באמצעות PowerShell:

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

אחרי שתבצעו את הפעולות שלמעלה, תוכלו להשתמש בפרטי הכניסה של חשבון השירות כשאתם בודקים או מריצים את האפליקציה בסביבות שהן לא של Google, כי השירות Application Default Credentials ‏ (ADC) יוכל לקבוע באופן משתמע את פרטי הכניסה שלכם.

שימוש בפרטי כניסה כדי להנפיק אסימוני גישה

אם אתם לא משתמשים בFirebase 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.

Python

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
}

Python

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;

אישור חשבון שירות מפרויקט אחר

אתם יכולים לשלוח הודעות לפרויקט אחד, "פרויקט היעד", תוך שימוש באסימון OAuth 2.0 שנוצר מחשבון שירות בפרויקט אחר, "פרויקט השולח". כך אפשר לרכז את הניהול של חשבונות השירות בפרויקט אחד, ולשלוח הודעות בשם פרויקטים אחרים. כדי לעשות את זה, פועלים לפי השלבים הבאים:

  1. בפרויקט השולח, מוודאים שה-API של העברת הודעות בענן ב-Firebase מופעל. כדי לבדוק אם הוא מופעל במסוף Firebase, עוברים אל הגדרות > כללי. ואז לוחצים על הכרטיסייה העברת הודעות בענן.

  2. בפרויקט השולח, יוצרים חשבון שירות.

  3. בפרויקט היעד, מקצים את התפקיד אדמין של העברת הודעות בענן ב-Firebase API לכתובת האימייל של חשבון השירות. כדי לעשות את זה, נכנסים לדף IAM & Admin > IAM במסוף Google Cloud. התפקיד הזה מאפשר לחשבון השירות מפרויקט השולח לשלוח הודעות לפרויקט היעד.

  4. יוצרים אסימון גישה מסוג OAuth 2.0 לחשבון השירות בפרויקט השולח. כדי לעשות את זה, אתם יכולים להשתמש באחת מהאפשרויות הבאות:

    • הורדה של קובץ ה-JSON של מפתח חשבון השירות ושימוש בו.
    • שימוש ב-Workload Identity אם השירות פועל ב-Google Cloud.

  5. משתמשים בטוקן הגישה שקיבלתם בכותרת Authorization של בקשת השליחה. צריך לשלוח את הבקשה לנקודת הקצה של HTTP v1 בפרויקט היעד:

      POST https://fcm.googleapis.com/v1/TARGET_PROJECT_ID/messages:send

שליחת הודעות למכשירים ספציפיים

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

REST

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

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

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

פקודת cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "notification":{
     "title":"FCM Message",
     "body":"This is an FCM Message"
   },
   "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

אם הפעולה תצליח, תגובה מה-API של HTTP v1 תהיה אובייקט JSON שמכיל את מזהה ההודעה:

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

שליחת הודעת התראה לבדיקה באמצעות FCM HTTP v1 API

בקטע הזה מוסבר איך לשלוח הודעת התראה לבדיקה באמצעות FCM HTTP v1 API.

כתובת ה-URL של בקשת ה-HTTP

הבקשה מורכבת מ-HTTP POST ליעד שצוין (טוקן רישום, נושא או תנאי) בכתובת ה-URL הבאה:

POST https://fcm.googleapis.com/v1/projectId/messages:send

דוגמה לקובץ JSON של בקשת HTTP מלאה

הנה דוגמה מלאה שמראה איך לפרסם התראה בבקשת HTTP POST:

{
  "message": {
    "token": REGISTRATION_TOKEN,
    "notification": {
      "title": "FCM API test",
      "body": "This is the body of the notification.",
      "image": "https://firebase.google.com/static/images/products/cloud-messaging/cloud-messaging-hero_1x.png"
    }
  }
}

הרצה

לוחצים על Run כדי לנסות את הדוגמה ב-API Explorer.