Method: spaces.search

傳回 Google Workspace 機構中的空間清單。如需範例，請參閱「搜尋及管理聊天室」。

如果將 useAdminAccess 設為 false，搜尋結果只會顯示通話使用者已加入的聊天室。如要使用管理員權限進行搜尋，請將 useAdminAccess 設為 true。開發人員預覽版提供將 useAdminAccess 設為 false 的選項。

支援下列類型的驗證：

  • 使用者驗證，並使用下列其中一個授權範圍：

    • https://www.googleapis.com/auth/chat.spaces.readonly
    • https://www.googleapis.com/auth/chat.spaces

  • 具備管理員權限的使用者驗證，以及下列其中一個授權範圍：

    • https://www.googleapis.com/auth/chat.admin.spaces.readonly
    • https://www.googleapis.com/auth/chat.admin.spaces

HTTP 要求

GET https://chat.googleapis.com/v1/spaces:search

這個網址使用 gRPC 轉碼語法。

查詢參數

參數
useAdminAccess

boolean

時，方法會使用使用者的 Google Workspace 管理員權限執行。true

通話使用者必須是具備「管理即時通訊和聊天室對話」權限的 Google Workspace 管理員。

需要 chat.admin.spaces.readonly 或 chat.admin.spaces OAuth 2.0 範圍。

開發人員預覽版提供將 useAdminAccess 設為 false 的功能。
pageSize

integer

要傳回的空間數量上限。服務傳回的產品數量可能會少於這個值。

如未指定，最多會傳回 100 個空間。

最大值為 1000。如果使用超過 1000 的值，系統會自動變更為 1000。
pageToken

string

這是從先前的搜尋空間呼叫接收到的權杖。提供此參數即可擷取後續網頁。

進行分頁時，提供的所有其他參數應與提供網頁權杖的呼叫相符。將不同值傳遞至其他參數可能會導致非預期的結果。
query

string

必填。搜尋查詢。

當 useAdminAccess 設為 true 時，您可以使用下列參數進行搜尋：

  • createTime
  • customer
  • displayName
  • externalUserAllowed
  • lastActiveTime
  • spaceHistoryState
  • spaceType

如果 useAdminAccess 設為 false：

  • displayName
  • externalUserAllowed

createTime 和 lastActiveTime 接受 RFC-3339 格式的時間戳記，支援的比較運算子包括：=、<、>、<=、>=。

如果 useAdminAccess 設為 true，則必須提供 customer，用來指出要從哪個客戶擷取聊天室。目前唯一支援的值是 customers/my_customer。

displayName 只接受 HAS (:) 運算子。要比對的文字會先轉換為符記，然後系統會不區分大小寫，獨立比對每個符記是否為空間 displayName 中任何位置的子字串。舉例來說，Fun Eve 與 Fun event 或 The evening was fun 相符，但與 notFun event 或 even 不相符。如果 useAdminAccess 設為 false，就必須使用 displayName 擷取有意義的結果。否則，預設行為是傳回空白回應。

externalUserAllowed 可接受 true 或 false。

spaceHistoryState 只接受 space 資源 historyState 欄位的值。

如果 useAdminAccess 設為 true，則必須提供 spaceType，且唯一有效值為 SPACE。

不同欄位之間僅支援 AND 運算子。有效範例為 spaceType = "SPACE" AND displayName:"Hello"，無效範例為 spaceType = "SPACE" OR displayName:"Hello"。

在同一個欄位中，spaceType 不支援 AND 或 OR 運算子。displayName、「spaceHistoryState」和「externalUserAllowed」僅支援 OR 運算子。lastActiveTime 和 createTime 支援 AND 和 OR 運算子。AND 只能用來表示間隔，例如 lastActiveTime < "2022-01-01T00:00:00+00:00" AND lastActiveTime > "2023-01-01T00:00:00+00:00"。

如果 useAdminAccess 設為 true，下列範例查詢就有效：

customer = "customers/my_customer" AND spaceType = "SPACE"

customer = "customers/my_customer" AND spaceType = "SPACE" AND
displayName:"Hello World"

customer = "customers/my_customer" AND spaceType = "SPACE" AND
(lastActiveTime < "2020-01-01T00:00:00+00:00" OR lastActiveTime >
"2022-01-01T00:00:00+00:00")

customer = "customers/my_customer" AND spaceType = "SPACE" AND
(displayName:"Hello World" OR displayName:"Fun event") AND
(lastActiveTime > "2020-01-01T00:00:00+00:00" AND lastActiveTime <
"2022-01-01T00:00:00+00:00")

customer = "customers/my_customer" AND spaceType = "SPACE" AND
(createTime > "2019-01-01T00:00:00+00:00" AND createTime <
"2020-01-01T00:00:00+00:00") AND (externalUserAllowed = "true") AND
(spaceHistoryState = "HISTORY_ON" OR spaceHistoryState = "HISTORY_OFF")

如果 useAdminAccess 設為 false，下列範例查詢就有效：

displayName:"Hello World"

(displayName:"Hello" OR displayName:"Fun")

(externalUserAllowed = "true") // Returns an empty response.

(externalUserAllowed = "true" AND displayName:"Hello")
orderBy

string

(選用步驟) 聊天室清單的排序方式。

支援的排序依據屬性如下：

  • membershipCount.joined_direct_human_user_count：直接加入聊天室的人類使用者人數。
  • lastActiveTime：表示最後一個符合資格的項目加入這個空間任何主題的時間。
  • createTime：表示聊天室的建立時間。

如果 useAdminAccess 為 false，則僅支援 createTime 和 relevance 排序。在非管理員搜尋中，這些欄位僅支援 DESC。

有效的排序作業值如下：

  • ASC 表示遞增。預設值。

  • DESC 代表遞減。

useAdminAccess 設為 true 時支援的語法如下：

  • membershipCount.joined_direct_human_user_count DESC
  • membershipCount.joined_direct_human_user_count ASC
  • lastActiveTime DESC
  • lastActiveTime ASC
  • createTime DESC
  • createTime ASC

如果 useAdminAccess 設為 false：

  • createTime DESC
  • relevance DESC

要求主體

要求主體必須為空白。

回應主體

回應會提供與搜尋聊天室要求相符的聊天室清單。

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "spaces": [
    {
      object (Space)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer,
  "results": [
    {
      object (SearchSpaceResult)
    }
  ]
}
欄位
spaces[]
(deprecated)

object (Space)

已淘汰：請改用新的 results 欄位。所要求空間的頁面。只有在 useAdminAccess 設為 true 時，才會填入這個欄位，並已淘汰，改用新的 results 欄位。
nextPageToken

string

可用於擷取下一頁的權杖。如果這個欄位留空，表示沒有後續網頁。
totalSize

integer

所有頁面中符合查詢條件的空間總數。如果結果超過 10,000 個空格，這個值就是預估值。
results[]

object (SearchSpaceResult)

僅供輸出。

符合查詢的搜尋結果清單。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.admin.spaces
  • https://www.googleapis.com/auth/chat.admin.spaces.readonly

詳情請參閱授權指南。

SearchSpaceResult

空間搜尋的單一結果項目。

JSON 表示法 
{
  "space": {
    object (Space)
  }
}
欄位
space

object (Space)

僅供輸出。相符的聊天室。