REST Resource: spaces

資源：聊天室

Google Chat 中的聊天室。聊天室是指兩位以上使用者之間的對話，或使用者與 Chat 擴充應用程式之間的一對一訊息。

JSON 表示法 
{
  "name": string,
  "type": enum (Type),
  "spaceType": enum (SpaceType),
  "singleUserBotDm": boolean,
  "threaded": boolean,
  "displayName": string,
  "externalUserAllowed": boolean,
  "spaceThreadingState": enum (SpaceThreadingState),
  "spaceDetails": {
    object (SpaceDetails)
  },
  "spaceHistoryState": enum (HistoryState),
  "importMode": boolean,
  "createTime": string,
  "lastActiveTime": string,
  "adminInstalled": boolean,
  "membershipCount": {
    object (MembershipCount)
  },
  "accessSettings": {
    object (AccessSettings)
  },
  "spaceUri": string,
  "sessionState": enum (SpaceSessionState),
  "sessionEnableTime": string,
  "importModeExpireTime": string,
  "customer": string,

  "predefinedPermissionSettings": enum (PredefinedPermissionSettings),
  "permissionSettings": {
    object (PermissionSettings)
  }
}
欄位
name

string

ID。聊天室的資源名稱。

格式：spaces/{space}

其中 {space} 代表系統指派的聊天室 ID。您可以呼叫 spaces.list() 方法，或從聊天室網址取得聊天室 ID。舉例來說，如果聊天室網址為 https://mail.google.com/mail/u/0/#chat/space/AAAAAAAAA，則聊天室 ID 為 AAAAAAAAA。
type
(deprecated)

enum (Type)

僅供輸出。已淘汰：請改用 spaceType。聊天室類型。
spaceType

enum (SpaceType)

(選用步驟) 空間類型。建立聊天室或更新聊天室類型時，必須提供這項資訊。僅供輸出其他用途。
singleUserBotDm

boolean

(選用步驟) 聊天室是否為 Chat 擴充應用程式與單一使用者之間的即時訊息。
threaded
(deprecated)

boolean

僅供輸出。已淘汰：請改用 spaceThreadingState。這個聊天室中的訊息是否以討論串形式呈現。
displayName

string

(選用步驟) 聊天室的顯示名稱。建立聊天室時，如果 spaceType 為 SPACE，則必須提供這個欄位。如果在建立聊天室或更新 displayName 時收到 ALREADY_EXISTS 錯誤訊息，請嘗試使用其他 displayName。Google Workspace 組織中現有的聊天室可能已使用這個顯示名稱。

如果是即時訊息，這個欄位可能為空白。

最多可使用 128 個半形字元。
externalUserAllowed

boolean

(選用步驟) 不可變動。這個聊天室是否允許任何 Google Chat 使用者加入。在 Google Workspace 機構中建立聊天室時輸入。在下列情況下建立聊天室時，請省略這個欄位：

  • 已驗證的使用者使用消費者帳戶 (非受管使用者帳戶)。根據預設，個人帳戶建立的聊天室允許任何 Google Chat 使用者加入。

如果是現有聊天室，這個欄位僅供輸出。
spaceThreadingState

enum (SpaceThreadingState)

僅供輸出。Chat 聊天室中的討論串狀態。
spaceDetails

object (SpaceDetails)

(選用步驟) 聊天室的詳細資料，包括說明和規則。
spaceHistoryState

enum (HistoryState)

(選用步驟) 這個聊天室中訊息和討論串的訊息記錄狀態。
importMode

boolean

(選用步驟) 這個聊天室是否在 Import Mode 中建立，做為將資料遷移至 Google Workspace 的一部分。匯入期間，使用者無法查看聊天室，直到匯入完成。

在Import Mode中建立聊天室需要使用者驗證。
createTime

string (Timestamp format)

(選用步驟) 不可變動。在 Chat 中建立的聊天室，則會顯示聊天室建立時間。這個欄位僅供輸出，除非用於匯入模式聊天室。

如果是匯入模式聊天室，請將這個欄位設為在來源中建立聊天室的歷來時間戳記，以保留原始建立時間。

只有在 spaceType 為 GROUP_CHAT 或 SPACE 時，輸出內容才會填入這項資訊。
lastActiveTime

string (Timestamp format)

僅供輸出。聊天室中最後一則訊息的時間戳記。
adminInstalled

boolean

僅供輸出。如果是含有 Chat 擴充應用程式的即時訊息 (DM) 聊天室，則取決於聊天室是否由 Google Workspace 管理員建立。管理員可以代表機構使用者，安裝 Chat 擴充應用程式並設定即時訊息。

如要支援管理員安裝，Chat 擴充應用程式必須具備即時訊息功能。
membershipCount

object (MembershipCount)

僅供輸出。已加入的會員人數 (依會員類型分組)。當 spaceType 為 SPACE、DIRECT_MESSAGE 或 GROUP_CHAT 時填入。
accessSettings

object (AccessSettings)

(選用步驟) 指定聊天室的存取權設定。只有在 spaceType 為 SPACE 時，系統才會填入資料。
spaceUri

string

僅供輸出。使用者存取聊天室的 URI。
sessionState

enum (SpaceSessionState)

僅供輸出。聊天室的工作階段狀態。
sessionEnableTime

string (Timestamp format)

僅供輸出。聊天室的工作階段支援狀態變更為「支援」的時間戳記。如果聊天室未啟用工作階段支援功能，則不設定。
importModeExpireTime

string (Timestamp format)

僅供輸出。如果聊天室仍處於匯入模式，系統會自動刪除聊天室的時間。

在匯入模式下建立的聊天室，必須在到期前使用 spaces.completeImport 退出此模式。

只有以匯入模式建立的聊天室，才會填入這個欄位。
customer

string

(選用步驟) 不可變動。聊天室網域的客戶 ID。只有在使用應用程式驗證建立聊天室，且 SpaceType 為 SPACE 時，才需要設定這個欄位，否則不應設定。

格式為 customers/{customer}，其中 customer 是 Admin SDK 客戶資源中的 id。私人應用程式也可以使用 customers/my_customer 別名，在與應用程式相同的 Google Workspace 機構中建立聊天室。

如果是即時訊息 (DM)，或聊天室是由非 Google Workspace 使用者建立，系統就不會填入這個欄位。
代表聊天室的權限設定。只有在 space_type 為 SPACE 時，系統才會填入資料。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位：
predefinedPermissionSettings

enum (PredefinedPermissionSettings)

(選用步驟) 僅供輸入。預先定義的空間權限集設定，僅在建立空間時輸入。如果不設定這個欄位，系統會建立協作空間。建立聊天室後，設定會填入「PermissionSettings」欄位。

設定預先定義的權限設定可支援：
permissionSettings

object (PermissionSettings)

(選用步驟) 現有聊天室的權限設定。用於更新確切聊天室權限設定的輸入內容，現有權限設定會遭到取代。輸出內容會列出目前的權限設定。

讀取及更新權限設定支援：
互斥欄位結束。

類型

已淘汰：請改用 SpaceType。

列舉
TYPE_UNSPECIFIED 保留。
ROOM 兩位以上真人之間的對話。
DM 使用者與 Chat 應用程式之間的 1 對 1 即時訊息，所有訊息都採用平面結構。請注意，這不包括兩位使用者之間的即時訊息。

SpaceType

空間類型。建立或更新聊天室時，必須提供這個欄位。僅供輸出其他用途。

列舉
SPACE_TYPE_UNSPECIFIED 保留。
SPACE 使用者可以在這裡傳送訊息、分享檔案及協作。SPACE可包含 Chat 擴充應用程式。
GROUP_CHAT 3 人以上的群組對話。GROUP_CHAT可包含 Chat 擴充應用程式。
DIRECT_MESSAGE 兩位使用者之間或使用者與 Chat 擴充應用程式之間的 1:1 訊息。

SpaceThreadingState

指定 Chat 聊天室中的討論串狀態類型。

列舉
SPACE_THREADING_STATE_UNSPECIFIED 保留。
THREADED_MESSAGES 支援訊息討論串的聊天室。使用者回覆訊息時，可以在討論串中回覆，這樣回覆內容就會保留在原始訊息的上下文中。
GROUPED_MESSAGES 依主題分類對話的具名聊天室。主題和回覆會歸在一組。
UNTHREADED_MESSAGES

不支援訊息討論串的聊天室。這個聊天室討論串狀態僅適用於特殊情況，包括：

  • 刻意關閉討論串功能的常設會議即時通訊。
  • 2022 年前建立的舊版群組對話。

SpaceDetails

聊天室的詳細資料，包括說明和規則。

JSON 表示法 
{
  "description": string,
  "guidelines": string
}
欄位
description

string

(選用步驟) 空間說明。例如，說明聊天室的討論主題、功能用途或參與者。

最多支援 4,096 個半形字元。
guidelines

string

(選用步驟) 聊天室的規則、期望和禮儀。

最多可輸入 5,000 個字元。

HistoryState

訊息和聊天室的記錄狀態。指定訊息和對話討論串建立後要保留多久。

