授權傳送要求

應用程式伺服器或信任的環境向「FCM」發出的要求 您必須先取得授權請注意,這些重要差異 舊版 HTTP API 和 HTTP v1 API 授權:

  • FCM HTTP v1 API 會使用 這種短期 OAuth 2.0 存取權杖 如要建立這個權杖,您可以使用 Google 應用程式 預設憑證 (位於 Google 伺服器環境) 和/或手動取得 所需憑證 找到來自服務帳戶的 JSON 私密金鑰檔案 如果你使用 Firebase Admin SDK 傳送訊息,程式庫會為您處理該權杖。
  • 已淘汰的舊版通訊協定只能使用取得的長效 API 金鑰 Firebase控制台即可啟用。
,瞭解如何調查及移除這項存取權。

授權 HTTP v1 傳送要求

視您的詳細資料而定 請搭配使用這些策略來授權伺服器 向 Firebase 服務發出的要求:

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

如果您的應用程式在 Compute Engine 上執行, Google Kubernetes EngineApp Engine 或 Cloud Functions (包括 Cloud Functions for Firebase) 使用應用程式預設憑證 (ADC)。ADC 會使用現有的預設服務 以取得憑證來授權要求,而 ADC 會啟用 您可以使用環境變數 GOOGLE_APPLICATION_CREDENTIALS。如要充分運用 授權流程,可搭配 Admin SDK 伺服器程式庫使用 ADC。

如果應用程式在非 Google 伺服器環境中執行, 您必須從 Firebase 專案下載服務帳戶 JSON 檔案。 只要您可以存取含有 私密金鑰檔案 GOOGLE_APPLICATION_CREDENTIALS:授權要求 取得憑證如果缺乏 授予這類檔案存取權,您必須在程式碼中參照服務帳戶檔案。 因為有憑證洩露風險,請務必小心謹慎。

使用 ADC 提供憑證

Google 應用程式預設憑證 (ADC) 檢查憑證 順序:

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

  2. 如未設定環境變數,ADC 會使用預設服務帳戶 該Compute EngineGoogle Kubernetes EngineApp Engine。 而 Cloud Functions 適用於在這些服務中執行的應用程式

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

以下 Admin SDK 程式碼範例說明這項策略。這個範例並未明確指定應用程式憑證,不過 ADC 可以 只要已設定環境變數,即可以隱含方式找到憑證;或 只要應用程式在 Compute Engine 上運作 Google Kubernetes EngineApp Engine 或 Cloud Functions。

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。如果您正在開發 或在地端部署環境部署應用程式 您就能使用取得 透過這個服務帳戶授權伺服器要求

驗證及授權服務帳戶 您必須先產生 JSON 格式的私密金鑰檔案,才能存取 Firebase 服務 格式。

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

  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) 系統會以隱含方式判斷您的憑證,方便您使用 Service 在非 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);
    });
  });
}

在此範例中,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;

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

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

遷移舊版伺服器金鑰

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

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

授權 HTTP 要求

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

  • Authorization:key=YOUR_SERVER_KEY
    請確認這是「伺服器」金鑰,其值為: 於提供 Firebase 控制台「設定」窗格的「雲端通訊」分頁。 Android、Apple 平台和瀏覽器金鑰遭到「FCM」拒絕。
  • Content-Typeapplication/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,以免發生任何風險 傳送測試訊息給正式版使用者,或從實際工作環境流量傳送上游訊息 測試連線

連線有兩個重要需求條件:

如果連線失敗的任何時間點,您應立即重新連線。 如果在連線中斷後仍無法解決問題,就不必再關閉 驗證。每個寄件者 IDFCM 允許並行 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 通訊協定參考資料 會提供訊息可能包含的所有參數的清單。