מעבר מממשקי API מדור קודם של FCM ל-HTTP v1

אפליקציות שמשתמשות בגרסאות קודמות של FCM API ל-HTTP ול-XMPP צריכות לעבור ל-HTTP v1 API בהקדם האפשרי. הוצאנו משימוש את האפשרות לשלוח הודעות (כולל הודעות מהלקוח לשרת) באמצעות ממשקי ה-API האלה ב-20 ביוני 2023, וההשבתה תתחיל ב-22 ביולי 2024.

מידע נוסף על התכונות הספציפיות שמושפעות

בנוסף לתמיכה השוטפת ולתכונות החדשות, ל-HTTP v1 API יש את היתרונות הבאים בהשוואה לממשקי ה-API מהדור הקודם:

  • אבטחה משופרת באמצעות אסימוני גישה ב-HTTP v1 API נעשה שימוש באסימוני גישה לטווח קצר בהתאם למודל האבטחה של OAuth2. אם טוקן גישה הופך לגלוי לכולם, אפשר להשתמש בו באופן זדוני רק למשך שעה בערך לפני שהוא יפוג. אסימוני רענון לא מועברים בתדירות גבוהה כמו מפתחות האבטחה שמשמשים ב-API מדור קודם, ולכן הסיכוי שהם ייפרצו נמוך בהרבה.

  • התאמה אישית יעילה יותר של הודעות בפלטפורמות שונות ב-API של HTTP v1, גוף ההודעה כולל מפתחות משותפים שמועברים לכל המופעים המטורגטים, וגם מפתחות ספציפיים לפלטפורמה שמאפשרים להתאים אישית את ההודעה בפלטפורמות שונות. כך אפשר ליצור 'שינויים' ששולחים מטען ייעודי (payload) שונה במקצת לפלטפורמות לקוח שונות בהודעה אחת.

  • יותר גמיש ומוכן לעתיד עבור גרסאות חדשות של פלטפורמות לקוח ממשק ה-API של HTTP v1 תומך באופן מלא באפשרויות העברת הודעות שזמינות בפלטפורמות של Apple, ב-Android ובאינטרנט. לכל פלטפורמה יש בלוק מוגדר משלה במטען הייעודי (payload) של JSON, ולכן FCM יכול להרחיב את ה-API לגרסאות חדשות ולפלטפורמות חדשות לפי הצורך.

עדכון נקודת הקצה של השרת

כתובת ה-URL של נקודת הקצה של HTTP v1 API שונה מכתובת נקודת הקצה הקודמת בדרכים הבאות:

  • הוא מנוהל באמצעות בקרת גרסאות, עם /v1 בנתיב.
  • הנתיב מכיל את מזהה הפרויקט של פרויקט Firebase של האפליקציה, בפורמט /projects/myproject-ID/. המזהה הזה זמין בכרטיסייה הגדרות כלליות של הפרויקט במסוף Firebase.
  • היא מציינת במפורש את שיטת send כ-:send.

כדי לעדכן את נקודת הקצה של השרת ל-HTTP v1, מוסיפים את הרכיבים האלה לנקודת הקצה בכותרת של בקשות השליחה.

בקשות HTTP לפני

POST https://fcm.googleapis.com/fcm/send

בקשות XMPP לפני

הודעות XMPP מדור קודם נשלחות דרך חיבור לנקודת הקצה הבאה:

fcm-xmpp.googleapis.com:5235

אחרי

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

עדכון ההרשאה של בקשות שליחה

במקום מחרוזת מפתח השרת ששימשה בבקשות מדור קודם, בקשות HTTP v1 לשליחה דורשות אסימון גישה מסוג OAuth 2.0. אם אתם משתמשים ב-Admin SDK כדי לשלוח הודעות, הספרייה מטפלת באסימון בשבילכם. אם אתם משתמשים בפרוטוקול גולמי, צריך לקבל את האסימון כמו שמתואר בקטע הזה ולהוסיף אותו לכותרת כ-Authorization: Bearer <valid Oauth 2.0 token>.

לפני

Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA

אחרי

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

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

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

כדי לאשר גישה ל-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

עדכון מטען הייעודי (payload) של בקשות שליחה

ב-FCM HTTP v1 יש שינוי משמעותי במבנה של מטען הנתונים של הודעת ה-JSON. השינויים האלה נועדו בעיקר כדי להבטיח שההודעות יטופלו בצורה נכונה כשהן יתקבלו בפלטפורמות שונות של לקוחות. בנוסף, השינויים האלה מאפשרים לכם גמישות נוספת בהתאמה אישית של שדות ההודעה או בביטול שלהם בכל פלטפורמה.

בנוסף לבדיקת הדוגמאות שבקטע הזה, מומלץ לעיין במאמר התאמה אישית של הודעה בפלטפורמות שונות ובחומר העזר בנושא API כדי להכיר את HTTP v1.

דוגמה: הודעה פשוטה

הנה השוואה בין מטען ייעודי (payload) פשוט מאוד של התראה – שמכיל רק את השדות title, body ו-data – שממחישה את ההבדלים הבסיסיים בין מטען ייעודי (payload) מדור קודם לבין מטען ייעודי (payload) של HTTP v1.

לפני

{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available."
  },
  "data": {
    "story_id": "story_12345"
  }
}

אחרי

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    }
  }
}

דוגמה: נתוני JSON בתצוגת עץ

בשונה מ-API מדור קודם להעברת הודעות, API מדור ראשון ל-HTTP לא תומך בערכי JSON מוטמעים בשדה data. צריך להמיר מ-JSON למחרוזת.

לפני

{
  ...
  "data": {
    "keysandvalues": {"key1": "value1", "key2": 123}
  }
}

אחרי

{
  "message": {
   ...
    "data": {
      "keysandvalues": "{\"key1\": \"value1\", \"key2\": 123}"
    }
  }
}

דוגמה: טירגוט של כמה פלטפורמות

כדי להפעיל טירגוט לכמה פלטפורמות, ה-API מדור קודם ביצע החלפות בקצה העורפי. לעומת זאת, ב-HTTP v1 יש בלוקים של מפתחות שספציפיים לפלטפורמה, כך שההבדלים בין הפלטפורמות גלויים למפתחים. כך תוכלו לטרגט כמה פלטפורמות תמיד באמצעות בקשה אחת, כמו בדוגמה הבאה.

לפני

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

אחרי

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

דוגמה: התאמה אישית באמצעות החלפות של פלטפורמה

בנוסף לפישוט המיקוד להודעות בפלטפורמות שונות, HTTP v1 API מאפשר גמישות בהתאמה אישית של הודעות לכל פלטפורמה.

לפני

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "Check out the Top Story.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

אחרי

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY",
        "body": "Check out the Top Story"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

דוגמה: טירגוט מכשירים ספציפיים

כדי לטרגט מכשירים ספציפיים באמצעות HTTP v1 API, צריך לספק את טוקן הרישום הנוכחי של המכשיר במפתח token במקום במפתח to.

לפני

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

אחרי

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

דוגמאות נוספות ומידע על FCM HTTP v1 API: