REST Resource: projects.messages

资源:留言

由 Firebase 云消息服务发送的消息。

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

要发送消息的主题名称,例如“天气”。注意:不应提供“/topics/”前缀。

condition

string

发送消息的条件,例如“主题中的'foo' && 主题中的'bar'”。

通知

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

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

string

通知的标题。

body

string

通知的正文。

image

string

包含将要下载到设备上并显示在通知中的图像的 URL。 JPEG、PNG、BMP 跨平台完全支持。动画 GIF 和视频仅适用于 iOS。 WebP 和 HEIF 跨平台和平台版本具有不同级别的支持。 Android 有 1MB 图像大小限制。在 Firebase 存储上托管图像的配额使用情况和影响/成本: https ://firebase.google.com/pricing

Android配置

通过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”(表示秒)结尾,前面是秒数,纳秒表示为秒的小数部分。例如,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,则当设备处于直接启动模式时,将允许将消息传递到应用程序。请参阅支持直接启动模式

Android消息优先级

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

枚举
NORMAL数据消息的默认优先级。普通优先级消息不会在睡眠设备上打开网络连接,并且它们的传递可能会延迟以节省电池。对于时间敏感度较低的消息,例如新电子邮件或其他要同步数据的通知,请选择正常传送优先级。
HIGH通知消息的默认优先级。 FCM 尝试立即传递高优先级消息,从而允许 FCM 服务在可能的情况下唤醒睡眠设备并打开与应用程序服务器的网络连接。例如,具有即时消息、聊天或语音呼叫提醒功能的应用程序通常需要打开网络连接,并确保 FCM 立即将消息传送到设备。如果消息时间紧迫并且需要用户立即交互,请设置高优先级,但请注意,与普通优先级消息相比,将消息设置为高优先级会更多地消耗电池。

Android通知

发送至 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,
}
领域
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

设备收到通知时播放的声音。支持“默认”或应用程序中捆绑的声音资源的文件名。声音文件必须位于 /res/raw/ 中。

tag

string

用于替换通知抽屉中现有通知的标识符。如果未指定,每个请求都会创建一个新通知。如果指定并且已显示具有相同标签的通知,则新通知将替换通知抽屉中的现有通知。

click_action

string

与用户单击通知关联的操作。如果指定,当用户单击通知时,将启动具有匹配意图过滤器的活动。

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“Zulu”格式的时间戳,具有纳秒分辨率和最多九个小数位。示例: "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

包含将在通知中显示的图像的 URL。如果存在,它将覆盖google.firebase.fcm.v1.Notification.image

通知优先级

通知的优先级。

枚举
PRIORITY_UNSPECIFIED如果未指定优先级,则通知优先级设置为PRIORITY_DEFAULT
PRIORITY_MIN最低通知优先级。除非在特殊情况下(例如详细的通知日志),否则可能不会向用户显示具有此PRIORITY_MIN的通知。
PRIORITY_LOW较低的通知优先级。与PRIORITY_DEFAULT的通知相比,UI 可以选择将通知显示得更小,或者显示在列表中的不同位置。
PRIORITY_DEFAULT默认通知优先级。如果应用程序不区分自己的通知的优先级,请对所有通知使用此值。
PRIORITY_HIGH更高的通知优先级。使用它来获取更重要的通知或警报。与PRIORITY_DEFAULT的通知相比,UI 可以选择将这些通知显示得更大,或者显示在通知列表中的不同位置。
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)。

AndroidFcm选项

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

JSON 表示
{
  "analytics_label": string
}
领域
analytics_label

string

与消息的分析数据关联的标签。

Webpush配置

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 通知选项。支持Web 通知 API中定义的通知实例属性。如果存在,“title”和“body”字段将覆盖google.firebase.fcm.v1.Notification.titlegoogle.firebase.fcm.v1.Notification.body

fcm_options

object ( WebpushFcmOptions )

FCM SDK for Web 提供的功能选项。

WebpushFcm选项

FCM SDK for Web 提供的功能选项。

JSON 表示
{
  "link": string,
  "analytics_label": string
}
领域
analytics_label

string

与消息的分析数据关联的标签。

Apns配置

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

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

map (key: string, value: string)

Apple 推送通知服务中定义的 HTTP 请求标头。请参阅APNs 请求标头以获取支持的标头,例如apns-expirationapns-priority

后端将apns-expiration的默认值设置为 30 天,如果未明确设置, apns-priority的默认值设置为 10。

包含"key": value对。示例: { "name": "wrench", "mass": "1.3kg", "count": "3" }

payload

object ( Struct format)

APNs 有效负载作为 JSON 对象,包括aps字典和自定义有效负载。请参阅有效负载密钥参考。如果存在,它将覆盖google.firebase.fcm.v1.Notification.titlegoogle.firebase.fcm.v1.Notification.body

fcm_options

object ( ApnsFcmOptions )

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

ApnsFcm选项

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

JSON 表示
{
  "analytics_label": string,
  "image": string
}
领域
analytics_label

string

与消息的分析数据关联的标签。

image

string

包含将在通知中显示的图像的 URL。如果存在,它将覆盖google.firebase.fcm.v1.Notification.image

Fcm选项

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

JSON 表示
{
  "analytics_label": string
}
领域
analytics_label

string

与消息的分析数据关联的标签。

方法

send

向指定目标(注册令牌、主题或条件)发送消息。