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

使用 FCM HTTP v1 API 傳送訊息

使用 FCM HTTP v1 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 控制台中，依序開啟「設定」>「服務帳戶」。
按一下「產生新的私密金鑰」，然後按一下「產生金鑰」確認。
妥善儲存內含金鑰的 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 環境中測試或執行時，使用服務帳戶憑證。

使用憑證產生存取權杖

除非您使用 Firebase Admin SDK，否則您需要產生存取權杖並新增至傳送要求。Firebase Admin SDK 會自動處理授權。

使用 Firebase 憑證和偏好語言的 Google Auth 程式庫，擷取短期有效的 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

使用其他專案的服務帳戶授權

您可以使用從其他專案 (「傳送者專案」) 服務帳戶產生的 OAuth 2.0 權杖，為一個專案 (「目標專案」) 傳送訊息。這樣一來，您就能在一個專案中集中管理服務帳戶，同時代表他人傳送訊息。如要瞭解如何執行這項操作，請按照下列步驟操作：

啟用 API：確認傳送者專案已啟用 Firebase Cloud Messaging API。
建立服務帳戶：在傳送者專案中建立服務帳戶。
授予權限：在目標專案的 IAM 頁面中，將「Firebase Cloud Messaging API 管理員」角色授予服務帳戶的電子郵件地址。這樣一來，其他專案的服務帳戶就能將訊息傳送至目標專案。
取得權杖：在傳送者專案中，為服務帳戶產生 OAuth 2.0 存取權杖。方法有二：
- 下載及使用服務帳戶金鑰 JSON 檔案。
- 或者，如果您的服務在 Google Cloud 上執行，也可以使用 Workload Identity。
傳送要求：在傳送要求的 Authorization 標頭中使用取得的存取權杖。要求必須傳送至目標專案的 HTTP v1 端點：
```
    POST https://fcm.googleapis.com/v1/TARGET_PROJECT_ID/messages:send
```

將訊息傳送至特定裝置

如要傳送至特定裝置，請傳遞裝置的註冊權杖，如下所示。

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

cURL 指令：

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "notification":{
     "title":"FCM Message",
     "body":"This is an FCM Message"
   },
   "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

如果成功，HTTP v1 API 回應會是包含訊息 ID 的 JSON 物件：

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

使用 FCM HTTP v1 API 傳送測試通知訊息

本節說明如何使用 FCM HTTP v1 API 傳送測試通知訊息。

HTTP 要求網址

這項要求包含向下列網址的指定目標 (註冊權杖、主題或條件) 發出的 HTTP POST：

POST https://fcm.googleapis.com/v1/projectId/messages:send

完整的 HTTP 要求 JSON 範例

以下是完整範例，說明如何在 HTTP POST 要求中發布通知：

{
  "message": {
    "token": REGISTRATION_TOKEN,
    "notification": {
      "title": "FCM API test",
      "body": "This is the body of the notification.",
      "image": "https://cat.10515.net/1.jpg"
    }
  }
}

執行

按一下「執行」，在 API Explorer 中試用範例。

使用 FCM HTTP v1 API 傳送訊息 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

授權 HTTP v1 傳送要求

使用 ADC 提供憑證

Node.js

Java

Python

Go

C#

手動提供憑證

Linux 或 macOS

Windows

使用憑證產生存取權杖

node.js

Python

Java

node.js

Python

Java

使用其他專案的服務帳戶授權

將訊息傳送至特定裝置

REST

使用 FCM HTTP v1 API 傳送測試通知訊息

HTTP 要求網址

完整的 HTTP 要求 JSON 範例

使用 FCM HTTP v1 API 傳送訊息