授權發送請求

從應用程式伺服器或受信任環境傳送到 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) 會依照下列順序檢查您的憑證：

  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(),
});

爪哇

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

default_app = firebase_admin.initialize_app()

去

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 檔案的檔案路徑。此變數僅適用於目前的 shell 會話，因此如果您開啟新會話，請再次設定該變數。

Linux 或 macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

視窗

使用 PowerShell：

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

完成上述步驟後，應用程式預設憑證 (ADC) 能夠隱含地確定您的憑證，從而允許您在非 Google 環境中測試或執行時使用服務帳戶憑證。

使用憑證建立存取令牌

除非您使用自動處理授權的Admin SDK ，否則您需要建立存取權杖並將其新增至傳送請求。

將您的 Firebase 憑證與您的首選語言的Google Auth 庫一起使用，以檢索短期 OAuth 2.0 存取權令牌：

節點.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 令牌或 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

爪哇

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> ：

節點.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}
index.js

Python

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}
messaging.py

爪哇

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 Console中執行此操作。

授權 HTTP 請求

訊息請求由兩部分組成：HTTP 標頭和 HTTP 正文。 HTTP 標頭必須包含以下標頭：

  • Authorization ：key=YOUR_SERVER_KEY
    確保這是伺服器金鑰，其值可在 Firebase 控制台「設定」窗格的「雲端訊息傳遞」標籤中找到。 Android、Apple 平台和瀏覽器金鑰被 FCM 拒絕。
  • Content-Type ：JSON 的application/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寄件者 ID ）和伺服器金鑰作為密碼。這些值可在 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 開啟連線並要求身份驗證機制，包括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>

流式細胞儀

<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">

流式細胞儀

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

流式細胞儀

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

注意：FCM 在路由訊息時不使用綁定資源。

有關創建發送請求的完整詳細信息，請參閱構建發送請求。舊版 XMPP 協定參考提供了訊息可以包含的所有參數的清單。