Tạo không gian trên Google Chat và thêm thành viên

Hướng dẫn này giải thích cách sử dụng phương thức setUp() trên tài nguyên Space của Google Chat API để tạo một không gian Chat và thêm thành viên vào không gian đó.

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.

Bạn có thể dùng phương thức setUp() để thực hiện bất kỳ thao tác nào sau đây:

  • Tạo một không gian có tên với các thành viên ban đầu.
  • Tạo tin nhắn trực tiếp (DM) giữa hai người.
  • Thiết lập tin nhắn nhóm giữa nhiều người.

Khi thiết lập một không gian, hãy cân nhắc những điều sau:

  • Người dùng gọi (đã xác thực) sẽ tự động được thêm vào không gian, vì vậy, bạn không cần chỉ định tư cách thành viên của người dùng trong yêu cầu.
  • Khi tạo tin nhắn trực tiếp (DM), nếu có một tin nhắn trực tiếp giữa hai người dùng, thì tin nhắn trực tiếp đó sẽ được trả về. Nếu không, một tin nhắn trực tiếp sẽ được tạo.
  • Khi tạo một cuộc trò chuyện nhóm, nếu không có thành viên nào được cung cấp trong yêu cầu được thêm thành công vào cuộc trò chuyện nhóm (ví dụ: vấn đề về quyền), thì một cuộc trò chuyện nhóm trống (chỉ bao gồm người dùng gọi) có thể được tạo.
  • Bạn không thể thiết lập không gian có tính năng trả lời theo chuỗi hoặc thêm người dùng bên ngoài tổ chức Google Workspace của mình.
  • Các thành viên trùng lặp (bao gồm cả người dùng gọi) được cung cấp trong yêu cầu sẽ bị lọc thay vì dẫn đến lỗi yêu cầu.
  • Khi một quản trị viên Google Workspace cài đặt một ứng dụng Chat cho toàn bộ tổ chức Google Workspace của họ, Google Chat sẽ tạo một tin nhắn trực tiếp giữa ứng dụng Chat đã cài đặt và mỗi người dùng trong tổ chức, do đó, bạn không cần phải thiết lập tin nhắn trực tiếp theo cách lập trình. Thay vào đó, hãy liệt kê các không gian để trả về tất cả tin nhắn trực tiếp hoặc tìm tin nhắn trực tiếp để biết thông tin chi tiết về một tin nhắn trực tiếp cụ thể.

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

Node.js

Python

Java

Apps Script

Thiết lập không gian

Để thiết lập một không gian, hãy truyền các thông tin sau trong yêu cầu của bạn:

  • Chỉ định phạm vi uỷ quyền chat.spaces.create hoặc chat.spaces.
  • Gọi phương thức SetUpSpace().
  • Truyền space dưới dạng một thực thể của Space với tất cả các trường cần thiết, chẳng hạn như displayName hoặc spaceType.
  • Truyền memberships dưới dạng một mảng các thực thể Membership. Đối với mỗi trường hợp:
    • Chỉ định users/{user} để thêm người dùng là con người làm thành viên của không gian, trong đó {user} là {person_id} cho person từ People API hoặc mã nhận dạng của user trong Directory API. Ví dụ: nếu người dùng People API resourceName là people/123456789, bạn có thể thêm người dùng vào không gian bằng cách thêm một thành viên có users/123456789 làm member.name.
    • Chỉ định groups/{group} để thêm một nhóm làm thành viên của không gian, trong đó {group} là mã nhóm mà bạn muốn tạo tư cách thành viên. Bạn có thể truy xuất mã nhận dạng của nhóm bằng Cloud Identity API. Ví dụ: nếu Cloud Identity API trả về một nhóm có tên là groups/123456789, thì hãy đặt membership.groupMember.name thành groups/123456789. Bạn không thể thêm Nhóm Google vào cuộc trò chuyện nhóm hoặc tin nhắn trực tiếp, mà chỉ có thể thêm vào một không gian có tên.

