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 API Google Chat để 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 gói thành viên). Khi bạn tạo gói 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 gói 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, Google Groups 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 hoặc ứng dụng Google Chat có được mời tham gia, có tham gia hay không tham gia không gian hay không.

Đ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ó quy trình xác thực người dùng, hãy truyền những thông tin sau vào 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 để tạo gói 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 như 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 bất kỳ giá trị nào sau đây:
      • Mã nhận dạng cho người trong API People. Ví dụ: nếu person resourceName của API People là people/123456789, thì hãy sử dụng giá trị users/123456789.
      • Mã nhận dạng cho 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, bạn phải sử dụng địa chỉ email của họ.

Ví dụ sau đây thêm một người dùng vào không gian có quy trình 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ế 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 thực thể của Membership nêu chi tiết về gói 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 không gian

Để mời hoặc thêm một nhóm trên Google Groups vào một không gian bằng tính năng xác thực người dùng (Xác thực ứng dụng không hỗ trợ tính năng mời hoặc thêm một nhóm trên Google Groups vào một không gian), hãy truyền các thông tin sau vào 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 để tạo gói thành viên.
  • Truyền membership dưới dạng một thực thể của Membership với trường name của groupMember được đặt thành groups/{group}, trong đó {group} là mã nhận dạng nhóm mà bạn muốn tạo gói 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 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ế 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ận dạng nhóm.

Chat API trả về một thực thể của Membership nêu chi tiết về gói 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, hãy truyền nội dung sau vào yêu cầu của bạn bằng quy trình xác thực người dùng (Quy trình xác thực ứng dụng không hỗ trợ mời hoặc thêm ứ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 để tạo gói 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 như sau:
    • Trường type được đặt thành BOT.
    • Trường name được đặt thành users/app; một bí danh đạ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 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 thực thể của Membership nêu chi tiết về gói 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 không gian dưới dạng ứng dụng Chat

Quy trình xác thực ứng dụng yêu cầu quyền phê duyệt của quản trị viên một lần.

Để mời hoặc thêm người dùng vào không gian bằng tính năng xác thực ứng dụng, hãy truyền những thông tin sau vào 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 để tạo gói thành viên.
  • Đặt member thành users/{user}, trong đó {user} là người mà bạn muốn tạo gói hội viên và là:
    • Mã nhận dạng cho người trong API People. Ví dụ: nếu người resourceName của API People là people/123456789, thì hãy đặt membership.member.name thành users/123456789.
    • Mã nhận dạng cho 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, 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 Bản dùng thử cho nhà phát triển, bạn phải sử dụng phiên bản bản dùng thử không công khai cho nhà phát triển của tài liệu khám phá API. Để 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 Trình đơn > API và dịch vụ > Thông tin xác thực.

    Chuyển đến phần Thông tin xác thực

  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 để 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 xác thực 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, hãy xem bài viết Áp dụng các quy tắc hạn chế đối với khoá API.

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

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

Python

  1. Trong thư mục đang hoạt động, 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ế các nội dung sau:

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

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

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

  4. Trong thư mục đang hoạt động, hãy tạo bản dựng 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, Google Groups 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.

Để 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 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 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 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, ứng dụng Chat có thể mời hoặc thêm người dùng, nhưng không phải ứng dụng Google Groups hoặc Chat. Để tự thêm, ứng dụng Chat phải sử dụng tính năng xác thực người dùng với phạm vi uỷ quyền chat.memberships.