Method: spaces.setup

Tạo một không gian và thêm người dùng được chỉ định vào không gian đó. Người dùng gọi sẽ tự động được thêm vào không gian và không được chỉ định là thành viên trong yêu cầu. Để xem ví dụ, hãy tham khảo phần Thiết lập không gian có các thành viên ban đầu.

Để chỉ định những thành viên là người dùng cần thêm, hãy thêm thành viên bằng membership.member.name thích hợp. Để thêm người dùng là con người, hãy sử dụng users/{user}, trong đó {user} có thể là địa chỉ email của người dùng. Đối với người dùng trong cùng một tổ chức Workspace, {user} cũng có thể là id của người đó trong People API hoặc id của người dùng trong Directory API. Ví dụ: nếu mã nhận dạng hồ sơ Người dùng của People API cho user@example.com là 123456789, bạn có thể thêm người dùng vào không gian bằng cách đặt membership.member.name thành users/user@example.com hoặc users/123456789.

Để chỉ định các nhóm trên Google cần thêm, hãy thêm tư cách thành viên bằng membership.group_member.name thích hợp. Để thêm hoặc mời một nhóm trên Google, hãy sử dụng groups/{group}, trong đó {group} là id cho nhóm đó trong Cloud Identity Groups API. Ví dụ: bạn có thể sử dụng Cloud Identity Groups lookup API để truy xuất mã nhận dạng 123456789 cho email nhóm group@example.com, sau đó bạn có thể thêm nhóm vào không gian bằng cách đặt membership.group_member.name thành groups/123456789. Chúng tôi không hỗ trợ email nhóm và bạn chỉ có thể thêm nhóm Google làm thành viên trong không gian có tên.

Đối với một không gian có tên hoặc cuộc trò chuyện nhóm, nếu người gọi chặn hoặc bị một số thành viên chặn, hoặc không có quyền thêm một số thành viên, thì những thành viên đó sẽ không được thêm vào không gian đã tạo.

Để tạo tin nhắn trực tiếp (DM) giữa người dùng gọi và một người dùng là con người khác, hãy chỉ định chính xác một thành viên để đại diện cho người dùng là con người đó. Nếu một người dùng chặn người dùng kia, thì yêu cầu sẽ không thành công và tin nhắn trực tiếp sẽ không được tạo.

Để tạo Tin nhắn trực tiếp giữa người dùng gọi và ứng dụng gọi điện, hãy đặt Space.singleUserBotDm thành true và không chỉ định bất kỳ thành viên nào. Bạn chỉ có thể dùng phương thức này để thiết lập tin nhắn trực tiếp với ứng dụng gọi điện. Để thêm ứng dụng gọi điện làm thành viên của một không gian hoặc tin nhắn trực tiếp hiện có giữa hai người dùng, hãy xem phần Mời hoặc thêm người dùng hoặc ứng dụng vào không gian.

Nếu đã có tin nhắn trực tiếp giữa hai người dùng, thì ngay cả khi một người dùng chặn người dùng kia tại thời điểm yêu cầu được thực hiện, tin nhắn trực tiếp hiện có vẫn được trả về.

Không hỗ trợ không gian có tính năng trả lời theo chuỗi. Nếu bạn nhận được thông báo lỗi ALREADY_EXISTS khi thiết lập một không gian, hãy thử một displayName khác. Một không gian hiện có trong tổ chức Google Workspace có thể đã sử dụng tên hiển thị này.

Yêu cầu xác thực người dùng bằng một trong các phạm vi uỷ quyền sau:

  • https://www.googleapis.com/auth/chat.spaces.create
  • https://www.googleapis.com/auth/chat.spaces

Yêu cầu HTTP

POST https://chat.googleapis.com/v1/spaces:setup

URL sử dụng cú pháp Chuyển mã gRPC.

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu với cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "space": {
    object (Space)
  },
  "requestId": string,
  "memberships": [
    {
      object (Membership)
    }
  ]
}
Trường
space

object (Space)

Bắt buộc. Bạn bắt buộc phải điền vào trường Space.spaceType.

Để tạo một không gian, hãy đặt Space.spaceType thành SPACE và đặt Space.displayName. Nếu bạn nhận được thông báo lỗi ALREADY_EXISTS khi thiết lập một không gian, hãy thử một displayName khác. Một không gian hiện có trong tổ chức Google Workspace có thể đã sử dụng tên hiển thị này.

