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)

郵件優先順序。可能的值為「標準」和「高」。詳情請參閱設定郵件優先順序。
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 中 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
}
欄位
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

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