REST Resource: projects.messages

资源：消息

要通过 Firebase Cloud Messaging 服务发送的消息。

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”开头的字词）。向 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' in topics && 'bar' in topics”。

通知

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

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) 消息优先级。可采用“normal”和“high”值。如需了解详情，请参阅设置消息的优先级。
ttl	string (Duration format) 设备离线后，消息在 FCM 存储中保留的时长（以秒为单位）。支持的最长存留时间为 4 周，如未设置，默认值为 4 周。如果您想立即发送消息，请将其设置为 0。在 JSON 格式中，Duration 类型编码为字符串而不是对象，其中字符串以后缀“s”（表示秒）结尾，后跟秒数，而纳秒以小数秒表示。例如，3 秒加 0 纳秒应以 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, "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。
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 标头。如需了解支持的标头（例如 "TTL": "15"），请参阅 Webpush 协议。 包含一系列 "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 中定义的通知实例属性。如果存在，“title”和“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	向指定目标（注册令牌、主题或条件）发送消息。