授權傳送要求

從應用程式伺服器或受信任環境傳送至 FCM 的要求必須經過授權。請注意，已淘汰的舊版 HTTP API 與 HTTP v1 API 授權之間存在以下重要差異：

  • FCM HTTP v1 API 會使用短效 OAuth 2.0 存取權憑證授權要求。如要鑄造此權杖，您可以使用 Google 應用程式預設憑證 (在 Google 伺服器環境中)，以及/或者手動從為服務帳戶產生的 JSON 私密金鑰檔案中取得必要憑證。如果您使用 Firebase Admin SDK 傳送訊息，程式庫會為您處理權杖。
  • 已淘汰的舊版通訊協定只能使用從 Firebase 控制台取得的長效 API 金鑰。

授權 HTTP v1 傳送要求

視伺服器環境的詳細資料而定，請結合下列策略，授權伺服器要求存取 Firebase 服務：

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

如果應用程式在 Compute Engine、Google Kubernetes Engine、App Engine 或 Cloud Functions (包括 Cloud Functions for Firebase) 上執行，請使用應用程式預設憑證 (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)
}
init.go

C#

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

手動提供憑證

Firebase 專案支援 Google 服務帳戶，您可以透過這些帳戶從應用程式伺服器或信任環境呼叫 Firebase 伺服器 API。如果您在本機開發程式碼，或將應用程式部署到內部部署，則可以使用透過此服務帳戶取得的憑證，授權伺服器要求。

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

如何為服務帳戶產生私密金鑰檔案：

  1. 在 Firebase 主控台中，依序開啟「設定」>「服務帳戶」。

  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 環境中測試或執行時使用服務帳戶憑證。

使用憑證鑄造存取權杖

除非您使用會自動處理授權的 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 Web Token (JWT) 驗證要求。詳情請參閱「JSON Web 權杖」。

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: Bearer <access_token> 格式將權杖新增為 Authorization 標頭的值：

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

授權舊版通訊協定傳送要求

使用 HTTP 舊版通訊協定時，每項要求都必須包含 Firebase 主控台「設定」窗格「雲端訊息傳送」分頁中的伺服器金鑰。如為 XMPP，您必須使用相同的伺服器金鑰建立連線。

遷移舊版伺服器金鑰

自 2020 年 3 月起，FCM 已停止建立舊版伺服器金鑰。現有的舊版伺服器金鑰仍可正常運作，但我們建議您改用 Firebase 控制台中標示為「伺服器金鑰」的新版金鑰。

如要刪除現有的舊版伺服器金鑰，請前往 Google Cloud 控制台。

授權 HTTP 要求

訊息要求包含兩個部分：HTTP 標頭和 HTTP 主體。HTTP 標頭必須包含下列標頭：

  • Authorization: key=YOUR_SERVER_KEY
    請確認這是伺服器金鑰，其值可在 Firebase 控制台 設定窗格中的「Cloud Messaging」分頁中找到。 FCM 會拒絕 Android、Apple 平台和瀏覽器金鑰。
  • Content-Type：application/json 代表 JSON，application/x-www-form-urlencoded;charset=UTF-8 代表純文字。
    如果省略 Content-Type，系統會假設格式為純文字。

例如：

Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
  "data" : {
    ...
  },
}

如要進一步瞭解如何建立傳送要求，請參閱「 建立傳送要求」。舊版 HTTP 通訊協定參考資料提供訊息可包含的所有參數清單。

檢查伺服器金鑰的有效性

如果您在傳送訊息時收到驗證錯誤，請檢查伺服器金鑰是否有效。舉例來說，在 Linux 上執行下列指令：

api_key=YOUR_SERVER_KEY

curl --header "Authorization: key=$api_key" \
     --header Content-Type:"application/json" \
     https://fcm.googleapis.com/fcm/send \
     -d "{\"registration_ids\":[\"ABC\"]}"

如果您收到 401 HTTP 狀態碼，表示您的伺服器金鑰無效。

授權 XMPP 連線

透過 XMPP，您可以維持與 FCM 伺服器的持續性非同步雙向連線。這項連線可用於在伺服器和使用者已連線至 FCM 的裝置之間傳送及接收訊息。

您可以使用大多數 XMPP 程式庫，管理與 FCM 的長效連線。XMPP 端點會在 fcm-xmpp.googleapis.com:5235 執行。當您使用非正式版使用者測試功能時，請改為連線至 fcm-xmpp.googleapis.com:5236 的預先發布伺服器 (請注意不同的連接埠)。

在預先製作環境 (較小的環境，可執行最新的 FCM 版本) 定期測試，有助於將實際使用者與測試程式碼區隔開來。連線至 fcm-xmpp.googleapis.com:5236 的測試裝置和測試程式碼應使用不同的 FCM 傳送者 ID，以免將測試訊息傳送至正式版使用者，或透過測試連線傳送正式版流量的上游訊息。

連線有兩個重要規定：

  • 您必須啟動傳輸層安全標準 (TLS) 連線。請注意，FCM 目前不支援 STARTTLS 擴充功能。
  • FCM 需要 SASL PLAIN 驗證機制，使用 <your_FCM_Sender_Id>@fcm.googleapis.com (FCM sender ID) 和伺服器金鑰做為密碼。這些值可在 Firebase 控制台「設定」窗格中的「Cloud Messaging」分頁中找到。

如果連線在任何時間點失敗，請立即重新連線。在驗證後發生連線中斷時，無需退回。FCM 允許每個傳送者 ID並行連線 2500 個。

下列程式碼片段說明如何為 FCM 的 XMPP 連線執行驗證和授權。

XMPP 伺服器

XMPP 伺服器要求連線至 FCM

<stream:stream to="fcm.googleapis.com"
        version="1.0" xmlns="jabber:client"
        xmlns:stream="http://etherx.jabber.org/streams">

FCM

FCM 會開啟連線，並要求驗證機制，包括 PLAIN 方法。

<stream:features>
  <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl">
    <mechanism>X-OAUTH2</mechanism>
    <mechanism>X-GOOGLE-TOKEN</mechanism>
    <mechanism>PLAIN</mechanism>
  </mechanisms>
</stream:features>

XMPP 伺服器

XMPP 伺服器必須使用 PLAIN 驗證方法回應，從 Firebase 主控台「Settings」窗格中的「Cloud Messaging」分頁提供伺服器金鑰。

<auth mechanism="PLAIN"
xmlns="urn:ietf:params:xml:ns:xmpp-sasl">MTI2MjAwMzQ3OTMzQHByb2plY3RzLmdjbS5hb
mFTeUIzcmNaTmtmbnFLZEZiOW1oekNCaVlwT1JEQTJKV1d0dw==</auth>

FCM

<success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>

XMPP 伺服器

<stream:stream to="fcm.googleapis.com"
        version="1.0" xmlns="jabber:client"
        xmlns:stream="http://etherx.jabber.org/streams">

FCM

<stream:features>
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"/>
  <session xmlns="urn:ietf:params:xml:ns:xmpp-session"/>
</stream:features>

XMPP 伺服器

<iq type="set">
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"></bind>
</iq>

FCM

<iq type="result">
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind">
    <jid>SENDER_ID@fcm.googleapis.com/RESOURCE</jid>
  </bind>
</iq>

注意：FCM 在轉送訊息時不會使用已綁定的資源。

如要進一步瞭解如何建立傳送要求，請參閱「 建立傳送要求」。舊版 XMPP 通訊協定參考資料提供訊息可包含的所有參數清單。