Mời hoặc thêm người dùng, nhóm trên Google Groups hoặc ứng dụng Google Chat vào một không gian

Hướng dẫn này giải thích cách sử dụng phương thức create() trên tài nguyên Membership của Google Chat API để mời hoặc thêm người dùng, Nhóm Google hoặc ứng dụng Chat vào một không gian (còn gọi là tạo tư cách thành viên). Khi tạo một thành viên, nếu thành viên được chỉ định đã tắt chính sách tự động chấp nhận, thì họ sẽ được mời và phải chấp nhận lời mời tham gia không gian trước khi tham gia. Nếu không, việc tạo một nhóm thành viên sẽ thêm trực tiếp thành viên đó vào không gian đã chỉ định.

Nếu là quản trị viên Google Workspace, bạn có thể thêm người dùng, Nhóm Google hoặc ứng dụng Chat vào bất kỳ không gian nào trong tổ chức Google Workspace của mình.

Tài nguyên Membership cho biết liệu người dùng là con người hay ứng dụng Google Chat được mời, có tham gia hay không tham gia một không gian.

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

Node.js

Python

Java

Apps Script

Mời hoặc thêm người dùng vào không gian với tư cách là người dùng

Để mời hoặc thêm người dùng vào một không gian có xác thực người dùng, 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.memberships.
  • Gọi phương thức CreateMembership().
  • Truyền parent làm tên tài nguyên của không gian mà bạn muốn tạo tư cách thành viên.
  • Truyền membership dưới dạng một thực thể của Membership với trường member được đặt bằng nội dung sau:
    • Trường type được đặt thành HUMAN.
    • Trường name được đặt thành users/{user}, trong đó {user} là người mà bạn muốn thêm vào không gian. Để chỉ định người dùng Chat, hãy thay thế {user} bằng một trong những giá trị sau:
      • Mã nhận dạng của người trong People API. Ví dụ: nếu person resourceName của People API là people/123456789, thì hãy sử dụng giá trị users/123456789.
      • Mã nhận dạng của người dùng trong Directory API.
      • Địa chỉ email của người dùng. Ví dụ: users/222larabrown@gmail.com hoặc users/larabrown@cymbalgroup.com. Nếu người dùng sử dụng Tài khoản Google hoặc thuộc một tổ chức Google Workspace khác, thì bạn phải sử dụng địa chỉ email của họ.

Ví dụ sau đây sẽ thêm một người dùng vào không gian bằng xác thực người dùng:

Node.js

chat/client-libraries/cloud/create-membership-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

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

// This sample shows how to create membership with user credential for a human user
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    membership: {
      member: {
        // Replace USER_NAME here
        name: 'users/USER_NAME',
        // User type for the membership
        type: 'HUMAN'
      }
    }
  };

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

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

main().catch(console.error);

Python

chat/client-libraries/cloud/create_membership_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.memberships"]

# This sample shows how to create membership with user credential for a human
# user
def create_membership_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMembershipRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        membership = {
            "member": {
                # Replace USER_NAME here
                "name": "users/USER_NAME",
                # user type for the membership
                "type_": "HUMAN"
            }
        }
    )

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

    # Handle the response
    print(response)

create_membership_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMembershipUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMembershipRequest;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SpaceName;
import com.google.chat.v1.User;