Để tạo cuộc trò chuyện nhóm, hãy đặt Space.spaceType thành GROUP_CHAT. Không đặt Space.displayName.

Để tạo cuộc trò chuyện 1:1 giữa người dùng, hãy đặt Space.spaceType thành DIRECT_MESSAGE và đặt Space.singleUserBotDm thành false. Đừng đặt Space.displayName hoặc Space.spaceDetails.

Để tạo cuộc trò chuyện 1:1 giữa một người và ứng dụng Chat gọi, hãy đặt Space.spaceType thành DIRECT_MESSAGE và Space.singleUserBotDm thành true. Đừng đặt Space.displayName hoặc Space.spaceDetails.

Nếu đã có không gian DIRECT_MESSAGE, thì không gian đó sẽ được trả về thay vì tạo một không gian mới.
requestId

string

Không bắt buộc. Mã nhận dạng duy nhất cho yêu cầu này. Bạn nên dùng một UUID ngẫu nhiên. Việc chỉ định một mã yêu cầu sẽ khiến yêu cầu trở nên bất biến, đảm bảo rằng nhiều yêu cầu giống hệt nhau có cùng mã yêu cầu sẽ chỉ tạo ra một khoảng trống duy nhất. Các yêu cầu tiếp theo có cùng mã yêu cầu sẽ trả về không gian hiện có và không cập nhật không gian, ngay cả khi thông tin chi tiết được yêu cầu khác với trạng thái hiện tại.

Cách sử dụng trường này một cách hiệu quả:

  • Đảm bảo rằng các yêu cầu tiếp theo giống hệt nhau và sử dụng cùng thông tin xác thực như yêu cầu ban đầu.
  • Nếu một không gian đã được tạo bằng mã yêu cầu được cung cấp, thì yêu cầu sẽ trả về không gian đó. Xin lưu ý rằng không gian được trả về có thể chưa được điền đầy đủ; API sẽ phản hồi không gian trong yêu cầu của bạn bằng tên tài nguyên do hệ thống chỉ định. Để truy xuất siêu dữ liệu mới nhất cho không gian, hãy gọi spaces.get.
  • Việc dùng lại mã yêu cầu hiện có với một người dùng đã xác thực khác sẽ dẫn đến lỗi.
memberships[]

object (Membership)

Không bắt buộc. Người dùng hoặc nhóm trên Google Chat mà bạn muốn mời tham gia không gian. Bỏ qua người dùng gọi vì họ sẽ được thêm tự động.

Nhóm này hiện cho phép tối đa 49 thành viên (ngoài người gọi).

Đối với thành viên là người dùng, trường Membership.member phải chứa một user có name được điền sẵn (định dạng: users/{user}) và type được đặt thành User.Type.HUMAN. Bạn chỉ có thể thêm người dùng là con người khi thiết lập không gian (chỉ có thể thêm ứng dụng Chat khi thiết lập tin nhắn trực tiếp bằng ứng dụng gọi điện). Bạn cũng có thể thêm thành viên bằng cách sử dụng email của người dùng làm email đại diện cho {user}. Ví dụ: user.name có thể là users/example@gmail.com. Để mời người dùng Gmail hoặc người dùng thuộc miền Google Workspace bên ngoài, bạn phải sử dụng email của người dùng cho {user}.

Đối với tư cách thành viên trong nhóm trên Google, trường Membership.group_member phải chứa một group có name được điền sẵn (định dạng groups/{group}). Bạn chỉ có thể thêm nhóm trên Google khi đặt Space.spaceType thành SPACE.

Không bắt buộc khi bạn đặt Space.spaceType thành SPACE.

Bạn phải cung cấp thông tin này khi đặt Space.spaceType thành GROUP_CHAT, cùng với ít nhất 2 gói thành viên.

Bắt buộc khi đặt Space.spaceType thành DIRECT_MESSAGE với một người dùng là con người, cùng với chính xác một thành viên.

Phải trống khi tạo cuộc trò chuyện 1:1 giữa người dùng và ứng dụng Chat gọi (khi đặt Space.spaceType thành DIRECT_MESSAGE và Space.singleUserBotDm thành true).

Nội dung phản hồi

Nếu thành công, nội dung phản hồi sẽ chứa một thực thể của Space.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.create

Để biết thêm thông tin, hãy xem Hướng dẫn uỷ quyền.