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

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

Google Workspace 管理員只能使用 Chat API 管理具名聊天室，也就是SpaceTypeSPACE。具名聊天室是持續存在的空間，可供使用者傳送訊息、分享檔案及協作。您無法使用 Chat API 管理直接訊息或群組即時通訊。

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

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

Google Workspace 管理員可以使用 Chat API，透過下列方式搜尋及管理機構中的具名聊天室：

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

必要條件

Python

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

以管理員身分呼叫 Google Chat API

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

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

本節將顯示下列範例，說明如何以管理員身分呼叫 Chat API：

搜尋貴機構的聊天室

本範例說明 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

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

  2. 在 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(
    'credentials.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)

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

    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

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

  2. 在 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(
      'credentials.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()

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

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

    python3 find_and_delete_inactive_spaces.py