Để tạo tin nhắn trực tiếp giữa người dùng gọi và một người dùng khác, hãy chỉ định tư cách thành viên của người dùng đó trong yêu cầu của bạn.

Để tạo tin nhắn trực tiếp giữa người dùng gọi và ứng dụng gọi, 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ể sử 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. Để thêm ứng dụng gọi 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 tạo tư cách thành viên.

Ví dụ sau đây sẽ tạo một không gian có tên và tạo một thành viên cho không gian đó cho 2 người dùng là con người (người dùng đã xác thực và một người dùng khác).

Node.js

chat/client-libraries/cloud/set-up-space-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.spaces.create'];

// This sample shows how to set up a named space with one initial member
// with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    space: {
      spaceType: 'SPACE',
      // Replace DISPLAY_NAME here.
      displayName: 'DISPLAY_NAME'
    },
    memberships: [{
      member: {
        // Replace USER_NAME here.
        name: 'users/USER_NAME',
        type: 'HUMAN'
      }
    }]
  };

  // Make the request
  const response = await chatClient.setUpSpace(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/set_up_space_user_cred.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.spaces.create"]

def set_up_space_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.SetUpSpaceRequest(
        space = {
            "space_type": 'SPACE',
            # Replace DISPLAY_NAME here.
            "display_name": 'DISPLAY_NAME'
        },
        memberships = [{
            "member": {
                # Replace USER_NAME here.
                "name": 'users/USER_NAME',
                "type_": 'HUMAN'
            }
        }]
    )

    # Make the request
    response = client.set_up_space(request)

    # Handle the response
    print(response)

set_up_space_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/SetUpSpaceUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SetUpSpaceRequest;
import com.google.chat.v1.Space;
import com.google.chat.v1.User;

// This sample shows how to set up a named space with one initial member with
// user credential.
public class SetUpSpaceUserCred {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.spaces.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      SetUpSpaceRequest.Builder request = SetUpSpaceRequest.newBuilder()
        .setSpace(Space.newBuilder()
          .setSpaceType(Space.SpaceType.SPACE)
          // Replace DISPLAY_NAME here.
          .setDisplayName("DISPLAY_NAME"))
        .addAllMemberships(ImmutableList.of(Membership.newBuilder()
          .setMember(User.newBuilder()
            // Replace USER_NAME here.
            .setName("users/USER_NAME")
            .setType(User.Type.HUMAN)).build()));
      Space response = chatServiceClient.setUpSpace(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to set up a named space with one initial member with
 * user credential.
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.spaces.create'
 * referenced in the manifest file (appsscript.json).
 */
function setUpSpaceUserCred() {
  // Initialize request argument(s)
  const space = {
    spaceType: 'SPACE',
    // TODO(developer): Replace DISPLAY_NAME here
    displayName: 'DISPLAY_NAME'
  };
  const memberships = [{
    member: {
      // TODO(developer): Replace USER_NAME here
      name: 'users/USER_NAME',
      // User type for the membership
      type: 'HUMAN'
    }
  }];

  // Make the request
  const response = Chat.Spaces.setup({ space: space, memberships: memberships });

  // Handle the response
  console.log(response);
}

Để chạy mẫu, hãy thay thế những nội dung sau:

  • DISPLAY_NAME: tên hiển thị của không gian mới.
  • USER_NAME: mã nhận dạng của người dùng khác để thêm tư cách thành viên.

Để chuyển đến không gian, hãy dùng mã nhận dạng tài nguyên của không gian để tạo URL của không gian. Bạn có thể lấy mã nhận dạng tài nguyên từ không gian name trong phần nội dung phản hồi của Google Chat. Ví dụ: nếu name của không gian là spaces/1234567, bạn có thể truy cập vào không gian bằng URL sau: https://mail.google.com/chat/u/0/#chat/space/1234567.