Watch demos on how to build & run AI-powered apps with Firebase at Demo Day '24. Watch now.

本頁面由 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 會使用您現有的預設服務帳戶取得憑證，以便授權要求，並透過 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: 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 通訊協定參考資料提供訊息可包含的所有參數清單。