REST Resource: spaces.messages

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

資源:訊息

Google Chat 訊息。

JSON 表示法
{
  "name": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "lastUpdateTime": string,
  "deleteTime": string,
  "text": string,
  "cards": [
    {
      object (Card)
    }
  ],
  "cardsV2": [
    {
      object (CardWithId)
    }
  ],
  "annotations": [
    {
      object (Annotation)
    }
  ],
  "thread": {
    object (Thread)
  },
  "space": {
    object (Space)
  },
  "fallbackText": string,
  "actionResponse": {
    object (ActionResponse)
  },
  "argumentText": string,
  "slashCommand": {
    object (SlashCommand)
  },
  "attachment": [
    {
      object (Attachment)
    }
  ],
  "matchedUrl": {
    object (MatchedUrl)
  },
  "threadReply": boolean,
  "clientAssignedMessageId": string,
  "emojiReactionSummaries": [
    {
      object (EmojiReactionSummary)
    }
  ],
  "deletionMetadata": {
    object (DeletionMetadata)
  }
}
欄位
name

string

資源名稱,格式為 spaces/*/messages/*

範例:spaces/AAAAAAAAAAA/messages/BBBBBBBBBBB.BBBBBBBBBBB

sender

object (User)

僅供輸出。建立訊息的使用者。

createTime

string (Timestamp format)

僅供輸出。在 Google Chat 伺服器中建立訊息的時間。

lastUpdateTime

string (Timestamp format)

僅供輸出。使用者上次編輯訊息的時間。如果訊息從未編輯過,則這個欄位會留空。

deleteTime

string (Timestamp format)

僅供輸出。Google Chat 伺服器中的訊息刪除時間。如果系統從未刪除這則訊息,則這個欄位會留空。

text

string

訊息的純文字。圖片、影片、網頁或其他可預覽項目的第一個連結會產生預覽方塊。

cards[]
(deprecated)

object (Card)

已淘汰:請改用 cardsV2

提供豐富格式的格式化和互動式資訊卡,可用來顯示 UI 元素,例如格式化文字、按鈕、可點擊圖片等。資訊卡一般會顯示在郵件的純文字內文下方。「cards」和「cardsV2」的大小上限為 32 KB。

cardsV2[]

object (CardWithId)

格式豐富的互動式資訊卡,可以顯示 UI 元素和可編輯的小工具,例如:

  • 格式化的文字
  • 按鈕
  • 可點擊圖片
  • 核取方塊
  • 圓形按鈕
  • 輸入小工具。

資訊卡通常會在 Chat 訊息的文字內文下方顯示,但有時可能會顯示在其他位置,例如對話方塊。每張卡片的大小上限為 32 KB。

cardId 是同一訊息中卡片專屬 ID 的專屬識別碼,用於識別使用者輸入值。

目前支援的小工具包括:

  • TextParagraph
  • DecoratedText
  • Image
  • ButtonList
  • Divider
  • TextInput
  • SelectionInput
  • Grid
annotations[]

object (Annotation)

僅供輸出。與此訊息中的文字相關聯的註解。

thread

object (Thread)

郵件所屬的會話串。如需使用範例,請參閱開始或回覆郵件串

space

object (Space)

郵件所屬的聊天室。透過使用者驗證存取時,只會填入聊天室名稱。

fallbackText

string

訊息資訊卡的純文字說明,在系統無法顯示實際資訊卡時使用 (例如行動裝置通知)。

actionResponse

object (ActionResponse)

只能輸入。即時通訊應用程式用來設定回應回應方式的參數。

argumentText

string

僅供輸出。訊息文字的純文字,其中所有 Chat 應用程式皆已提及。

slashCommand

object (SlashCommand)

僅供輸出。斜線指令資訊 (如適用)。

attachment[]

object (Attachment)

使用者上傳的附件。

matchedUrl

object (MatchedUrl)

僅供輸出。「spaces.messages.text」中與連結預覽模式相符的網址。詳情請參閱預覽連結

threadReply

boolean

僅供輸出。true 時,訊息是回覆執行緒中的回應。以 false 的形式,聊天室的頂層訊息會顯示該則訊息,包括對話串的首則訊息,或是不含對話串回覆的訊息。

如果聊天室不支援對話串回覆,則這個欄位一律為 false

clientAssignedMessageId

string

在建立訊息時指派的 Chat 訊息自訂名稱。開頭必須是 client-,且只能包含小寫英文字母、數字和連字號,長度上限為 63 個字元。指定這個欄位,即可取得、更新或刪除具有指定值的訊息。如需使用範例,請參閱為已建立的郵件命名一文。

emojiReactionSummaries[]

object (EmojiReactionSummary)

僅供輸出。訊息中的表情符號回應摘要清單。

deletionMetadata

object (DeletionMetadata)

僅供輸出。關於已刪除訊息的資訊。系統會在您設定了 deleteTime 時刪除訊息。

卡片 ID

用於指定 Chat 應用程式的小工具。

JSON 表示法
{
  "cardId": string,
  "card": {
    object (Card)
  }
}
欄位
cardId

string

cardsV2 訊息而言為必填。此小工具的即時通訊應用程式指定識別碼。在某封郵件的範圍內。

card

object (Card)

資訊卡支援定義的版面配置、按鈕等互動式 UI 元素,以及圖片等互動式多媒體元素。這張資訊卡可顯示詳細資訊、收集使用者資訊,並引導使用者採取後續行動。

Annotation

與訊息純文字內文相關聯的註解。

純文字郵件內文範例:

Hello @FooBot how are you!"

相對應的註解中繼資料:

"annotations":[{
  "type":"USER_MENTION",
  "startIndex":6,
  "length":7,
  "userMention": {
    "user": {
      "name":"users/{user}",
      "displayName":"FooBot",
      "avatarUrl":"https://goo.gl/aeDtrS",
      "type":"BOT"
    },
    "type":"MENTION"
   }
}]
JSON 表示法
{
  "type": enum (AnnotationType),
  "length": integer,
  "startIndex": integer,

  // Union field metadata can be only one of the following:
  "userMention": {
    object (UserMentionMetadata)
  },
  "slashCommand": {
    object (SlashCommandMetadata)
  }
  // End of list of possible types for union field metadata.
}
欄位
type

enum (AnnotationType)

此註解的類型。

length

integer

此註解對應的純文字內文中的子字串長度。

startIndex

integer

與此註解對應的純文字內文作為起始索引 (以 0 為基礎)。

聯集欄位 metadata。關於註解的其他中繼資料。metadata 只能是下列其中一項:
userMention

object (UserMentionMetadata)

使用者提及的中繼資料。

slashCommand

object (SlashCommandMetadata)

斜線指令的中繼資料。

AnnotationType

註解類型。

列舉
ANNOTATION_TYPE_UNSPECIFIED 列舉的預設值。請勿使用。
USER_MENTION 系統已提及使用者。
SLASH_COMMAND 系統會叫用斜線指令。

UserMentionMetadata

使用者提及 (@) 的註解中繼資料。

JSON 表示法
{
  "user": {
    object (User)
  },
  "type": enum (Type)
}
欄位
user

object (User)

使用者提及。

type

enum (Type)

使用者提及類型。

類型

列舉
TYPE_UNSPECIFIED 列舉的預設值。請勿使用。
ADD 將使用者加入聊天室。
MENTION 在聊天室中提及使用者。

SlashCommandMetadata

斜線指令 (/) 的註解中繼資料。

JSON 表示法
{
  "bot": {
    object (User)
  },
  "type": enum (Type),
  "commandName": string,
  "commandId": string,
  "triggersDialog": boolean
}
欄位
bot

object (User)

已叫用指令的 Chat 應用程式。

type

enum (Type)

斜線指令的類型。

commandName

string

叫用斜線指令的名稱。

commandId

string (int64 format)

叫用斜線指令的指令 ID。

triggersDialog

boolean

指出斜線指令是否適用於對話方塊。

類型

列舉
TYPE_UNSPECIFIED 列舉的預設值。請勿使用。
ADD 將 Chat 應用程式新增至聊天室。
INVOKE 在聊天室中叫用斜線指令。

對話串

Google Chat 中的對話串。

JSON 表示法
{
  "name": string,
  "threadKey": string
}
欄位
name

string

執行緒的資源名稱。

範例:spaces/{space}/threads/{thread}

threadKey

string

選填欄位,不透明執行緒 ID。如要開始新增或新增至執行緒,請建立訊息並指定 threadKeythread.name。如需使用範例,請參閱開始或回覆郵件串

在其他要求中,此為輸出欄位。

動作回應

即時通訊應用程式用來設定回應回應方式的參數。

JSON 表示法
{
  "type": enum (ResponseType),
  "url": string,
  "dialogAction": {
    object (DialogAction)
  }
}
欄位
type

enum (ResponseType)

只能輸入。Chat 應用程式回應的類型。

url

string

只能輸入。用於驗證或設定的網址。(僅適用於 REQUEST_CONFIG 回應類型)。

dialogAction

object (DialogAction)

只能輸入。對對話方塊相關事件的回應。必須使用ResponseType.Dialog

回應類型

Chat 應用程式回應的類型。

列舉
TYPE_UNSPECIFIED 預設類型;系統會將其視為「NEW_MESSAGE」。
NEW_MESSAGE 在主題中以新訊息張貼訊息。
UPDATE_MESSAGE 更新 Chat 應用程式的訊息。這只適用於在訊息傳送者類型為 BOT 的 CARD_CLICKED 事件。
UPDATE_USER_MESSAGE_CARDS 請更新使用者訊息中的卡片。此回應僅適用於回應符合相符網址的 MESSAGE 事件,或訊息傳送者類型為 HUMAN 的 CARD_CLICKED 事件。系統會忽略文字。
REQUEST_CONFIG 私下要求使用者提供額外的驗證或設定。
DIALOG 呈現對話方塊

對話方塊

包含對話方塊和要求狀態碼。

JSON 表示法
{
  "actionStatus": {
    object (ActionStatus)
  },

  // Union field action can be only one of the following:
  "dialog": {
    object (Dialog)
  }
  // End of list of possible types for union field action.
}
欄位
actionStatus

object (ActionStatus)

只能輸入。叫用或提交對話方塊的要求狀態。必要時向使用者顯示狀態和訊息。例如發生錯誤或成功。

聯集欄位 action

action 只能是下列其中一個值:

dialog

object (Dialog)

只能輸入。要求的對話方塊

對話方塊

對話方塊的卡片內文周圍採用包裝函式。

JSON 表示法
{
  "body": {
    object (Card)
  }
}
欄位
body

object (Card)

只能輸入。以模組化方式呈現的對話方塊主體。Google Chat 應用程式不支援下列卡片實體:DateTimePickerOnChangeAction

動作狀態

表示叫用或提交對話方塊的要求狀態。

JSON 表示法
{
  "statusCode": enum (Code),
  "userFacingMessage": string
}
欄位
statusCode

enum (Code)

狀態碼。

userFacingMessage

string

告知使用者要求狀態的訊息。如未設定,系統會傳送以 statusCode 為基礎的一般訊息。

程式碼

gRPC API 的標準錯誤代碼。

有時可能適用多個錯誤代碼。服務應傳回最適用的特定錯誤代碼。例如,如果 OUT_OF_RANGEFAILED_PRECONDITION 代碼都適用,則最好使用前者。同樣地,請優先使用 NOT_FOUNDALREADY_EXISTS,而不是 FAILED_PRECONDITION

列舉
OK

非錯誤;於成功時傳回。

HTTP 對應:200 OK

CANCELLED

作業已取消,一般由呼叫者取消。

HTTP 對應:499 用戶端已關閉要求

UNKNOWN

不明的錯誤。舉例來說,如果從其他位址空間收到的 Status 值屬於這個位址空間中不明的錯誤空間,則可能會傳回這個錯誤。由 API 發出但未傳回充分錯誤資訊的錯誤,也可能會轉換為此錯誤。

HTTP 對應:500 內部伺服器錯誤

INVALID_ARGUMENT

用戶端指定了無效的引數。請注意,這與 FAILED_PRECONDITION 不同。INVALID_ARGUMENT 表示不論系統狀態為何 (例如格式錯誤的引數),發生問題的引數。

HTTP 對應:400 錯誤的要求

DEADLINE_EXCEEDED

期限於作業完成之前過期。針對變更系統狀態的作業,即使作業已成功完成,也可能傳回此錯誤。例如,來自伺服器的成功回應延遲時間可能已長到足以使期限過期。

HTTP 對應:504 閘道逾時

NOT_FOUND

找不到某些要求的實體 (例如檔案或目錄)。

伺服器開發人員注意事項:如果針對所有使用者類別 (例如逐步推出功能或未記錄的許可清單) 拒絕要求,系統可能會使用 NOT_FOUND。如果某些使用者 (例如以使用者為基礎的存取權控管) 中某些使用者的要求遭拒,則必須使用 PERMISSION_DENIED

HTTP 對應:404 找不到

ALREADY_EXISTS

用戶端嘗試建立的實體 (例如檔案或目錄) 已存在。

HTTP 對應:409 衝突

PERMISSION_DENIED

呼叫者沒有執行指定作業的權限。對於因耗用某些資源所導致的拒絕情形,不得使用 PERMISSION_DENIED (請針對這些錯誤改用 RESOURCE_EXHAUSTED)。如果無法識別呼叫者,不得使用 PERMISSION_DENIED (請針對這些錯誤改用 UNAUTHENTICATED)。此錯誤代碼並不表示要求有效,或是要求的實體已存在或是滿足其他先決條件。

HTTP 對應:403 禁止

UNAUTHENTICATED

要求沒有作業的有效驗證憑證。

HTTP 對應:401 未授權

RESOURCE_EXHAUSTED

已耗盡某些資源,或許是每位使用者的配額,或許是完整檔案系統空間不足。

HTTP 對應:429 太多要求

FAILED_PRECONDITION

作業已遭拒絕,因為系統不在執行作業所需的狀態下。例如要刪除的目錄非空白、rmdir 作業套用至非目錄等。

服務實作者可以根據下列指南在 FAILED_PRECONDITIONABORTEDUNAVAILABLE 之間做出選擇:(a) 如果用戶端只能重試失敗的呼叫,請使用 UNAVAILABLE。(b) 如果用戶端應在較高層級重試,請使用 ABORTED。例如,當用戶端指定的測試與設定失敗時,表示用戶端應重新啟動讀取-修改-寫入-序列。(c) 在已明確修正系統狀態之前,如果用戶端不應重試,請使用 FAILED_PRECONDITION。舉例來說,如果「rmdir」因目錄並非空白而失敗,則應傳回 FAILED_PRECONDITION,因為用戶端不應重試,除非從目錄中刪除檔案。

HTTP 對應:400 錯誤的要求

ABORTED

作業已取消,原因通常是排序器檢查失敗或交易取消等並行問題。

如要決定採用 FAILED_PRECONDITIONABORTED 還是 UNAVAILABLE,請參閱以上指南。

HTTP 對應:409 衝突

OUT_OF_RANGE

嘗試作業時超過有效範圍,例如搜尋或讀取超過檔案結尾。

INVALID_ARGUMENT 不同,此錯誤表示如果系統狀態變更則可修正的問題。例如,如果要求在不在 [0,2^32-1] 的範圍之內讀取的 32 位元檔案系統,系統會產生 INVALID_ARGUMENT,但如果要求從目前檔案大小以外的偏移值讀取,就會產生 OUT_OF_RANGE

FAILED_PRECONDITIONOUT_OF_RANGE 之間存在相差的重疊。我們建議在套用時採用 OUT_OF_RANGE (更具體的錯誤),以便在疊代空間的呼叫端輕鬆找到 OUT_OF_RANGE 錯誤,以偵測完成的時間。

HTTP 對應:400 錯誤的要求

UNIMPLEMENTED

未實作作業或作業在此服務中不受支援/未啟用。

HTTP 對應:501 未實作

INTERNAL

內部錯誤。這表示基礎系統預期的某些不變的情形已被打破。此錯誤代碼保留供嚴重錯誤使用。

HTTP 對應:500 內部伺服器錯誤

UNAVAILABLE

服務目前無法使用。這很有可能是暫時性條件,只要向輪詢進行重試即可修正。請注意,重試非冪等運算並不安全。

如要決定採用 FAILED_PRECONDITIONABORTED 還是 UNAVAILABLE,請參閱以上指南。

HTTP 對應:503 服務不可用

DATA_LOSS

無法復原的資料遺失或損毀。

HTTP 對應:500 內部伺服器錯誤

SlashCommand

Google Chat 中的斜線指令

JSON 表示法
{
  "commandId": string
}
欄位
commandId

string (int64 format)

叫用的斜線指令 ID。

相符網址

Chat 訊息中的相符網址。即時通訊應用程式可以預覽相符的網址。詳情請參閱預覽連結

JSON 表示法
{
  "url": string
}
欄位
url

string

僅供輸出。相符網址。

EmojiReactionSummary

以特定表情符號回應訊息的使用者人數。

JSON 表示法
{
  "emoji": {
    object (Emoji)
  },
  "reactionCount": integer
}
欄位
emoji

object (Emoji)

與回應相關的表情符號。

reactionCount

integer

使用相關表情符號的回應總數。

Deletion 中繼資料

關於已刪除訊息的資訊。系統會在您設定了 deleteTime 時刪除訊息。

JSON 表示法
{
  "deletionType": enum (DeletionType)
}
欄位
deletionType

enum (DeletionType)

表示刪除郵件的使用者。

刪除類型

刪除郵件的使用者以及刪除郵件的方式。

列舉
DELETION_TYPE_UNSPECIFIED 未使用這個值。
CREATOR 使用者刪除了自己的訊息。
SPACE_OWNER 聊天室擁有者已刪除訊息。
ADMIN 一位 Google Workspace 管理員刪除了這封郵件。
APP_MESSAGE_EXPIRY 即時通訊應用程式過期時,就會刪除自己的訊息。
CREATOR_VIA_APP 即時通訊應用程式代表使用者刪除了訊息。
SPACE_OWNER_VIA_APP 即時通訊應用程式代表聊天室擁有者刪除了訊息。

方法

create

建立訊息。

delete

刪除訊息。

get

傳回訊息。

list

列出來電者所屬聊天室中的訊息,包括已封鎖成員和聊天室中的訊息。

patch

更新訊息。

update

更新訊息。