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

אפשר לראות את כל חשבונות השירות של פרויקט Firebase בכרטיסייה Settings (הגדרות) > Service accounts (חשבונות שירות).

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

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

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

  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 Cloud Messaging API' לכתובת האימייל של חשבון השירות. כדי לעשות את זה, נכנסים לדף IAM בקטע IAM & Admin במסוף 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

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

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