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

授權傳送要求

應用程式伺服器或信任的環境向「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 Engine、App 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) 檢查憑證順序：

ADC 會檢查環境變數已設定 GOOGLE_APPLICATION_CREDENTIALS。如果已設定變數 ADC 會使用變數指向的服務帳戶檔案。
如未設定環境變數，ADC 會使用預設服務帳戶該Compute Engine、Google Kubernetes Engine、App Engine。而 Cloud Functions 適用於在這些服務中執行的應用程式
如果 ADC 無法使用上述任一項憑證，系統會擲回錯誤。

以下 Admin SDK 程式碼範例說明這項策略。這個範例並未明確指定應用程式憑證，不過 ADC 可以只要已設定環境變數，即可以隱含方式找到憑證；或只要應用程式在 Compute Engine 上運作 Google Kubernetes Engine、App 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)
}init.go

C#

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

手動提供憑證

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

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

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

在 Firebase 主控台中，依序開啟「設定」>「服務帳戶」。
按一下「產生新私密金鑰」，然後按一下「產生金鑰」加以確認。
妥善儲存含有金鑰的 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);
    });
  });
}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 控制台設定窗格中的「Cloud Messaging」分頁中找到。 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 要求採用 SASL PLAIN 驗證機制 <your_FCM_Sender_Id>@fcm.googleapis.com (FCM 寄件者 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 主控台「設定」窗格的「雲端通訊」分頁中提供伺服器金鑰。

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