列舉
HISTORY_STATE_UNSPECIFIED 預設值。請勿使用。
HISTORY_OFF 記錄功能已關閉。訊息和討論串會保留 24 小時。
HISTORY_ON 開啟記錄。貴機構的保管箱資料保留規則會指定訊息和討論串的保留時間。

MembershipCount

代表聊天室的成員數量，並依類別分組。

JSON 表示法 
{
  "joinedDirectHumanUserCount": integer,
  "joinedGroupCount": integer
}
欄位
joinedDirectHumanUserCount

integer

僅供輸出。直接加入聊天室的人類使用者人數，不包括透過加入群組而加入的使用者。
joinedGroupCount

integer

僅供輸出。直接加入聊天室的所有群組數量。

AccessSettings

代表聊天室的存取權設定。

JSON 表示法 
{
  "accessState": enum (AccessState),
  "audience": string,
  "accessPermissionSettings": {
    object (AccessPermissionSettings)
  }
}
欄位
accessState

enum (AccessState)

僅供輸出。指出聊天室的存取狀態。
audience

string

(選用步驟) 目標對象的資源名稱，這類對象可搜尋及加入聊天室，並預覽聊天室中的訊息。如未設定，則只有個別受邀或加入聊天室的使用者或 Google 群組可以存取。詳情請參閱「讓目標對象可搜尋聊天室」。

格式：audiences/{audience}

如要使用 Google Workspace 機構的預設目標對象，請設為 audiences/default。

讀取目標對象支援：

如果將 chat.bot 範圍與應用程式驗證搭配使用，這個欄位就不會填入資料。

設定目標對象時，必須驗證使用者。
accessPermissionSettings

object (AccessPermissionSettings)

(選用步驟) 存取聊天室的權限設定。

如要在建立聊天室時設定目標對象，請在要求中指定 accessSettings.audience 欄位。

AccessState

代表聊天室的存取狀態。

列舉
ACCESS_STATE_UNSPECIFIED 存取狀態不明或這個 API 不支援。
PRIVATE 只有由其他使用者或 Google Workspace 管理員個別新增或邀請的使用者或 Google 群組，才能搜尋及存取聊天室。
DISCOVERABLE

聊天室管理員已授予目標對象聊天室存取權。如果使用者或 Google 群組已個別加入或受邀加入聊天室，也可以搜尋及存取聊天室。詳情請參閱「讓特定使用者可搜尋聊天室」。

建立可自由加入的聊天室時，必須驗證使用者身分。

AccessPermissionSettings

存取聊天室的權限設定。

JSON 表示法 
{
  "discoverSpaceSetting": {
    object (AccessPermissionSetting)
  },
  "joinSpaceSetting": {
    object (AccessPermissionSetting)
  },
  "viewSpaceMembershipSetting": {
    object (AccessPermissionSetting)
  }
}
欄位
discoverSpaceSetting

object (AccessPermissionSetting)

(選用步驟) 用於探索聊天室的存取權限設定。
joinSpaceSetting

object (AccessPermissionSetting)

(選用步驟) 加入聊天室的存取權限設定。
viewSpaceMembershipSetting

object (AccessPermissionSetting)

(選用步驟) 查看聊天室成員資格的存取權限設定。更新可查看聊天室成員資格的使用者時，必須在更新遮罩和要求主體中，與 PermissionSettings.view_space_membership 一併指定。將檢視權限授予目標對象時，您也必須在同一要求中將 PermissionSettings.view_space_membership 授予所有成員。如要移除現有的目標對象 (例如，將檢視權限限制為僅限聊天室管理員或助理管理員)，請指定空白的 AccessPermissionSetting (不含 principals)。

AccessPermissionSetting

存取權限設定。

JSON 表示法 
{
  "principals": [
    {
      object (Principal)
    }
  ]
}
欄位
principals[]

object (Principal)

(選用步驟) 未排序的清單。這項權限允許的主體。

主體

代表已獲授予存取權實體的主體。

JSON 表示法 
{

  "audience": {
    object (Audience)
  }
}
欄位
主體類型。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位：
audience

object (Audience)

目標對象。
互斥欄位結束。

目標對象

Google Chat 中的目標對象。目標對象是指 Google Workspace 組織內的一群使用者，由管理員定義。目標對象可用來設定資源的存取權和瀏覽權限，例如讓特定使用者群組可搜尋到聊天室。

詳情請參閱「目標對象」和「讓目標對象可搜尋聊天室」。

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

string

可搜尋或加入聊天室的目標對象資源名稱。詳情請參閱「讓目標對象可搜尋到聊天室」。格式：audiences/{audience}

