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

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

  • שם הנושא
  • תנאי
  • טוקן רישום מכשיר
  • שם קבוצת המכשירים (פרוטוקול בלבד)

אפשר לשלוח הודעות עם מטען ייעודי (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 יחד עם ספריות שרת של Admin 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)
}
init.go

C#‎

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

הזנת פרטי הכניסה באופן ידני

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

כדי לאמת חשבון שירות ולאשר לו גישה לשירותי 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"

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

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

אלא אם אתם משתמשים ב-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);
    });
  });
}
index.js

בדוגמה הזו, ספריית הלקוח של 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
messaging.py

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();
}
Messaging.java

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

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

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

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

node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}
index.js

Python

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

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;
FirebaseMessagingSnippets.java

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

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

  1. הפעלת ה-API: מוודאים ש-Firebase Cloud Messaging API מופעל בפרויקט השולח.
  2. יצירת חשבון שירות: יוצרים חשבון שירות בפרויקט של השולח.
  3. הענקת הרשאות: בפרויקט היעד, מעניקים לכתובת האימייל של חשבון השירות את התפקיד Firebase Cloud Messaging API Admin בדף IAM. כך חשבון השירות מהפרויקט השני יכול לשלוח הודעות לפרויקט היעד.
  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

אם הפעולה מצליחה, התגובה של HTTP v1 API היא אובייקט 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://cat.10515.net/1.jpg"
    }
  }
}

Run

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