本頁面由 Cloud Translation API 翻譯而成。

搜尋及管理 Google Workspace 機構的 Google Chat 聊天室

本指南說明 Google Workspace 管理員如何在 Google Chat API 的 Space 資源上使用 search() 方法，管理貴機構中的命名聊天室並執行管理工作。

Google Workspace 管理員只能使用 Chat API 管理命名空間，這類空間會定義為 SPACE 的 SpaceType。命名聊天室是持續存在的空間，可供使用者傳送訊息、共用檔案和協作。您無法使用 Chat API 管理直接訊息 (DM) 或群組即時通訊。

Space 資源代表使用者和 Chat 應用程式可用於傳送訊息、共用檔案和協作的場所。聊天室分為以下幾種類型：

即時訊息 (DM) 是指兩位使用者之間，或使用者與 Chat 應用程式之間的對話。
群組通訊是指三位以上使用者與 Chat 應用程式之間的對話。
命名聊天室是持續存在的空間，可供使用者傳送訊息、分享檔案和協作。

Google Workspace 管理員可以使用 Chat API 搜尋及管理貴機構中的命名聊天室，方法如下：

稽核機構中的聊天室。您可以使用 search() 方法，擷取組織內所有空間的清單，並取得每個空間的詳細設定和中繼資料，例如建立日期、上次活動日期、成員人數、歷史記錄設定狀態，以及邀請外部訪客的功能。
找出並刪除閒置的聊天室：您可以使用 search() 方法，找出自指定日期和時間起未使用的空間，然後刪除這些空間。如需進一步瞭解相關資訊和程式碼範例，請參閱「尋找並刪除閒置空間」。
根據搜尋條件匯出聊天室清單您可以使用 search() 方法，擷取符合 query 中指定條件的空間清單，並將結果匯出為 CSV 檔案進行分析。
尋找並與聊天室管理員聯絡。您可以使用 search() 方法，擷取機構中的所有聊天室清單，然後使用 members.list() 方法擷取所有聊天室管理員成員清單。
尋找沒有指定管理員的聊天室您可以使用 search() 方法擷取機構中的所有聊天室清單，然後使用 members.list() 方法擷取沒有任何管理員的聊天室清單。

必要條件

Python

具備 Google Chat 存取權的 Google Workspace 企業或進階版帳戶。

設定環境：
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用並設定 Google Chat API，並為 Chat 應用程式提供名稱、圖示和說明。
- 安裝 Python Google API 用戶端程式庫。
- 為電腦版應用程式建立 OAuth 用戶端 ID 憑證。如要執行本指南中的範例，請將憑證儲存為名為 client_secrets.json 的 JSON 檔案，並儲存至本機目錄。
選擇支援使用者驗證的授權範圍。

您必須具備 Google Workspace 組織的「管理即時通訊和聊天室對話」管理員權限。

以管理員身分呼叫 Google Chat API

如要以具備管理員權限的使用者身分進行驗證，您必須在要求中傳遞下列資訊：

指定支援使用具有管理員權限的使用者驗證的授權範圍。
將 useAdminAccess 欄位設為 true。

本節提供以下範例，說明如何以管理員身分呼叫 Chat API：

呼叫 search() 方法，搜尋聊天室。
找出並刪除組織中的閒置空間，方法是呼叫 search() 方法以傳回閒置空間清單，然後呼叫 delete() 方法來刪除這些空間。

搜尋貴機構中的聊天室

本範例說明 Google Workspace 管理員如何在 Chat API 的 Space 資源上使用 search() 方法，根據指定條件搜尋機構中的聊天室。

如要使用使用者驗證和管理員權限呼叫 search() 方法，您必須在要求中指定下列項目：

指定 chat.admin.spaces 或 chat.admin.spaces.readonly 授權範圍。
指定 useAdminAccess=true。
指定搜尋 query 參數來篩選結果：
- customer = "customers/my_customer"：必要，唯一支援的值為 customers/my_customer
- spaceType = "SPACE" - 必要，唯一支援的值為 SPACE
- 視需要加入一或多個額外查詢，進一步篩選聊天室搜尋結果，例如顯示名稱中的關鍵字 (displayName)、建立日期 (createTime)，或根據聊天室活動 (lastActiveTime)。

下列程式碼示範如何使用管理員權限搜尋顯示名稱含有「Hello」和「World」的任何組合型別的聊天室：

Python

在工作目錄中，建立名為 search_spaces_for_hello_world.py 的檔案。

在 search_spaces_for_hello_world.py 中加入以下程式碼：

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = [
  'https://www.googleapis.com/auth/chat.admin.spaces.readonly',
]

def main():
# Authenticate with Google Workspace
# and get user authorization.
flow = InstalledAppFlow.from_client_secrets_file(
    'client_secrets.json',
    SCOPES,
)
creds = flow.run_local_server()

# Build a service endpoint for Chat API.
chat = build('chat', 'v1', credentials=creds)

