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

向指定目標(註冊令牌、主題或條件)發送訊息。