// This sample shows how to create membership with user credential for a human
// user.
public class CreateMembershipUserCred {

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

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMembershipRequest.Builder request = CreateMembershipRequest.newBuilder()
        // replace SPACE_NAME here
        .setParent("spaces/SPACE_NAME")
        .setMembership(Membership.newBuilder()
          .setMember(User.newBuilder()
            // replace USER_NAME here
            .setName("users/USER_NAME")
            // user type for the membership
            .setType(User.Type.HUMAN)));
      Membership response = chatServiceClient.createMembership(request.build());

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

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create membership with user credential for a human user
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships'
 * referenced in the manifest file (appsscript.json).
 */
function createMembershipUserCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const membership = {
    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.Members.create(membership, parent);

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

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

  • SPACE_NAME: mã nhận dạng từ name của không gian. Bạn có thể lấy mã nhận dạng bằng cách gọi phương thức ListSpaces() hoặc từ URL của không gian.
  • USER_NAME: mã nhận dạng người dùng.

Chat API trả về một phiên bản của Membership cho biết chi tiết về tư cách thành viên của người dùng đã được tạo.

Mời hoặc thêm một nhóm trên Google Groups vào một không gian

Để mời hoặc thêm một Nhóm trên Google vào một không gian có xác thực người dùng (Xác thực ứng dụng không hỗ trợ việc mời hoặc thêm một Nhóm trên Google vào 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.memberships.
  • Gọi phương thức CreateMembership().
  • Truyền parent làm tên tài nguyên của không gian mà bạn muốn tạo tư cách thành viên.
  • Truyền membership dưới dạng một phiên bản của Membership với trường name của groupMember được đặt thành groups/{group}, 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.

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.

Ví dụ sau đây thêm một nhóm vào một không gian có tên bằng phương thức xác thực người dùng:

Node.js

chat/client-libraries/cloud/create-membership-user-cred-for-group.js
import {createClientWithUserCredentials} from './authentication-utils.js';

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

// This sample shows how to create membership with user credential for a group
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    membership: {
      groupMember: {
        // Replace GROUP_NAME here
        name: 'groups/GROUP_NAME'
      }
    }
  };

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

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

main().catch(console.error);

Python

chat/client-libraries/cloud/create_membership_user_cred_for_group.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.memberships"]

# This sample shows how to create membership with user credential for a group
def create_membership_with_user_cred_for_group():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMembershipRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        membership = {
            "groupMember": {
                # Replace GROUP_NAME here
                "name": "groups/GROUP_NAME"
            }
        }
    )

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

    # Handle the response
    print(response)

create_membership_with_user_cred_for_group()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMembershipUserCredForGroup.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMembershipRequest;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SpaceName;
import com.google.chat.v1.Group;

// This sample shows how to create membership with user credential for a group.
public class CreateMembershipUserCredForGroup {

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

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMembershipRequest.Builder request = CreateMembershipRequest.newBuilder()
        // replace SPACE_NAME here
        .setParent("spaces/SPACE_NAME")
        .setMembership(Membership.newBuilder()
          .setGroupMember(Group.newBuilder()
            // replace GROUP_NAME here
            .setName("groups/GROUP_NAME")));
      Membership response = chatServiceClient.createMembership(request.build());

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

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create membership with user credential for a group
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships'
 * referenced in the manifest file (appsscript.json).
 */
function createMembershipUserCredForGroup() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const membership = {
    groupMember: {
      // TODO(developer): Replace GROUP_NAME here
      name: 'groups/GROUP_NAME'
    }
  };

  // Make the request
  const response = Chat.Spaces.Members.create(membership, parent);

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

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

  • SPACE_NAME: mã nhận dạng từ name của không gian. Bạn có thể lấy mã nhận dạng bằng cách gọi phương thức ListSpaces() hoặc từ URL của không gian.
  • GROUP_NAME: mã nhóm.

Chat API trả về một phiên bản của Membership cho biết chi tiết về tư cách thành viên của người dùng đã được tạo.

Thêm ứng dụng Chat vào một không gian

Ứng dụng Chat không thể thêm một ứng dụng khác làm thành viên vào một không gian. Để thêm một ứng dụng Chat vào một không gian hoặc tin nhắn trực tiếp giữa hai người dùng là con người, hãy truyền các thông tin sau trong yêu cầu của bạn bằng xác thực người dùng (Xác thực ứng dụng không hỗ trợ việc mời hoặc thêm một ứng dụng Chat vào một không gian):

