使用 FCM HTTP v1 API 发送消息

使用 FCM HTTP v1 API，您可以构建消息请求并将其发送到以下各类目标：

主题名称
条件
设备注册令牌
设备组名称（仅限协议）

您可以发送包含通知载荷（由预定义字段组成）的消息、包含数据载荷（由您自己的用户定义字段组成）的消息，或者包含这两种载荷的消息。如需了解详情，请参阅消息类型。

为 HTTP v1 发送请求 (send request) 提供授权

根据服务器环境的详细信息，您可以组合使用以下策略为服务器向 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)
}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 文件的路径：此变量仅适用于当前的 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 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 令牌 (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.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 Admin 角色。这样，其他项目的服务账号就可以向目标项目发送消息。
获取令牌：为发送方项目中的服务账号生成 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 发送请求 (send request) 提供授权

使用 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 发送消息