了解 2023 年 Google I/O 大会上介绍的 Firebase 亮点。了解详情

本頁面由 Cloud Translation API 翻譯而成。

授權傳送要求

將應用程式伺服器或受信任環境傳送至 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 會使用您現有的預設服務帳戶取得憑證來授權要求，而 ADC 則透過環境變數 GOOGLE_APPLICATION_CREDENTIALS 啟用彈性的本機測試。如要徹底自動化授權流程，請搭配使用 ADC 與 Admin SDK 伺服器程式庫。

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

使用 ADC 提供憑證

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

ADC 會檢查是否已設定環境變數 GOOGLE_APPLICATION_CREDENTIALS。如果已設定變數，ADC 就會使用該變數指向的服務帳戶檔案。
如未設定環境變數，ADC 就會使用 Compute Engine、Google Kubernetes Engine、App Engine 和 Cloud Functions 為在這些服務中執行的應用程式提供的預設服務帳戶。
如果 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 格式的私密金鑰檔案。

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

在 Firebase 控制台中，依序開啟「Settings」>「Service Accounts」(服務帳戶)。
按一下「產生新私密金鑰」，然後按一下「產生金鑰」加以確認。
安全地儲存包含金鑰的 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 網頁符記。

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.tokenmessaging.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

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

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

遷移舊版伺服器金鑰

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

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

授權 HTTP 要求

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

Authorization：key=YOUR_SERVER_KEY
請確認這是「伺服器」金鑰，其值會顯示在 Firebase 控制台「設定」窗格的「雲端通訊」分頁中。 Android、Apple 平台和瀏覽器金鑰遭到 FCM 拒絕。
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 要求採用 <your_FCM_Sender_Id>@fcm.googleapis.com (FCM 寄件者 ID) 的 SASL PLAIN 驗證機制，並使用伺服器金鑰做為密碼。這些值會顯示在 Firebase 控制台「設定」窗格中的雲端通訊分頁。

如果連線失敗，您應立即重新連線。在驗證後中斷連線後，您不需要關閉連線。針對每個寄件者 ID，FCM 允許並行 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 控制台「設定」窗格的「雲端通訊」分頁提供伺服器金鑰。

<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 通訊協定參考資料提供訊息可包含的所有參數清單。