spaces = []
page_token = ''

# Search for all spaces.
while True:
  result = (
      chat.spaces()
      .search(
          useAdminAccess=True,
          query=(
            'customer = "customers/my_customer"'
            'AND spaceType = "SPACE"'
            'AND displayName:"Hello World"'
            )
pageToken=page_token,
      )
      .execute()
  )
  if 'spaces' not in result:
    print('No spaces found named Hello World.')
    return
  spaces.extend(result['spaces'])
  if 'nextPageToken' in result:
    page_token = result['nextPageToken']
  else:
    break

print(str(len(spaces)) + ' spaces found:')
# Prints the list of spaces.
print(spaces)

在工作目錄中建構並執行範例：
```
python3 search_spaces_for_hello_world.py
```

找出並刪除閒置的聊天室

本範例說明 Google Workspace 管理員如何在 Chat API 的 Space 資源上使用 search() 方法，找出未使用的聊天室，然後使用 delete() 方法搭配 useAdminAccess 參數來刪除這些聊天室。

閒置的 Google Chat 聊天室 (不再活躍使用的聊天室) 可能會佔用寶貴的儲存空間，並造成使用者介面雜亂。管理員可以使用 search() 方法，找出自指定日期和時間 (例如兩個月前) 起未使用的空間。列舉空間清單後，管理員就可以對這些空間採取行動，例如更新或刪除。

如要搜尋未使用的空間清單，然後使用使用者驗證和管理員權限刪除這些空間，請在要求中傳遞以下內容：

如要搜尋未啟用的聊天室，請指定下列項目：
- 指定 chat.admin.spaces 或 chat.admin.spaces.readonly 授權範圍。
- 對 Spaces 資源呼叫 search() 方法。
- 將 INACTIVE_SPACE_DEADLINE 設為決定要傳回的空格上次活動的日期和時間。
- 指定 useAdminAccess=true。
- 指定搜尋 query 參數來篩選結果：
  - customer = "customers/my_customer" - 必要，唯一支援的值為 customers/my_customer
  - spaceType = "SPACE" - 必要，唯一支援的值為 SPACE
  - lastActiveTime：如要篩選要求，只傳回無效的聊天室，請指定 lastActiveTime
如要從搜尋結果中刪除停用的聊天室，請指定下列項目：
- 指定 chat.admin.delete 授權範圍。
- 對 Spaces 資源呼叫 delete() 方法。
- 指定 useAdminAccess=true。

以下程式碼示範如何搜尋並刪除未使用的空間：

Python

在工作目錄中，建立名為 find_and_delete_inactive_spaces.py 的檔案。

在 find_and_delete_inactive_spaces.py 中加入以下程式碼：


from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = [
    'https://www.googleapis.com/auth/chat.admin.spaces.readonly',
    'https://www.googleapis.com/auth/chat.admin.delete',
]

# Any spaces that have not been active since this time will be deleted.
INACTIVE_SPACE_DEADLINE = '"INACTIVE_DATE"'

def main():
  # Authenticate with Google Workspace
  # and get user authorization.
  flow = InstalledAppFlow.from_client_secrets_file(
      'client_secrets.json',
      SCOPES,
  )
  creds = flow.run_local_server()

  # Build a service endpoint for Chat API.
  chat = build('chat', 'v1', credentials=creds)

  spaces = []
  page_token = ''

  # Search for all inactive spaces.
  while True:
    result = (
        chat.spaces()
        .search(
            useAdminAccess=True,
            query=(
                'customer = "customers/my_customer" AND spaceType = "SPACE" AND'
                ' lastActiveTime < '
            )
            + INACTIVE_SPACE_DEADLINE,
            pageToken=page_token,
        )
        .execute()
    )
    if 'spaces' not in result:
      print('No inactive spaces found.')
      return
    spaces.extend(result['spaces'])
    if 'nextPageToken' in result:
      page_token = result['nextPageToken']
    else:
      break

  print(str(len(spaces)) + ' inactive spaces found:')
  # Prints the list of inactive spaces.
  print(spaces)

  # Delete all inactive spaces.
  for space in spaces:
    (
        chat.spaces()
        .delete(
            useAdminAccess=True,
            name=space['name'],
        )
        .execute()
    )
    print(
        'Deleted space: '
        + space['displayName']
        + ', Resource Name: '
        + space['name']
    )

if __name__ == '__main__':
  main()

在程式碼中，將 INACTIVE_DATE 替換為 YYYY-MM-DDTHH:MM:SS+HH:MM 格式的日期和時間。例如「2024-06-01T00:00:00+00:00」。

在工作目錄中建構並執行範例：

python3 find_and_delete_inactive_spaces.py

搜尋及管理 Google Workspace 機構的 Google Chat 聊天室

必要條件

Python

以管理員身分呼叫 Google Chat API

搜尋貴機構中的聊天室

Python

找出並刪除閒置的聊天室

Python

相關主題