  • Chỉ định phạm vi uỷ quyền chat.memberships.app.
  • Gọi phương thức CreateMembership().
  • Truyền parent làm tên tài nguyên của không gian mà bạn muốn tạo tư cách thành viên.
  • Truyền membership dưới dạng một thực thể của Membership với trường member được đặt bằng nội dung sau:
    • Trường type được đặt thành BOT.
    • Trường name được đặt thành users/app; một biệt hiệu đại diện cho ứng dụng gọi API Chat.

Ví dụ sau đây thêm một ứng dụng Chat vào một không gian:

Node.js

chat/client-libraries/cloud/create-membership-user-cred-for-app.js
import {createClientWithUserCredentials} from './authentication-utils.js';

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

// This sample shows how to create membership with app credential for an app
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    membership: {
      member: {
        // Member name for app membership, do not change this
        name: 'users/app',
        // User type for the membership
        type: 'BOT'
      }
    }
  };

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

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

main().catch(console.error);

Python

chat/client-libraries/cloud/create_membership_user_cred_for_app.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.memberships.app"]

# This sample shows how to create membership with app credential for an app
def create_membership_with_user_cred_for_app():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMembershipRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        membership = {
            "member": {
                # member name for app membership, do not change this.
                "name": "users/app",
                # user type for the membership
                "type_": "BOT"
            }
        }
    )

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

    # Handle the response
    print(response)

create_membership_with_user_cred_for_app()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMembershipUserCredForApp.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMembershipRequest;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SpaceName;
import com.google.chat.v1.User;

// This sample shows how to create membership with user credential for the
// calling app.
public class CreateMembershipUserCredForApp {

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

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMembershipRequest.Builder request = CreateMembershipRequest.newBuilder()
        // replace SPACE_NAME here
        .setParent("spaces/SPACE_NAME")
        .setMembership(Membership.newBuilder()
          .setMember(User.newBuilder()
            // member name for app membership, do not change this.
            .setName("users/app")
            // user type for the membership
            .setType(User.Type.BOT)));
      Membership response = chatServiceClient.createMembership(request.build());

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

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create membership with app credential for an app
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships.app'
 * referenced in the manifest file (appsscript.json).
 */
function createMembershipUserCredForApp() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const membership = {
    member: {
      // Member name for app membership, do not change this
      name: 'users/app',
      // User type for the membership
      type: 'BOT'
    }
  };

  // Make the request
  const response = Chat.Spaces.Members.create(membership, parent);

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

Để chạy mẫu, hãy thay thế SPACE_NAME bằng mã nhận dạng từ name của không gian. Bạn có thể lấy mã nhận dạng bằng cách gọi phương thức ListSpaces() hoặc từ URL của không gian.

Chat API trả về một phiên bản của Membership cho biết chi tiết về tư cách thành viên của người dùng đã được tạo.

Mời hoặc thêm người dùng vào một không gian dưới dạng ứng dụng Chat

Để xác thực ứng dụng, bạn cần có sự phê duyệt một lần của quản trị viên.

Để mời hoặc thêm người dùng vào một không gian bằng xác thực ứng dụng, 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.app.memberships.
  • Gọi phương thức create trên tài nguyên membership.
  • Đặt parent thành tên tài nguyên của không gian mà bạn muốn tạo tư cách thành viên.
  • Đặt member thành users/{user}, trong đó {user} là người mà bạn muốn tạo tư cách thành viên và có thể là:
    • Mã nhận dạng của người trong People API. Ví dụ: nếu person resourceName của People API là people/123456789, thì hãy đặt membership.member.name thành users/123456789.
    • Mã nhận dạng của người dùng trong Directory API.
    • Địa chỉ email của người dùng. Ví dụ: users/222larabrown@gmail.com hoặc users/larabrown@cymbalgroup.com. Nếu người dùng sử dụng Tài khoản Google hoặc thuộc một tổ chức Google Workspace khác, thì bạn phải sử dụng địa chỉ email của họ.

Tạo một khoá API

Để gọi một phương thức API trong bản dùng thử cho nhà phát triển, bạn phải sử dụng một phiên bản không công khai của tài liệu khám phá API trong bản dùng thử cho nhà phát triển. Để xác thực yêu cầu, bạn phải truyền một khoá API.

Để tạo Khoá API, hãy mở dự án Google Cloud của ứng dụng rồi làm như sau:

