REST Resource: projects.messages

資源：Message

透過 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 僅供輸出。訊息的 ID，格式為 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 要接收訊息的主題名稱，例如「天氣」注意：「/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

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 群組訊息的 ID，這是指可收合的訊息群組。這樣一來，在恢復傳送郵件時，系統只會傳送最後一封郵件。一次最多只能使用 4 個不同的收合鍵。
priority	enum (AndroidMessagePriority) 郵件優先順序。可採用「正常」和「high」輕鬆分配獎金詳情請參閱設定郵件優先順序。
ttl	string (Duration format) 裝置離線時，訊息應保留在 FCM 儲存空間的時間長度 (以秒為單位)。存留時間上限為 4 週，如未設定，預設值為 4 週。如要立即傳送訊息，請設為 0。在 JSON 格式中，Duration 類型會編碼為字串而非物件，其中字串的結尾是「s」(指示秒數) 後面，後面接收到的秒數，奈秒為單位，以小秒表示。舉例來說，長度為 0 奈秒的 3 秒應以 JSON 格式編碼為「3s」，而 3 秒和 1 奈秒則應以 JSON 格式表示「3.000000001s」。值會無條件捨去至最接近的秒數。 持續時間以秒為單位，最多 9 個小數位數，結尾為「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) FCM SDK for Android 提供的功能選項。
direct_boot_ok	boolean 如果將這項政策設為 True，系統會在裝置處於直接啟動模式時，允許傳送訊息至應用程式。請參閱支援直接啟動模式。

AndroidMessagePriority

傳送至 Android 裝置的訊息優先順序。請注意，這項優先順序屬於 FCM 概念，可控制訊息的傳送時間。請參閱 FCM 指南。此外，您也可以使用 AndroidNotification.NotificationPriority。

列舉
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, "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 的通知圖示設為我的圖示。如果您沒有在要求中傳送這個金鑰，FCM 會顯示應用程式資訊清單中指定的啟動器圖示。
color	string 通知的圖示顏色，以 #rrggbb 格式表示。
sound	string 裝置收到通知時要播放的音效。支援「default」或是應用程式中隨附的音效資源檔案名稱音效檔案必須位於 /res/raw/。
tag	string 用於取代通知導覽匣中現有通知的 ID。如未指定，每個要求都會建立新通知。如果已指定，且已顯示含有相同標記的通知，新通知會取代通知導覽匣中的現有通知。
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 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："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。 持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
visibility	enum (Visibility) 設定通知的 Notification.visibility。
notification_count	integer 設定這則通知代表的項目數量。系統可能會針對支援徽章的啟動器顯示徽章數量，詳情請參閱通知徽章。舉例來說，如果你只使用一則通知來代表多則新訊息，但想這裡計數代表新訊息總數，這項功能就非常實用。如果零或未指定，支援徽章的系統會使用預設值，也就是每次有新通知時，長按選單上顯示的數字遞增。
light_settings	object (LightSettings) 設定：如果裝置有 LED 燈，則可控制通知的 LED 閃爍率和顏色。總閃爍時間是由 OS 控制。
image	string 包含將顯示在通知中的圖片網址。如果有這個欄位，則會覆寫 google.firebase.fcm.v1.Notification.image。
bypass_proxy_notification (deprecated)	boolean 這個項目已遭淘汰！ 如果設定這項政策，應用程式將處理傳送到裝置的通知，而非 Proxy。
proxy	enum (Proxy) 這項設定可控管可透過 Proxy 處理通知的時機。

通知優先順序

通知的優先順序等級。

列舉
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 定義 持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
light_off_duration	string (Duration format) 執行個體類型，和 light_on_duration 一起定義 LED 閃光燈的閃爍速率。解析度由 proto.Duration 定義 持續時間以秒為單位，最多 9 個小數位數，結尾為「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

這項設定可控管可透過 Proxy 處理通知的時機。

列舉
PROXY_UNSPECIFIED	如果未指定，則預設為 Proxy.IF_PRIORITY_LOWERED。
ALLOW	請試著對這則通知進行 Proxy 處理。
DENY	請勿代理此通知。
IF_PRIORITY_LOWERED	只有在裝置的 AndroidMessagePriority 從 HIGH 降為 NORMAL 時，才能嘗試 Proxy 通知。

AndroidFcm 選項

FCM SDK for Android 提供的功能選項。

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 中定義的通知執行個體屬性。如果有，請註明「title」和「body」欄位會覆寫 google.firebase.fcm.v1.Notification.title 和 google.firebase.fcm.v1.Notification.body。
fcm_options	object (WebpushFcmOptions) FCM SDK for Web 的功能選項。

WebpushFcm 選項

FCM SDK for Web 的功能選項。

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)，請參閱 APN 要求標頭。 後端會將 apns-expiration 的預設值設為 30 天；如未明確設定，則 apns-priority 的預設值是 10。 包含 "key": value 組合清單的物件。範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
payload	object (Struct format) 以 JSON 物件形式的 APN 酬載，包括 aps 字典和自訂酬載。請參閱酬載金鑰參考資料。如果存在，則會覆寫 google.firebase.fcm.v1.Notification.title 和 google.firebase.fcm.v1.Notification.body。
fcm_options	object (ApnsFcmOptions) FCM SDK for iOS 提供的功能選項。

ApnsFcmOptions

FCM SDK for iOS 提供的功能選項。

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

欄位
analytics_label	string 與訊息分析資料相關的標籤。
image	string 包含將顯示在通知中的圖片網址。如果有這個欄位，則會覆寫 google.firebase.fcm.v1.Notification.image。

Fcm 選項

適用於 FCM SDK 功能的平台獨立選項。

JSON 表示法
{ "analytics_label": string }

欄位
analytics_label	string 與訊息分析資料相關的標籤。

方法
send	傳送訊息給指定目標 (註冊符記、主題或條件)。