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

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

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

`Space` 资源表示用户和 Chat 应用可以在其中发送消息、共享文件和协作的位置。Space聊天室有多种类型：

  • 私信 (DM) 是两位用户之间或用户与 Chat 应用之间的对话。
  • 群聊是三位或更多用户与 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