  1. Trong bảng điều khiển Google Cloud, hãy chuyển đến phần Trình đơn > API và Dịch vụ > Thông tin xác thực.

    Chuyển đến phần Thông tin đăng nhập

  2. Nhấp vào Tạo thông tin xác thực > Khoá API.
  3. Khoá API mới của bạn sẽ xuất hiện.
    • Nhấp vào biểu tượng Sao chép để sao chép khoá API nhằm sử dụng trong mã của ứng dụng. Bạn cũng có thể tìm thấy khoá API trong phần "Khoá API" của thông tin đăng nhập dự án.
    • Nhấp vào Hạn chế khoá để cập nhật chế độ cài đặt nâng cao và giới hạn việc sử dụng khoá API. Để biết thêm thông tin chi tiết, hãy xem phần Áp dụng các quy tắc hạn chế đối với khoá API.

Viết một tập lệnh gọi API Chat

Ví dụ sau đây thêm một người dùng vào không gian bằng quy trình xác thực ứng dụng:

Python

  1. Trong thư mục làm việc, hãy tạo một tệp có tên là chat_membership_app_create.py.

  2. Thêm mã sau vào chat_membership_app_create.py:

    from google.oauth2 import service_account
from apiclient.discovery import build

# Define your app's authorization scopes.
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.app.memberships"]

def main():
    '''
    Authenticates with Chat API using app authentication,
    then adds a user to a Chat space by creating a membership.
    '''

    # Specify service account details.
    creds = (
        service_account.Credentials.from_service_account_file('credentials.json')
        .with_scopes(SCOPES)
    )

    # Build a service endpoint for Chat API.
    chat = build('chat', 'v1', credentials=creds, discoveryServiceUrl='https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY')

    # Use the service endpoint to call Chat API.
    result = chat.spaces().members().create(

        # The space in which to create a membership.
        parent = 'spaces/SPACE',

        # Specify which user the membership is for.
        body = {
          'member': {
            'name':'users/USER',
            'type': 'HUMAN'
          }
        }

    ).execute()

    # Prints details about the created membership.
    print(result)

if __name__ == '__main__':
    main()

  3. Trong mã, hãy thay thế những nội dung sau:

    • API_KEY: khoá API mà bạn đã tạo để xây dựng điểm cuối dịch vụ cho Chat API.

    • SPACE: tên của một không gian. Bạn có thể lấy tên này từ phương thức spaces.list trong Chat API hoặc từ URL của một không gian.

    • USER: mã nhận dạng người dùng.

  4. Trong thư mục làm việc, hãy tạo và chạy mẫu:

    python3 chat_membership_app_create.py

Thêm người dùng hoặc nhóm trên Google Groups vào một không gian với tư cách là quản trị viên Google Workspace

Nếu là quản trị viên Google Workspace, bạn có thể gọi phương thức create() để thêm người dùng, Nhóm Google hoặc ứng dụng Chat vào bất kỳ không gian nào trong tổ chức Google Workspace của bạn.

Để gọi phương thức này với tư cách là quản trị viên Google Workspace, hãy làm như sau:

  • Gọi phương thức bằng cách sử dụng quy trình xác thực người dùng và chỉ định một phạm vi uỷ quyền hỗ trợ việc gọi phương thức bằng đặc quyền quản trị viên.
  • Trong yêu cầu, hãy chỉ định tham số truy vấn useAdminAccess thành true.

Để biết thêm thông tin và ví dụ, hãy xem bài viết Quản lý không gian trong Google Chat với tư cách là quản trị viên Google Workspace.

Các điểm hạn chế và điều cần cân nhắc

  • Với tính năng Xác thực ứng dụng, một ứng dụng Chat có thể mời hoặc thêm người dùng, nhưng không thể thêm Nhóm Google hoặc ứng dụng Chat. Để tự thêm, ứng dụng Chat phải sử dụng quy trình xác thực người dùng với phạm vi uỷ quyền chat.memberships.