從舊版 FCM API 遷移至 HTTP v1

如果應用程式針對 HTTP 和 XMPP 使用已淘汰的 FCM 舊版 API,應盡早改用 HTTP v1 API。透過這些 API 傳送訊息 (包括上游訊息) 的功能已於 2023 年 6 月 20 日淘汰,將於 2024 年 6 月 21 日移除

進一步瞭解受影響的特定功能

除了持續支援及推出新功能外,HTTP v1 API 也與舊版 API 相比有下列優點:

  • 透過存取權杖提升安全性:HTTP v1 API 會根據 OAuth2 安全性模型使用短期存取權杖。在存取權杖公開的情況下,您只能惡意使用存取權杖一小時左右。更新權杖的傳送頻率不與舊版 API 中使用的安全金鑰相同,因此較難擷取這些權杖。

  • 提高跨平台訊息自訂效率這可讓您建立「覆寫」,在單一訊息中將稍微不同的酬載傳送至不同的用戶端平台。

  • 針對新的用戶端平台版本提供更可擴充且符合未來趨勢 HTTP v1 API 全面支援 Apple 平台、Android 和網頁版上的訊息傳遞選項。由於每個平台在 JSON 酬載中都有自己定義的區塊,因此 FCM 可以視需要將 API 擴充到新版本和新平台。

更新伺服器端點

HTTP v1 API 的端點網址與舊版端點有以下差異:

  • 此為版本編號,且路徑包含 /v1
  • 路徑中包含應用程式的 Firebase 專案 ID,格式為 /projects/myproject-ID/。您可以在 Firebase 控制台的「一般專案設定」分頁中找到這個 ID。
  • 這會明確將 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 服務發出的伺服器要求:

  • Google 應用程式預設憑證 (ADC)
  • 服務帳戶 JSON 檔案
  • 從服務帳戶衍生的短期 OAuth 2.0 存取權杖

如果您的應用程式是在 Compute Engine、Google Kubernetes Engine、App Engine 或 Cloud Functions 上執行 (包括 Cloud Functions for Firebase),請使用應用程式預設憑證 (ADC)。ADC 會使用您現有的預設服務帳戶取得憑證來授權要求,而 ADC 則透過環境變數 GOOGLE_APPLICATION_CREDENTIALS 啟用彈性的本機測試。如要徹底自動化授權流程,請搭配使用 ADC 與 Admin SDK 伺服器程式庫。

如果您的應用程式是在非 Google 伺服器環境中執行,您必須從 Firebase 專案下載服務帳戶 JSON 檔案。只要您能存取包含私密金鑰檔案的檔案系統,就可以使用環境變數 GOOGLE_APPLICATION_CREDENTIALS,以這些手動取得的憑證來授權要求。如果您無法存取這類檔案,則必須在程式碼中參照服務帳戶檔案。這項操作應謹慎處理,有可能導致憑證外洩。

使用 ADC 提供憑證

Google 應用程式預設憑證 (ADC) 會按照下列順序檢查您的憑證:

  1. ADC 會檢查是否已設定環境變數 GOOGLE_APPLICATION_CREDENTIALS。如果已設定變數,ADC 就會使用該變數指向的服務帳戶檔案。

  2. 如未設定環境變數,ADC 就會使用 Compute Engine、Google Kubernetes Engine、App Engine 和 Cloud Functions 為在這些服務中執行的應用程式提供的預設服務帳戶。

  3. 如果 ADC 無法使用上述任一憑證,系統會擲回錯誤。

以下 Admin SDK 程式碼範例說明這項策略。這個範例並未明確指定應用程式憑證,但是,只要已設定環境變數,或只要應用程式是在 Compute Engine、Google Kubernetes Engine、App Engine 或 Cloud Functions 上執行,ADC 就能以隱含方式找到憑證。

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 伺服器 API。如果您在本機開發程式碼,或是在內部部署應用程式,您可以使用透過這個服務帳戶取得的憑證來授權伺服器要求。

如要驗證服務帳戶,並授權該帳戶存取 Firebase 服務,您必須產生 JSON 格式的私密金鑰檔案。

如何產生服務帳戶的私密金鑰檔案:

  1. 在 Firebase 控制台中,依序開啟「Settings」>「Service Accounts」(服務帳戶)

  2. 按一下「產生新私密金鑰」,然後按一下「產生金鑰」加以確認。

  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"

完成上述步驟後,應用程式預設憑證 (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);
    });
  });
}

在這個範例中,Google API 用戶端程式庫會使用 JSON Web Token 或 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;

更新傳送要求的酬載

FCM HTTP v1 在建構 JSON 訊息酬載的結構方面發生了重大異動。主要來說,這些變更可確保在不同用戶端平台收到訊息時,都能正確處理訊息;此外,這些變更可讓您更靈活地自訂或「覆寫」各平台的訊息欄位。

除了查看本節中的範例之外,請參閱跨平台自訂訊息API 參考資料,熟悉 HTTP v1。

範例:簡單通知訊息

以下比較非常簡單的通知酬載 (僅包含 titlebodydata 欄位),說明舊版和 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"
    }
  }
}

範例:指定多個平台

為了啟用多平台指定功能,舊版 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!",
      "time": "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 的範例和資訊,請參閱以下內容: