Save the date - Google I/O returns May 18-20. Register to get the most out of the digital experience: Build your schedule, reserve space, participate in Q&As, earn Google Developer profile badges, and more. Register now
本頁面由 Cloud Translation API 翻譯而成。
Switch to English

授權發送請求

從應用服務器或可信環境發送到FCM的請求必須經過授權。請注意舊版HTTP和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引擎，App Engine或云功能（包括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 API客戶端庫一起用於您的首選語言，以檢索短暫的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網絡令牌或JWT對請求進行身份驗證。有關更多信息，請參閱JSON Web令牌。

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token
messaging.py

爪哇

private static String getAccessToken() throws IOException {
  GoogleCredential googleCredential = GoogleCredential
      .fromStream(new FileInputStream("service-account.json"))
      .createScoped(Arrays.asList(SCOPES));
  googleCredential.refreshToken();
  return googleCredential.getAccessToken();
}
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

爪哇

URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;
Messaging.java

授權舊版協議發送請求

使用HTTP舊協議，每個請求必須包含Firebase控制台“設置”窗格中“雲消息”選項卡中的服務器密鑰。對於XMPP，必須使用相同的服務器密鑰來建立連接。

遷移舊版服務器密鑰

從2020年3月開始，FCM停止創建舊服務器密鑰。現有的舊服務器密鑰將繼續起作用，但是我們建議您在Firebase控制台中使用標記為“服務器密鑰”的較新版本的密鑰。

如果要刪除現有的舊服務器密鑰，可以在Google Cloud Console中進行。

授權HTTP請求

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

  • Authorization ：密鑰= YOUR_SERVER_KEY
    確保這是服務器密鑰，其值在Firebase控制台“設置”窗格的“雲消息”選項卡中可用。 FCM拒絕Android，iOS和瀏覽器鍵。
  • 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需要使用<your_FCM_Sender_Id>@fcm.googleapis.com （FCM發送者ID ）和Server密鑰作為密碼的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打開連接並請求包括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 auth方法進行響應，並從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協議參考》提供了消息可以包含的所有參數的列表。