构建应用服务器发送请求

使用 FCM 应用服务器协议,您可以构建消息请求并将其发送到以下各类目标:

  • 主题名称
  • 条件
  • 设备注册令牌
  • 设备组名称(仅限旧版协议)

您可以发送包含通知负载(由预定义字段组成)的消息、包含数据负载(由您自己的用户指定字段组成)的消息,或者包含这两种负载的消息。如需了解详情,请参阅消息类型。本页中的示例用于说明如何通过 v1 HTTP 协议发送通知消息。本文还包含有关如何通过旧版 HTTP 和 XMPP 协议发送消息的指导。

要通过 HTTP 发送消息,请向 FCM v1 端点发送一个 HTTP POST 请求并指定 send 方法。端点网址必须包含您应用的 Firebase 项目的项目 ID,您可在 Firebase 控制台的常规项目设置标签中找到此 ID。例如:

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

请求标头必须包含以下内容:

  • Content-type: application/json
  • Authorization: Bearer <valid Oauth 2.0 token for the service account of the Firebase project>

如需详细了解 OAuth 2.0 访问令牌,请参阅向发送请求提供授权

请求正文包含选项 JSON 键值对以及消息内容。如需简要了解消息正文选项,请参阅关于 FCM 消息;如需了解详情,请参阅 API 参考

向特定设备发送消息

在请求正文中,将 message 对象内的 token 键设为您要定位的具体应用实例的注册令牌。请查看适用于您的平台的客户端设置信息,以详细了解注册令牌。

必须使用访问令牌授权向 v1 API 发出的所有 HTTP 请求。要了解如何从您的服务帐号凭据获取访问令牌,请参阅授权发送请求

HTTP POST 请求

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 响应

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

向主题发送消息

向 Firebase 云消息传递主题发送消息与向单台设备或一个用户组发送消息十分类似。应用服务器会将消息正文中的 topic 键设为类似 yourTopic 这样的值。开发者可以选择符合以下正则表达式的任何主题名称:"[a-zA-Z0-9-_.~%]+"

要向多个主题的组合发送消息,应用服务器会将 condition 键设置为指定目标主题的某个布尔型条件。例如,要向已订阅 TopicATopicBTopicC 的设备发送消息,则设置如下条件:

'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

FCM 首先对括号中的所有条件求值,然后从左至右对表达式求值。在上述表达式中,只订阅某个单一主题的用户将不会接收到消息。同样地,未订阅 TopicA 的用户也不会接收到消息。下列组合将会接收到消息:

  • TopicA 和 TopicB
  • TopicA 和 TopicC

您最多可以在条件表达式中添加五个主题,支持使用括号。支持的运算符包括 &&||!。请注意 ! 的用法:

!('TopicA' in topics)

使用此表达式,任何未订阅 TopicA 的应用实例(包括未订阅任何主题的应用实例)都会收到消息。

如需详细了解应用服务器键,请参阅参考信息

主题 HTTP POST 请求

发送至单个主题:

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":{
    "topic" : "foo-bar",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message"
      }
   }
}

用 cURL 发送:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "message": {
    "topic" : "foo-bar",
    "notification": {
      "body": "This is a Firebase Cloud Messaging Topic Message!",
      "title": "FCM Message"
    }
  }
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

发送至已订阅“dogs”或“cats”主题的设备:

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":{
    "condition": "'dogs' in topics || 'cats' in topics",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
    }
  }
}

用 cURL 发送:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

主题 HTTP 响应

{
    "name": "projects/myproject-b5ae1/messages/5735743068807585451"
}

如需消息选项的完整列表,请参阅 HTTP v1 API 参考

使用旧版应用服务器协议发送消息

如果您更喜欢使用旧版协议,请按本部分所示构建消息请求。请注意,如果您通过 HTTP 发送消息到多个平台,v1 协议可以简化您的消息请求。

向特定设备发送消息

要向特定设备发送消息,请将 to 键设置为特定应用实例的注册令牌。请查看针对您的平台的客户端设置信息,了解有关注册令牌的更多信息。

HTTP POST 请求

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}

HTTP 响应

{ "multicast_id": 108,
  "success": 1,
  "failure": 0,
  "results": [
    { "message_id": "1:08" }
  ]
}

XMPP 消息

