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ênSpace của Google Chat API để quản lý các không gian có tên trong tổ chức và thực hiện các tác vụ quản trị.

Là quản trị viên Google Workspace, bạn chỉ có thể dùng Chat API để quản lý không gian có tên. Không gian có tên được xác định là một SpaceType của SPACE. Không gian có 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ể dùng Chat API để 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à các ứ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 như sau:

  • Tin nhắn trực tiếp (DM) là cuộc trò chuyện giữa hai người dùng hoặc giữa một người dùng và một ứng dụng Chat.
  • Cuộc trò chuyện nhóm là cuộc trò chuyện giữa từ 3 người dùng trở lên và các ứng dụng Chat.
  • Không gian có 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. Bằng cách sử dụng phương thức search(), bạn có thể truy xuất danh sách tất cả các không gian trong một tổ chức cùng với 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á các 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 khoảng trống chưa được sử dụng kể từ một ngày và giờ cụ thể, rồi xoá chúng. Để biết thêm thông tin chi tiết và mã mẫu, hãy xem phần Tìm và xoá các 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. Bằng phương thức search(), bạn có thể truy xuất danh sách các không gian đáp ứng 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. Bằng phương thức search(), bạn có thể truy xuất danh sách tất cả cá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ả các thành viên không gian là người quản lý.
  • Tìm không gian không có người quản lý được chỉ định. Bằng cách sử dụng phương thức search(), bạn có thể truy xuất danh sách tất cả cá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 các không gian không có người quản lý.

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

Python

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

Để xác thực với tư cách là người dùng có đặc quyền quản trị, bạn phải truyền các thông tin sau trong 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 phương thức xác thực người dùng có đặc quyền của quản trị viên.
  • Đặ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 các không gian trong một tổ chức dựa trên các tiêu chí được chỉ định.

Để gọi phương thức search() bằng xác thực người dùng và đặc quyền 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
    • Bạn có thể thêm một hoặc nhiều cụm từ tìm kiếm khác để lọc thêm nội dung tìm kiếm 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).

Đoạn mã sau đây minh hoạ cách sử dụng đặc quyền quản trị viên để tìm kiếm các không gian có tên hiển thị chứa "Hello" và "World", theo mọi tổ hợp:

Python

  1. Trong thư mục làm việc, 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(
    '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. Trong thư mục làm việc, hãy tạo 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 Chat API để 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.

Những không gian không hoạt động trên Google Chat (những không gian không còn được sử dụng thường xuyên) có thể chiếm nhiều dung lượng lưu trữ 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ư 2 tháng trước. Sau khi liệt kê danh sách không gian, quản trị viên có thể thực hiện các thao tác đối với các không gian đó, chẳng hạn như cập nhật hoặc xoá.

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

  • Để tìm kiếm các 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 khoảng trống sẽ được 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ị được hỗ trợ duy nhất 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 chỉ trả về các không gian không hoạt động, hãy chỉ định lastActiveTime
  • Để xoá các 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.

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

Python

  1. Trong thư mục làm việc, 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(
      '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. 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 làm việc, hãy tạo và chạy mẫu:

    python3 find_and_delete_inactive_spaces.py