搜索和管理 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 Workspace 组织的管理 Chat 和聊天室对话 管理员权限。

以管理员身份调用 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(
    '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)

  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(
      '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()

  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