Tìm và quản lý phòng Google Chat cho tổ chức của bạn trên Google Workspace

Hướng dẫn này giải thích cách quản trị viên Google Workspace có thể sử dụng phương thức search() trên tài nguyên Space của API Google Chat để quản lý các không gian có tên trên tổ chức của họ và thực hiện các nhiệm vụ quản trị.

Là quản trị viên Google Workspace, bạn chỉ có thể sử dụng Chat API để quản lý các không gian có tên. Các không gian này được xác định là một SpaceType của SPACE. Không gian được đặt tên là những nơi ổn định để mọi người gửi tin nhắn, chia sẻ tệp và cộng tác. Bạn không thể sử dụng API Chat để quản lý tin nhắn trực tiếp (DM) hoặc cuộc trò chuyện nhóm.

Tài nguyên Space đại diện cho một nơi mà mọi người và ứng dụng Chat có thể gửi tin nhắn, chia sẻ tệp và cộng tác. Có một số loại không gian:

  • Tin nhắn trực tiếp (DM) là cuộc trò chuyện giữa hai người dùng hoặc một người dùng và ứng dụng Chat.
  • Cuộc trò chuyện nhóm là cuộc trò chuyện giữa 3 người dùng trở lên và ứng dụng Chat.
  • Không gian được đặt tên là những nơi ổn định để mọi người gửi tin nhắn, chia sẻ tệp và cộng tác.

Là quản trị viên Google Workspace, bạn có thể sử dụng Chat API để tìm kiếm và quản lý các không gian có tên trong tổ chức của mình theo những cách sau:

  • Kiểm tra không gian trong tổ chức. Khi sử dụng phương thức search(), bạn có thể truy xuất danh sách tất cả không gian trong một tổ chức, trong đó có thông tin chi tiết về chế độ cài đặt và siêu dữ liệu của từng không gian, chẳng hạn như ngày tạo, ngày hoạt động gần đây nhất, số lượng thành viên, trạng thái của chế độ cài đặt nhật ký và khả năng mời khách bên ngoài.
  • Tìm và xoá những không gian không hoạt động. Bằng cách sử dụng phương thức search(), bạn có thể tìm thấy những không gian chưa được sử dụng kể từ một ngày và giờ cụ thể, sau đó xoá chúng. Để biết thêm thông tin chi tiết và mã mẫu, hãy xem bài viết Tìm và xoá không gian không hoạt động.
  • Xuất danh sách không gian dựa trên tiêu chí tìm kiếm. Khi sử dụng phương thức search(), bạn có thể truy xuất danh sách các không gian đáp ứng các tiêu chí được chỉ định trong query và xuất kết quả sang tệp CSV để phân tích.
  • Tìm và liên hệ với người quản lý không gian. Khi sử dụng phương thức search(), bạn có thể truy xuất danh sách tất cả không gian trong một tổ chức, sau đó sử dụng phương thức members.list() để truy xuất danh sách tất cả thành viên không gian là người quản lý.
  • Tìm những không gian chưa có người quản lý được chỉ định. Khi sử dụng phương thức search(), bạn có thể truy xuất danh sách tất cả không gian trong một tổ chức, sau đó sử dụng phương thức members.list() để truy xuất danh sách không gian không có người quản lý nào.

Điều kiện tiên quyết

Python

Gọi API Google Chat với tư cách quản trị viên

Để xác thực dưới dạng người dùng có quyền quản trị, bạn phải truyền những thông tin sau vào yêu cầu của mình:

  • Chỉ định một phạm vi uỷ quyền hỗ trợ việc sử dụng tính năng xác thực người dùng bằng đặc quyền quản trị.
  • Đặt trường useAdminAccess thành true.

Phần này trình bày các ví dụ sau đây về cách gọi Chat API với tư cách là quản trị viên:

Tìm kiếm không gian trong tổ chức của bạn

Ví dụ này giải thích cách quản trị viên Google Workspace có thể sử dụng phương thức search() trên tài nguyên Space của Chat API để tìm kiếm không gian trên một tổ chức dựa trên các tiêu chí đã chỉ định.