如要使用 Google Workspace 機構的預設目標對象，請設為 audiences/default。

PredefinedPermissionSettings

預先定義的權限設定，只能在建立具名聊天室時指定。我們日後可能會新增更多設定。如要進一步瞭解具名聊天室的權限設定，請參閱「瞭解聊天室」。

列舉
PREDEFINED_PERMISSION_SETTINGS_UNSPECIFIED 未指定。請勿使用。
COLLABORATION_SPACE 將聊天室設為協作空間，讓所有成員都能張貼訊息。
ANNOUNCEMENT_SPACE 將聊天室設為公告聊天室，只有聊天室管理員可以張貼訊息。

PermissionSettings

更新現有名稱聊天室時，可指定的權限設定。

如要在建立聊天室時設定權限，請在要求中指定 PredefinedPermissionSettings 欄位。

JSON 表示法 
{
  "manageMembersAndGroups": {
    object (PermissionSetting)
  },
  "modifySpaceDetails": {
    object (PermissionSetting)
  },
  "toggleHistory": {
    object (PermissionSetting)
  },
  "useAtMentionAll": {
    object (PermissionSetting)
  },
  "manageApps": {
    object (PermissionSetting)
  },
  "manageWebhooks": {
    object (PermissionSetting)
  },
  "postMessages": {
    object (PermissionSetting)
  },
  "replyMessages": {
    object (PermissionSetting)
  },
  "viewSpaceMembership": {
    object (PermissionSetting)
  }
}
欄位
manageMembersAndGroups

object (PermissionSetting)

(選用步驟) 管理聊天室成員和群組的設定。
modifySpaceDetails

object (PermissionSetting)

(選用步驟) 更新聊天室名稱、顯示圖片、說明和規範的設定。
toggleHistory

object (PermissionSetting)

(選用步驟) 開啟或關閉聊天室記錄的設定。
useAtMentionAll

object (PermissionSetting)

(選用步驟) 在聊天室中使用 @all 的設定。
manageApps

object (PermissionSetting)

(選用步驟) 管理聊天室中應用程式的設定。
manageWebhooks

object (PermissionSetting)

(選用步驟) 管理聊天室中 Webhook 的設定。
postMessages

object (PermissionSetting)

僅供輸出。在聊天室中張貼訊息的設定。
replyMessages

object (PermissionSetting)

(選用步驟) 在聊天室中回覆訊息的設定。
viewSpaceMembership

object (PermissionSetting)

(選用步驟) 查看聊天室成員的設定。更新可查看聊天室成員資格的使用者時，必須在更新遮罩和要求主體中，與 AccessPermissionSettings.view_space_membership_setting 一併指定。如要限制特定角色 (例如僅限聊天室管理員或助理管理員) 的檢視權限，請在這裡指定所需角色權限，並在同一要求中提供空白的 AccessPermissionSettings.view_space_membership_setting。如果在 AccessPermissionSettings.view_space_membership_setting 中設定了目標對象，則必須將這項設定授予所有成員。

PermissionSetting

代表聊天室權限設定。

JSON 表示法 
{
  "managersAllowed": boolean,
  "membersAllowed": boolean,
  "assistantManagersAllowed": boolean
}
欄位
managersAllowed

boolean

(選用步驟) 聊天室擁有者 (ROLE_MANAGER) 是否具備這項權限。
membersAllowed

boolean

(選用步驟) 基本聊天室成員 (ROLE_MEMBER) 是否具備這項權限。
assistantManagersAllowed

boolean

(選用步驟) 聊天室管理員 (ROLE_ASSISTANT_MANAGER) 是否具備這項權限。

SpaceSessionState

聊天室的工作階段狀態。

列舉
SPACE_SESSION_STATE_UNSPECIFIED 未指定。請勿使用。
NOT_SUPPORTED 聊天室不支援工作階段。
THREAD 聊天室支援以討論串為基礎的工作階段。

方法

completeImport

 完成指定聊天室的匯入程序，並向使用者顯示。

create

 建立聊天室。

delete

 刪除指定聊天室。

findDirectMessage

 傳回與指定使用者現有的即時訊息。

findGroupChats

 傳回所有 spaceType == GROUP_CHAT 聊天室，其人類成員僅包含發出呼叫的使用者，以及 FindGroupChatsRequest.users 中指定的使用者。

get

 傳回聊天室的詳細資料。

list

 列出呼叫端所屬的聊天室。

patch

 更新聊天室。
傳回 Google Workspace 機構中的聊天室清單。

setup

 建立聊天室，並將指定使用者加入其中。