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

從舊版 FCM API 遷移至 HTTP v1

如果應用程式使用已淘汰的 FCM 舊版 HTTP 和 XMPP API，請盡快遷移至 HTTP v1 API。自 2023 年 6 月 20 日起，系統已淘汰透過這些 API 傳送訊息 (包括上游訊息) 的功能，並於 2024 年 7 月 22 日開始停用。

進一步瞭解受影響的特定功能。

除了持續支援和新功能外，HTTP v1 API 相較於舊版 API 還有下列優點：

透過存取權杖提升安全性：HTTP v1 API 會根據 OAuth2 安全性模型，使用存留時間較短的存取權杖。如果存取權杖遭到公開，惡意使用者只能在權杖失效前的一小時左右使用。與舊版 API 中使用的安全金鑰相比，重新整理權杖的傳輸頻率較低，因此遭擷取的可能性也低得多。
更有效率地跨平台自訂訊息：對於訊息主體，HTTP v1 API 具有適用於所有目標執行個體的通用鍵，以及可讓您跨平台自訂訊息的平台專屬鍵。這樣一來，您就能建立「覆寫」，在單一訊息中將略有不同的酬載傳送至不同的用戶端平台。
更具擴充性，可因應新版用戶端平台 HTTP v1 API 完全支援 Apple 平台、Android 和 Web 提供的訊息選項。由於每個平台在 JSON 酬載中都有自己的定義區塊，因此 FCM 可視需要將 API 擴充至新版本和新平台。

更新伺服器端點

HTTP v1 API 的端點網址與舊版端點的差異如下：

路徑中包含 /v1，因此具有版本資訊。
路徑包含應用程式的 Firebase 專案 ID，格式為 /projects/myproject-ID/。這個 ID 位於 Firebase 控制台的「一般專案設定」分頁中。
明確指定 send 方法為 :send。

如要更新 HTTP v1 的伺服器端點，請在傳送要求的標頭中，將下列元素新增至端點。

先前的 HTTP 要求

POST https://fcm.googleapis.com/fcm/send

XMPP 要求日期早於

舊版 XMPP 訊息會透過連線傳送至下列端點：

fcm-xmpp.googleapis.com:5235

晚於

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

更新傳送要求的授權

HTTP 第 1 版傳送要求需要 OAuth 2.0 存取權杖，取代舊版要求中使用的伺服器金鑰字串。如果您使用 Admin SDK 傳送訊息，程式庫會為您處理權杖。如果您使用原始通訊協定，請按照本節所述取得權杖，並將其新增至標頭，格式為 Authorization: Bearer <valid Oauth 2.0 token>。

之前

Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA

晚於

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

視伺服器環境的詳細資料而定，請一併使用下列策略，授權伺服器對 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 憑證和偏好語言的 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: 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

更新傳送要求的酬載

FCM HTTP v1 在 JSON 訊息酬載的結構中，導入了重大變更。這些變更主要是為了確保在不同用戶端平台上收到訊息時，系統能正確處理訊息；此外，這些變更也提供額外的彈性，讓您能自訂或「覆寫」每個平台的訊息欄位。

除了檢查本節中的範例，請參閱「在各平台自訂訊息」一文，並查看 API 參考資料，熟悉 HTTP v1。

範例：簡單的通知訊息

以下是僅包含 title、body 和 data 欄位的極簡通知酬載比較，可看出舊版和 HTTP v1 酬載的基本差異。

之前

{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available."
  },
  "data": {
    "story_id": "story_12345"
  }
}

晚於

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    }
  }
}

範例：巢狀 JSON 資料

與舊版即時通訊 API 不同，HTTP v1 API 不支援 data 欄位中的巢狀 JSON 值。必須將 JSON 轉換為字串。

之前

{
  ...
  "data": {
    "keysandvalues": {"key1": "value1", "key2": 123}
  }
}

晚於

{
  "message": {
   ...
    "data": {
      "keysandvalues": "{\"key1\": \"value1\", \"key2\": 123}"
    }
  }
}

範例：指定多個平台

如要啟用多平台指定目標，舊版 API 會在後端執行覆寫作業。相較之下，HTTP 第 1 版提供平台專屬的金鑰區塊，可讓開發人員清楚瞭解平台之間的差異。這樣一來，您就能透過單一要求指定多個平台，如下列範例所示。

之前

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

晚於

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

範例：使用平台覆寫自訂

除了簡化跨平台訊息指定目標作業，HTTP v1 API 也提供彈性，可自訂各平台的訊息。

之前

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "Check out the Top Story.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

晚於

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY",
        "body": "Check out the Top Story"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

範例：指定特定裝置

如要使用 HTTP v1 API 指定特定裝置，請在 token 鍵中提供裝置目前的註冊權杖，而非 to 鍵。

之前

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

晚於

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

如要查看更多範例及瞭解 FCM HTTP v1 API，請參閱下列資源：

說明如何使用 HTTP v1 API 建構應用程式伺服器傳送要求。除非另有註明，否則所有「REST」程式碼片段都會使用 v1 API。
Firebase 網誌。

從舊版 FCM API 遷移至 HTTP v1 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

更新伺服器端點

先前的 HTTP 要求

XMPP 要求日期早於

晚於

更新傳送要求的授權

之前

晚於

使用 ADC 提供憑證

Node.js

Java

Python

Go

C#

手動提供憑證

Linux 或 macOS

Windows

使用憑證產生存取權杖

node.js

Python

Java

node.js

Python

Java

更新傳送要求的酬載

範例：簡單的通知訊息

之前

晚於

範例：巢狀 JSON 資料

之前

晚於

範例：指定多個平台

之前

晚於

範例：使用平台覆寫自訂

之前

晚於

範例：指定特定裝置

之前

晚於

從舊版 FCM API 遷移至 HTTP v1