Để gọi phương thức search() bằng quy trình xác thực người dùng và quyền của quản trị viên, bạn phải chỉ định những thông tin sau trong yêu cầu:

  • Chỉ định phạm vi uỷ quyền chat.admin.spaces hoặc chat.admin.spaces.readonly.
  • Chỉ định useAdminAccess=true.
  • Chỉ định các tham số tìm kiếm query để lọc kết quả:
    • customer = "customers/my_customer" – bắt buộc và giá trị duy nhất được hỗ trợ là customers/my_customer
    • spaceType = "SPACE" – bắt buộc và giá trị duy nhất được hỗ trợ là SPACE
    • Một hoặc nhiều cụm từ tìm kiếm bổ sung (không bắt buộc) để lọc thêm nội dung tìm kiếm trong không gian, chẳng hạn như từ khoá trong tên hiển thị (displayName), ngày tạo (createTime) hoặc dựa trên hoạt động trong không gian (lastActiveTime).

Mã sau đây cho thấy ví dụ về cách sử dụng đặc quyền quản trị để tìm không gian có tên hiển thị chứa "Hello" và "World", theo bất kỳ tổ hợp nào:

Python

  1. Trong thư mục đang hoạt động, hãy tạo một tệp có tên là search_spaces_for_hello_world.py.

  2. Thêm mã sau vào 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. Trong thư mục đang hoạt động, hãy tạo bản dựng và chạy mẫu:

    python3 search_spaces_for_hello_world.py

Tìm và xoá không gian không hoạt động

Ví dụ này giải thích cách quản trị viên Google Workspace có thể sử dụng phương thức search() trên tài nguyên Space của API Chat để tìm các không gian không hoạt động, sau đó xoá các không gian đó bằng phương thức delete() với tham số useAdminAccess.

Các không gian Google Chat không hoạt động (không còn được sử dụng thường xuyên) có thể chiếm không gian lưu trữ quý giá và gây lộn xộn trong giao diện người dùng. Khi sử dụng phương thức search(), quản trị viên có thể tìm thấy những không gian chưa được sử dụng kể từ một ngày và giờ cụ thể, chẳng hạn như cách đây hai tháng. Sau khi liệt kê danh sách các không gian, quản trị viên có thể thực hiện hành động đối với các không gian đó, chẳng hạn như cập nhật hoặc xoá các không gian đó.

Để tìm kiếm danh sách không gian không hoạt động rồi xoá các không gian đó bằng quy trình xác thực người dùng và quyền của quản trị viên, hãy truyền những thông tin sau vào các yêu cầu của bạn:

  • Để tìm kiếm không gian không hoạt động, hãy chỉ định những thông tin sau:
    • Chỉ định phạm vi uỷ quyền chat.admin.spaces hoặc chat.admin.spaces.readonly.
    • Gọi phương thức search() trên tài nguyên Spaces.
    • Đặt INACTIVE_SPACE_DEADLINE thành ngày và giờ của hoạt động gần đây nhất để xác định các không gian cần trả về.
    • Chỉ định useAdminAccess=true.
    • Chỉ định các tham số tìm kiếm query để lọc kết quả:
      • customer = "customers/my_customer" – bắt buộc và giá trị duy nhất được hỗ trợ là customers/my_customer
      • spaceType = "SPACE" – bắt buộc và giá trị duy nhất được hỗ trợ là SPACE
      • lastActiveTime – để lọc yêu cầu của bạn chỉ trả về các không gian không hoạt động, hãy chỉ định lastActiveTime
  • Để xoá những không gian không hoạt động khỏi kết quả tìm kiếm, hãy chỉ định những thông tin sau:
    • Chỉ định phạm vi uỷ quyền chat.admin.delete.
    • Gọi phương thức delete() trên tài nguyên Spaces.
    • Chỉ định useAdminAccess=true.

Mã sau đây cho thấy ví dụ về cách tìm kiếm và xoá các không gian không hoạt động bằng đặc quyền quản trị:

Python

  1. Trong thư mục đang hoạt động, hãy tạo một tệp có tên là find_and_delete_inactive_spaces.py.

  2. Thêm mã sau vào 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. Trong mã, hãy thay thế INACTIVE_DATE bằng ngày và giờ ở định dạng YYYY-MM-DDTHH:MM:SS+HH:MM. Ví dụ: "2024-06-01T00:00:00+00:00".

  4. Trong thư mục đang hoạt động, hãy tạo bản dựng và chạy mẫu:

    python3 find_and_delete_inactive_spaces.py