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

僅供輸出。傳送訊息的 ID，格式為 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

包含即將下載到裝置上的圖片網址，並顯示在通知中。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

可收合的訊息群組 ID，只有在可繼續傳送時，才會傳送最後一則訊息。在任何指定最多只能有 4 個不同的收合鍵。
priority

enum (AndroidMessagePriority)

訊息優先順序。可接受「正常」和「高」值。詳情請參閱設定訊息的優先順序。
ttl

string (Duration format)

裝置離線時，訊息應保留在 FCM 儲存空間中的時間長度 (以秒為單位)。支援即時更新的時間上限為 4 週。如未設定，預設值為 4 週。如要立即傳送訊息，請設為 0。在 JSON 格式中，Duration 類型會編碼為字串而非物件，其中字串會在後接「s」(表示秒數) 並在前面加上秒數，以奈秒表示。舉例來說，含有 0 奈秒的 3 秒應以 JSON 格式編碼，其中 3 秒和 1 奈秒應以 JSON 格式表示，例如「3.000000001s」。TTL 會無條件捨去至最接近的秒數。

時間長度以秒為單位，最多可有 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)

Android 適用的 FCM SDK 提供的功能選項。
direct_boot_ok

boolean

如果將這項政策設為 True，即使裝置處於直接啟動模式，訊息功能仍可傳送至應用程式。請參閱「支援直接啟動模式」。

AndroidMessagePriority

傳送至 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,
  "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

用於取代通知導覽匣中現有通知的 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」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："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 閃爍率和顏色設定。總閃爍時間是由作業系統控制。
image

string

包含要顯示在通知中的圖片網址。如有設定，則會覆寫 google.firebase.fcm.v1.Notification.image。
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 請勿透過 Proxy 處理這則通知。
IF_PRIORITY_LOWERED 請只在裝置的 AndroidMessagePriority 從 HIGH 降至 NORMAL 時，才嘗試透過 Proxy 處理這則通知。

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 標頭。請參閱 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 提供的功能選項。

WebpushFcmOptions

網頁版 FCM SDK 提供的功能選項。

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 要求標頭。

後端會設定 30 天的 apns-expiration 預設值，而 apns-priority 的預設值是 10 (如果沒有明確設定)。

包含 "key": value 組合清單的物件。範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
payload

object (Struct format)

APN 酬載為 JSON 物件，包括 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

 向指定的目標 (註冊權杖、主題或條件) 傳送訊息。