搜索和管理 Google Workspace 组织的 Google Chat 聊天室

本指南介绍了 Google Workspace 管理员如何使用 Google Chat API 的 Space 资源中的 search() 方法来管理组织中的命名空间并执行管理任务。

作为 Google Workspace 管理员，您只能使用 Chat API 管理已命名的聊天室，这些聊天室定义为 SPACE 的 SpaceType。命名聊天室是持久存在的聊天室，用户可以在其中发送消息、共享文件和协作。您无法使用 Chat API 管理私信 (DM) 或群聊。

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() 方法查找不活跃的聊天室，然后使用 useAdminAccess 参数通过 delete() 方法删除这些聊天室。

不活跃的 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