如果应用使用的是已弃用的 HTTP 和 XMPP 旧版 FCM API，应尽早迁移到 HTTP v1 API。 使用这些 API 发送消息（包括上行消息）已于 2023 年 6 月 20 日弃用，关停时间为 2024 年 7 月 22 日。
详细了解受影响的具体功能。
除了持续的支持和新功能之外，HTTP v1 API 较之旧版 API 具有以下优势：
可通过访问令牌提供更高的安全性：HTTP v1 API 根据 OAuth2 安全模型使用只在短时间内有效的访问令牌。即使访问令牌变成公开状态，能被恶意使用的时间也只有 1 小时左右，之后令牌就会失效。传输刷新令牌的频率不像传输旧版 API 中使用的安全密钥那样频繁，因此这些令牌被捕获的可能性要低得多。
可针对不同平台更高效地自定义消息：在消息正文中，HTTP v1 API 加入了会传输到所有已定位实例的通用键，以及针对具体平台的键（方便您针对不同平台自定义消息）。这样，您就可以创建“替换项”，这些替换项可在一则消息中向不同的客户端平台发送略有不同的载荷。
对于新的客户端平台版本，扩展性和适应性更出色：HTTP v1 API 完全支持 Apple 平台、Android 和 Web 的消息传递选项。由于 JSON 载荷中包含每个平台专属的定义块，因此 FCM 可以根据需要扩展 API 以支持新版本及新平台。
更新服务器端点
HTTP v1 API 的端点网址与旧版端点的不同之处表现在以下几个方面：
- 带版本号，并且路径中包含
/v1。 - 路径中包含您应用的 Firebase 项目的 ID（格式为
/projects/myproject-ID/）。您可以在 Firebase 控制台的项目设置的“常规”标签页中找到此 ID。 - 明确将
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 v1 发送请求需要 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 就会使用该变量指向的服务账号文件。
如果未设置环境变量，则对于在 Compute Engine、Google Kubernetes Engine、App Engine 和 Cloud Functions 上运行的应用，ADC 会使用这些服务提供的默认服务账号。
如果 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)
}
C#
FirebaseApp.Create(new AppOptions()
{
Credential = GoogleCredential.GetApplicationDefault(),
});
手动提供凭据
Firebase 项目支持 Google 服务账号，您可以使用这些账号从应用服务器或受信任环境调用 Firebase 服务器 API。如果您是在本地编写代码，或是在本地部署您的应用，则可以使用通过此服务账号获取的凭据来对服务器请求进行授权。
如需对服务账号进行身份验证并授予其访问 Firebase 服务的权限，您必须生成 JSON 格式的私钥文件。
如需为您的服务账号生成私钥文件，请执行以下操作：
在 Firebase 控制台中，依次打开设置 > 服务账号。
点击生成新的私钥，然后点击生成密钥进行确认。
妥善存储包含密钥的 JSON 文件。
通过服务账号进行授权时，有两种方式可为您的应用提供凭据。您可以设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量，也可以在代码中明确传递服务账号密钥的路径。第一种方式更为安全，因此强烈推荐使用此方式。
如需设置该环境变量，请执行以下操作：
将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为包含服务账号密钥的 JSON 文件的路径：此变量仅适用于当前的 Shell 会话，因此请在开始新的会话时重新设置该变量。
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 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);
});
});
}
在此示例中，Google API 客户端库使用 JSON Web 令牌 (JWT) 对请求进行身份验证。有关详情，请参阅 JSON Web 令牌。
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: Bearer <access_token> 格式将令牌添加为 Authorization 标头的值：
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;
更新发送请求的载荷
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 v1 则提供针对具体平台的键块，平台之间的任何差异对开发者而言都一目了然。如此，您在任何情况下只需一个请求即可定位多个平台，如以下示例所示。
更新前
// 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。