<message id="">
  <gcm xmlns="google:mobile:data">
    { "data": {
      "score": "5x1",
      "time": "15:10"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
  </gcm>
</message>

XMPP 响应

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

XMPP 连接服务器提供了另外几种可供选择的响应格式。请参阅服务器响应格式

如需向客户端应用发送下行消息时可用的消息选项的完整列表,请参阅您所选的连接服务器协议(HTTPXMPP)的参考信息。

向主题发送消息

向 Firebase 云消息传递主题发送消息与向单台设备或一个用户组发送消息十分类似。应用服务器会将 to 键设为类似 /topics/yourTopic 这样的值。开发者可以选择符合以下正则表达式的任何主题名称:"/topics/[a-zA-Z0-9-_.~%]+"

要向多个主题的组合发送消息,应用服务器必须将 condition 键(而非 to 键)设为用于指定目标主题的布尔型条件。例如,要向已订阅 TopicATopicBTopicC 的设备发送消息,则设置如下条件:

'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

FCM 首先对括号中的所有条件求值,然后从左至右对表达式求值。在上述表达式中,只订阅某个单一主题的用户将不会接收到消息。同样地,未订阅 TopicA 的用户也不会接收到消息。下列组合将会接收到消息:

  • TopicA 和 TopicB
  • TopicA 和 TopicC

您最多可以在条件表达式中添加五个主题,支持使用括号。支持的运算符包括 &&||!。请注意 ! 的用法:

!('TopicA' in topics)

使用此表达式,任何未订阅 TopicA 的应用实例(包括未订阅任何主题的应用实例)都会收到消息。

如需详细了解应用服务器键,请参阅您所选的连接服务器协议(HTTPXMPP)的参考信息。本页面中的示例说明了如何使用 HTTP 和 XMPP 协议将消息发送至主题。

主题 HTTP POST 请求

发送至一个主题:

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
  "to": "/topics/foo-bar",
  "data": {
    "message": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

发送至已订阅“dogs”或“cats”主题的设备:

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
  "condition": "'dogs' in topics || 'cats' in topics",
  "data": {
    "message": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

主题 HTTP 响应

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

主题 XMPP 消息

发送至一个主题:

<message id="">
  <gcm xmlns="google:mobile:data">
{
  "to": "/topics/foo-bar",
  "data": {
    "message": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

  </gcm>
</message>

发送至已订阅“dogs”或“cats”主题的设备:

<message id="">
  <gcm xmlns="google:mobile:data">
{
  "condition": "'dogs' in topics || 'cats' in topics",
  "data": {
    "message": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

  </gcm>
</message>

主题 XMPP 响应

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

FCM 服务器对主题发送请求返回成功或失败响应前,可能会有最长 30 秒的延迟。请务必在请求中相应地设置应用服务器的超时值。

如需消息选项的完整列表,请参阅您所选的连接服务器协议(HTTPXMPP)的参考信息。

向设备组发送消息

向设备组发送消息与向单台设备发送消息十分类似。您需要将 to 参数设为特定于设备组的通知键。如需详细了解负载支持,请参阅消息类型。本页的示例展示了如何通过 HTTP 和 XMPP 协议向设备组发送数据消息。

设备组 HTTP POST 请求

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to": "aUniqueKey",
  "data": {
    "hello": "This is a Firebase Cloud Messaging Device Group Message!",
   }
}

设备组 HTTP 响应

以下是一个“成功”的示例:notification_key 有 2 个关联的注册令牌,且消息已成功发送至这两个令牌:

{
  "success": 2,
  "failure": 0
}

以下是一个“部分成功”的示例:notification_key 有 3 个关联的注册令牌。 消息仅成功发送至其中一个注册令牌。响应消息列出了未收到消息的注册令牌:

{
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

当消息未能发送至与某个 notification_key 关联的一个或多个注册令牌时,应用服务器隔一段时间就会重试一次。

如果服务器尝试向没有成员的设备组发送消息,则响应如下所示(0 个成功,0 个失败):

{
  "success": 0,
  "failure": 0
}

设备组 XMPP 消息

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to": "aUniqueKey",
      "message_id": "m-1366082849205" ,
      "data": {
          "hello":"This is a Firebase Cloud Messaging Device Group Message!"
      }
  }
  </gcm>
</message>

设备组 XMPP 响应

当消息成功发送至设备组中的任何一台设备时,XMPP 连接服务器都会发送 ACK 响应。当发送至组中所有设备的所有消息都失败时,XMPP 连接服务器会发送 NACK 响应。

以下是一个“成功”的示例:notification_key 有 3 个关联的注册令牌,且消息已成功发送至这 3 个令牌:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

以下是一个“部分成功”的示例:notification_key 有 3 个关联的注册令牌。 消息仅成功发送至其中一个注册令牌。响应消息列出了未收到消息的注册令牌:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

当 FCM 连接服务器未能将消息发送至组中的所有设备时,应用服务器将收到 NACK 响应。

如需消息选项的完整列表,请参阅您所选的连接服务器协议(HTTPXMPP)的参考信息。

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面