REST Resource: projects.messages

资源：消息

Firebase Cloud Messaging Service 发送的消息。

JSON 表示法

{ "name": string, "data": { string: string, ... }, "notification": { object (Notification) }, "android": { object (AndroidConfig) }, "webpush": { object (WebpushConfig) }, "apns": { object (ApnsConfig) }, "fcm_options": { object (FcmOptions) }, // Union field target can be only one of the following: "token": string, "topic": string, "condition": string // End of list of possible types for union field target. }

字段
name	string 仅限输出。所发送消息的标识符，格式为 projects/*/messages/{message_id}。
data	map (key: string, value: string) 仅限输入。任意键/值载荷，必须采用 UTF-8 编码。键不能是保留的字词（“from”“message_type”或任何以“google.”或“gcm.notification”开头的字词）。向 iOS 设备发送仅包含数据字段的载荷时，ApnsConfig 仅允许使用普通优先级 ("apns-priority": "5")。 包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
notification	object (Notification) 仅限输入。可在所有平台上使用的基本通知模板。
android	object (AndroidConfig) 仅限输入。针对通过 FCM 连接服务器发送的消息的 Android 专用选项。
webpush	object (WebpushConfig) 仅限输入。Webpush 协议选项。
apns	object (ApnsConfig) 仅限输入。Apple 推送通知服务特定选项。
fcm_options	object (FcmOptions) 仅限输入。可在所有平台上使用的 FCM SDK 功能选项的模板。
联合字段 target。必需。仅限输入。要向其发送消息的目标。target 只能是下列其中一项：
token	string 向其发送消息的注册令牌。
topic	string 消息要发送到的主题名称，例如"weather"。注意：“/topics/”前缀。
condition	string 消息发送至的条件，例如“foo”在主题中(&&)“bar”主题中”。

通知

可在所有平台上使用的基本通知模板。

JSON 表示法
{ "title": string, "body": string, "image": string }

字段
title	string 通知的标题。
body	string 通知的正文。
image	string 包含将要下载到设备上并显示在通知中的图片的网址。跨平台全面支持 JPEG、PNG 和 BMP。动画 GIF 和视频只适用于 iOS。WebP 和 HEIF 在不同平台和平台版本上的支持级别各不相同。Android 的图片大小上限为 1MB。在 Firebase 存储上托管映像的配额用量和影响/费用：https://firebase.google.com/pricing

AndroidConfig

针对通过 FCM 连接服务器发送的消息的 Android 专用选项。

JSON 表示法
{ "collapse_key": string, "priority": enum (AndroidMessagePriority), "ttl": string, "restricted_package_name": string, "data": { string: string, ... }, "notification": { object (AndroidNotification) }, "fcm_options": { object (AndroidFcmOptions) }, "direct_boot_ok": boolean }

字段
collapse_key	string 一组邮件的标识符，可折叠，以便当恢复递送时只发送最后一条消息。在任意指定时间内最多允许 4 个不同的折叠密钥。
priority	enum (AndroidMessagePriority) 消息优先级。可以接受“常规”和“高”值。如需了解详情，请参阅设置消息的优先级。
ttl	string (Duration format) 当设备离线时，消息在 FCM 存储空间中保留的时长（以秒为单位）。支持的最长存留时间为 4 周，如果未设置，默认值为 4 周。如果您想立即发送消息，请将该值设置为 0。在 JSON 格式中，Duration 类型编码为字符串而不是对象，其中字符串以后缀“s”结尾（表示秒数），并且前面是秒数，纳秒以小数秒表示。例如，0 纳秒的 3 秒应以 JSON 格式编码为“3s”，而 3 秒和 1 纳秒应以 JSON 格式表示为“3.000000001s”。TTL 将向下舍入到最接近的秒数。 该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
restricted_package_name	string 应用的软件包名称，其注册令牌必须匹配才能接收消息。
data	map (key: string, value: string) 任意键/值载荷。如果存在，它将替换 google.firebase.fcm.v1.Message.data。 包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
notification	object (AndroidNotification) 将发送给 Android 设备的通知。
fcm_options	object (AndroidFcmOptions) 适用于 Android 版 FCM SDK 所提供功能的选项。
direct_boot_ok	boolean 如果此政策设为 true，系统将允许在设备处于直接启动模式时向该应用传送消息。请参阅支持“直接启动”模式。

AndroidMessagePriority 功能

向 Android 设备发送消息的优先级。请注意，此优先级是一个 FCM 概念，用于控制何时传送消息。请参阅 FCM 指南。此外，您还可以使用 AndroidNotification.NotificationPriority 来确定目标 Android 设备上的通知显示优先级。

枚举
NORMAL	数据消息的默认优先级。普通优先级消息不会让睡眠中的设备打开网络连接，为了省电，消息可能会被延迟传递。对于时间不太敏感的邮件（例如新电子邮件通知或其他要同步的数据），请选择普通递送优先级。
HIGH	通知消息的默认优先级。FCM 会立即尝试传递高优先级消息，允许 FCM 服务在可能的情况下唤醒休眠设备并打开与应用服务器的网络连接。例如，具有即时通讯、聊天或语音通话提醒功能的应用通常需要打开网络连接，并确保 FCM 及时将消息传递给设备。如果消息具有时效性并且需要用户立即互动，请设置高优先级，但请注意，与普通优先级消息相比，将消息设置为高优先级耗电更多。

AndroidNotification

将发送给 Android 设备的通知。

JSON 表示法

{ "title": string, "body": string, "icon": string, "color": string, "sound": string, "tag": string, "click_action": string, "body_loc_key": string, "body_loc_args": [ string ], "title_loc_key": string, "title_loc_args": [ string ], "channel_id": string, "ticker": string, "sticky": boolean, "event_time": string, "local_only": boolean, "notification_priority": enum (NotificationPriority), "default_sound": boolean, "default_vibrate_timings": boolean, "default_light_settings": boolean, "vibrate_timings": [ string ], "visibility": enum (Visibility), "notification_count": integer, "light_settings": { object (LightSettings) }, "image": string, "bypass_proxy_notification": boolean, "proxy": enum (Proxy) }

字段
title	string 通知的标题。如果存在，它将替换 google.firebase.fcm.v1.Notification.title。
body	string 通知的正文。如果存在，它将替换 google.firebase.fcm.v1.Notification.body。
icon	string 通知的图标。将可绘制资源 myicon 的通知图标设置为 myicon。如果您不在请求中发送此键，FCM 将会显示您的应用清单中指定的启动器图标。
color	string 通知的图标颜色，以 #rrggbb 格式来表示。
sound	string 设备收到通知时要播放的声音。支持“default”或应用中绑定的声音资源的文件名。声音文件必须位于 /res/raw/ 中。
tag	string 用于替换抽屉式通知栏中现有通知的标识符。如果未指定此参数，则每次请求均会创建一条新的通知。如果已指定此参数，且已显示带有相同标记的通知，则新通知将替换抽屉式通知栏中的现有通知。
click_action	string 与用户点击通知相关的操作。如果已指定，将在用户点击通知时启动带有匹配 intent 过滤器的 activity。
body_loc_key	string 应用的字符串资源中正文字符串的键，用于将正文文字本地化为用户当前的本地化设置语言。如需了解详情，请参阅字符串资源。
body_loc_args[]	string 将用于替换 body_loc_key 中用于将正文文字本地化为用户当前的本地化设置的格式说明符的变量字符串值。如需了解详情，请参阅格式和样式设置。
title_loc_key	string 应用的字符串资源中标题字符串的键，用于将标题文字本地化为用户当前的本地化设置语言。如需了解详情，请参阅字符串资源。
title_loc_args[]	string 将用于替换 title_loc_key（用来将标题文字本地化为用户当前的本地化设置语言）中的格式说明符的变量字符串值。如需了解详情，请参阅格式和样式设置。
channel_id	string 通知的渠道 ID（Android O 中的新功能）。应用必须使用此频道 ID 创建一个频道，然后才能收到任何包含此频道 ID 的通知。如果您不在请求中发送此渠道 ID，或者应用尚未创建所提供的渠道 ID，FCM 将使用应用清单中指定的渠道 ID。
ticker	string 设置“证券代码”文本，发送到无障碍服务。在 API 级别 21 (Lollipop) 之前，用于设置首次收到通知时显示在状态栏中的文本。
sticky	boolean 如果此政策设为 false 或未设置，当用户在面板中点击通知时，通知会自动关闭。如果设置为 true，即使用户点击通知，通知也会持续显示。
event_time	string (Timestamp format) 设置通知中的事件发生的时间。面板中的通知按此时间排序。时间点使用 protobuf.Timestamp 表示。 时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
local_only	boolean 设置此通知是否仅与当前设备相关。某些通知可以桥接到其他设备（例如 Wear OS 手表）进行远程显示。您可以设置此提示，建议不要桥接此通知。请参阅 Wear OS 指南
notification_priority	enum (NotificationPriority) 设置此通知的相对优先级。优先级指示该通知应占用用户的注意力。在某些情况下，系统可能会对用户隐藏优先级较低的通知，而用户可能会因收到优先级较高的通知而受到打扰。设置相同优先级的影响可能在不同平台上略有不同。请注意，此优先级与 AndroidMessagePriority 不同。此优先级在消息传送后由客户端处理，而 AndroidMessagePriority 是一个 FCM 概念，用于控制何时传送消息。
default_sound	boolean 如果设置为 true，则使用 Android 框架的默认通知提示音。默认值在 config.xml 中指定。
default_vibrate_timings	boolean 如果此政策设为 true，系统会为通知使用 Android 框架的默认振动模式。默认值在 config.xml 中指定。如果 default_vibrate_timings 设置为 true，并且也设置了 vibrate_timings，则系统会使用默认值，而不是用户指定的 vibrate_timings。
default_light_settings	boolean 如果此政策设为 true，系统会为通知使用 Android 框架的默认 LED 灯设置。默认值在 config.xml 中指定。如果 default_light_settings 设置为 true，并且也设置了 light_settings，则系统会使用用户指定的 light_settings，而不是默认值。
vibrate_timings[]	string (Duration format) 设置要使用的振动模式。传入一个 protobuf.Duration 数组以开启或关闭振动器。第一个值表示在开启振动器之前等待的 Duration。下一个值表示让振动器保持开启状态的 Duration。后续值会在 Duration 之间切换，以关闭振动器和开启振动器。如果设置了 vibrate_timings 且 default_vibrate_timings 设置为 true，则系统会使用默认值，而不是用户指定的 vibrate_timings。 该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
visibility	enum (Visibility) 设置通知的 Notification.visibility。
notification_count	integer 设置此通知表示的项目数量。对于支持标志的启动器，可能会显示为标志数量。请参阅通知标志。例如，如果您仅使用一个通知来表示多条新消息，但希望此处的计数表示新消息的总数，上述做法可能会很有用。如果为零或未指定，支持标记的系统使用默认值，即每当收到新通知时，都会递增长按菜单上显示的数字。
light_settings	object (LightSettings) 用于控制通知的 LED 指示灯闪烁频率和颜色（如果设备上有 LED 指示灯）的设置。总闪烁时间由操作系统控制。
image	string 包含将在通知中显示的图片的网址。如果存在，它将替换 google.firebase.fcm.v1.Notification.image。
bypass_proxy_notification (deprecated)	boolean 此项已弃用！ 如果已设置，则传送到设备的显示通知将由应用（而非代理）处理。
proxy	enum (Proxy) 此设置用于控制何时可以代理通知。

通知优先级

通知的优先级。

枚举
PRIORITY_UNSPECIFIED	如果未指定优先级，则通知优先级将设置为 PRIORITY_DEFAULT。
PRIORITY_MIN	最低通知优先级。除非在特殊情况下（例如详细的通知日志），否则带有此 PRIORITY_MIN 的通知可能不会向用户显示。
PRIORITY_LOW	降低通知优先级。与使用 PRIORITY_DEFAULT 的通知相比，界面可能会选择以较小的尺寸或在列表中的其他位置显示通知。
PRIORITY_DEFAULT	默认通知优先级。如果应用不优先处理自己的通知，则对所有通知使用此值。
PRIORITY_HIGH	通知优先级较高。此功能可用来接收更重要的通知或提醒。与使用 PRIORITY_DEFAULT 的通知相比，界面可能会选择更大尺寸或在通知列表中的不同位置显示这些通知。
PRIORITY_MAX	最高通知优先级。对于需要用户立即关注或输入的应用最重要的项目，请使用此类型。

公开范围

通知的不同可见性级别。

枚举
VISIBILITY_UNSPECIFIED	如果未指定，则默认为 Visibility.PRIVATE。
PRIVATE	在所有锁屏上显示此通知，但在安全的锁屏上隐藏敏感信息或隐私信息。
PUBLIC	在所有锁定屏幕上完整显示此通知。
SECRET	请勿在安全的锁屏上显示此通知的任何部分。

光照设置

用于控制通知 LED 的设置。

JSON 表示法
{ "color": { object (Color) }, "light_on_duration": string, "light_off_duration": string }

字段
color	object (Color) 必需。使用 google.type.Color 设置 LED 的 color。
light_on_duration	string (Duration format) 必需。与 light_off_duration 一起定义 LED 闪光灯的闪烁频率。分辨率由 proto.Duration 定义 该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
light_off_duration	string (Duration format) 必需。与 light_on_duration 一起定义 LED 闪光灯的闪烁频率。分辨率由 proto.Duration 定义 该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

颜色

表示 RGBA 颜色空间中的一种颜色。这种表示法旨在简化与各种语言中的颜色表示法之间的转换，而不是紧凑的转换。例如，在 Java 中，可以轻松地将此表示法的字段提供给 java.awt.Color 的构造函数；在 iOS 中，也可以轻松地将其提供给 UIColor 的 +colorWithRed:green:blue:alpha 方法；只需少量工作，即可轻松将其格式化为采用 JavaScript 的 CSS rgba() 字符串。

此参考页面不包含解读 RGB 值时应使用的绝对颜色空间，例如 sRGB、Adobe RGB、DCI-P3 和 BT.2020。默认情况下，应用应采用 sRGB 颜色空间。

在需要确定颜色均等性时，除非另有说明，否则如果两种颜色的红色、绿色、蓝色和 alpha 值都相差不超过 1e-5，则将相应实现视为相等。

示例 (Java)：

 import com.google.type.Color;

 // ...
 public static java.awt.Color fromProto(Color protocolor) {
   float alpha = protocolor.hasAlpha()
       ? protocolor.getAlpha().getValue()
       : 1.0;

   return new java.awt.Color(
       protocolor.getRed(),
       protocolor.getGreen(),
       protocolor.getBlue(),
       alpha);
 }

 public static Color toProto(java.awt.Color color) {
   float red = (float) color.getRed();
   float green = (float) color.getGreen();
   float blue = (float) color.getBlue();
   float denominator = 255.0;
   Color.Builder resultBuilder =
       Color
           .newBuilder()
           .setRed(red / denominator)
           .setGreen(green / denominator)
           .setBlue(blue / denominator);
   int alpha = color.getAlpha();
   if (alpha != 255) {
     result.setAlpha(
         FloatValue
             .newBuilder()
             .setValue(((float) alpha) / denominator)
             .build());
   }
   return resultBuilder.build();
 }
 // ...

示例 (iOS / Obj-C)：

 // ...
 static UIColor* fromProto(Color* protocolor) {
    float red = [protocolor red];
    float green = [protocolor green];
    float blue = [protocolor blue];
    FloatValue* alpha_wrapper = [protocolor alpha];
    float alpha = 1.0;
    if (alpha_wrapper != nil) {
      alpha = [alpha_wrapper value];
    }
    return [UIColor colorWithRed:red green:green blue:blue alpha:alpha];
 }

 static Color* toProto(UIColor* color) {
     CGFloat red, green, blue, alpha;
     if (![color getRed:&red green:&green blue:&blue alpha:&alpha]) {
       return nil;
     }
     Color* result = [[Color alloc] init];
     [result setRed:red];
     [result setGreen:green];
     [result setBlue:blue];
     if (alpha <= 0.9999) {
       [result setAlpha:floatWrapperWithValue(alpha)];
     }
     [result autorelease];
     return result;
}
// ...

示例 (JavaScript)：

// ...

var protoToCssColor = function(rgb_color) {
   var redFrac = rgb_color.red || 0.0;
   var greenFrac = rgb_color.green || 0.0;
   var blueFrac = rgb_color.blue || 0.0;
   var red = Math.floor(redFrac * 255);
   var green = Math.floor(greenFrac * 255);
   var blue = Math.floor(blueFrac * 255);

   if (!('alpha' in rgb_color)) {
      return rgbToCssColor(red, green, blue);
   }

   var alphaFrac = rgb_color.alpha.value || 0.0;
   var rgbParams = [red, green, blue].join(',');
   return ['rgba(', rgbParams, ',', alphaFrac, ')'].join('');
};

var rgbToCssColor = function(red, green, blue) {
  var rgbNumber = new Number((red << 16) | (green << 8) | blue);
  var hexString = rgbNumber.toString(16);
  var missingZeros = 6 - hexString.length;
  var resultBuilder = ['#'];
  for (var i = 0; i < missingZeros; i++) {
     resultBuilder.push('0');
  }
  resultBuilder.push(hexString);
  return resultBuilder.join('');
};

// ...

JSON 表示法
{ "red": number, "green": number, "blue": number, "alpha": number }

字段
red	number 颜色中红色的量，以区间 [0, 1] 中的值表示。
green	number 颜色中绿色的量，以区间 [0, 1] 中的值表示。
blue	number 颜色中的蓝色量，以 [0, 1] 区间中的值表示。
alpha	number 此颜色在像素中的应用比例。也就是说，最终像素颜色由以下等式定义： pixel color = alpha * (this color) + (1.0 - alpha) * (background color) 也就是说，值为 1.0 表示纯色，而值为 0.0 表示完全透明的颜色。它会使用封装容器消息，而非简单的浮动标量，以便区分默认值和未设置的值。如果省略，此颜色对象会渲染为纯色（就好像已经将 Alpha 值明确指定为 1.0）。

代理

此设置用于控制何时可以代理通知。

枚举
PROXY_UNSPECIFIED	如果未指定，则默认为 Proxy.IF_PRIORITY_LOWERED。
ALLOW	尝试将此通知设为代理。
DENY	请勿代理此通知。
IF_PRIORITY_LOWERED	仅当相应通知的AndroidMessagePriority在设备上从 HIGH 降低至 NORMAL 时，才尝试代理此通知。

AndroidFcmOptions

适用于 Android 版 FCM SDK 所提供功能的选项。

JSON 表示法
{ "analytics_label": string }

字段
analytics_label	string 与消息的分析数据相关联的标签。

WebpushConfig

Webpush 协议选项。

JSON 表示法
{ "headers": { string: string, ... }, "data": { string: string, ... }, "notification": { object }, "fcm_options": { object (WebpushFcmOptions) } }

字段
headers	map (key: string, value: string) webpush 协议中定义的 HTTP 标头。如需了解受支持的标头，请参阅 Webpush 协议，例如"TTL": "15"。 包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
data	map (key: string, value: string) 任意键/值载荷。如果存在，它将替换 google.firebase.fcm.v1.Message.data。 包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
notification	object (Struct format) 网络通知选项作为 JSON 对象。支持 Web Notification API 中定义的通知实例属性。“标题”（如果有）和“body”字段会替换 google.firebase.fcm.v1.Notification.title 和 google.firebase.fcm.v1.Notification.body。
fcm_options	object (WebpushFcmOptions) Web 版 FCM SDK 所提供功能的选项。

WebpushFcmOptions

Web 版 FCM SDK 所提供功能的选项。

JSON 表示法
{ "link": string, "analytics_label": string }

字段
link	string 用户点击通知时要打开的链接。所有网址值都需要采用 HTTPS。
analytics_label	string 与消息的分析数据相关联的标签。

ApnsConfig

Apple 推送通知服务特定选项。

JSON 表示法
{ "headers": { string: string, ... }, "payload": { object }, "fcm_options": { object (ApnsFcmOptions) } }

字段
headers	map (key: string, value: string) 在 Apple 推送通知服务中定义的 HTTP 请求标头。如需了解受支持的标头（例如 apns-expiration 和 apns-priority），请参阅 APNs 请求标头。 如果未明确设置，后端会将 apns-expiration 的默认值设为 30 天，并将 apns-priority 的默认值设为 10。 包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
payload	object (Struct format) 采用 JSON 对象形式的 APNs 载荷，包括 aps 字典和自定义载荷。请参阅载荷键参考。如果存在，它会替换 google.firebase.fcm.v1.Notification.title 和 google.firebase.fcm.v1.Notification.body。
fcm_options	object (ApnsFcmOptions) 适用于 iOS 版 FCM SDK 所提供功能的选项。

ApnsFcmOptions

适用于 iOS 版 FCM SDK 所提供功能的选项。

JSON 表示法
{ "analytics_label": string, "image": string }

字段
analytics_label	string 与消息的分析数据相关联的标签。
image	string 包含将在通知中显示的图片的网址。如果存在，它将替换 google.firebase.fcm.v1.Notification.image。

FcmOptions

FCM SDK 所提供功能的独立平台选项。

JSON 表示法
{ "analytics_label": string }

字段
analytics_label	string 与消息的分析数据相关联的标签。

方法
send	向指定目标（注册令牌、主题或条件）发送消息。