스페이스에 사용자, Google 그룹 또는 Google Chat 앱을 초대하거나 추가하기

이 가이드에서는 Google Chat API의 Membership 리소스에서 create() 메서드를 사용하여 사용자, Google 그룹 또는 Chat 앱을 스페이스에 초대하거나 추가하는 방법을 설명합니다(멤버십 생성이라고도 함). 멤버십을 만들 때 지정된 회원의 자동 수락 정책이 사용 중지된 경우 초대되며, 참여하기 전에 스페이스 초대를 수락해야 합니다. 그렇지 않으면 멤버십을 만들면 지정된 스페이스에 구성원이 직접 추가됩니다.

Google Workspace 관리자는 Google Workspace 조직의 모든 스페이스에 사용자, Google 그룹 또는 Chat 앱을 추가할 수 있습니다.

Membership 리소스는 사람 사용자 또는 Google Chat 앱이 스페이스에 초대되었는지, 스페이스에 속해 있는지, 스페이스에 없는지를 나타냅니다.

기본 요건

Node.js

Python

자바

Apps Script

스페이스에 사용자를 초대하거나 사용자로 추가하기

사용자 인증을 통해 스페이스에 사용자를 초대하거나 추가하려면 요청에 다음을 전달합니다.

  • chat.memberships 승인 범위를 지정합니다.
  • CreateMembership() 메서드를 호출합니다.
  • 멤버십을 만들 스페이스의 리소스 이름으로 parent를 전달합니다.
  • membership를 Membership의 인스턴스로 전달하고 필드 member를 다음과 같이 설정합니다.
    • HUMAN로 설정된 type 필드
    • name 필드가 users/{user}로 설정되어 있으며 여기서 {user}는 스페이스에 추가하려는 사용자입니다. Chat 사용자를 지정하려면 {user}를 다음 중 하나로 바꿉니다.
      • People API의 사용자 ID입니다. 예를 들어 People API 사람 resourceName이 people/123456789이면 users/123456789 값을 사용합니다.
      • Directory API의 사용자 ID입니다.
      • 사용자의 이메일 주소 예를 들면 users/222larabrown@gmail.com 또는 users/larabrown@cymbalgroup.com입니다. 사용자가 Google 계정을 사용하거나 다른 Google Workspace 조직에 속해 있는 경우 사용자의 이메일 주소를 사용해야 합니다.

다음 예에서는 사용자 인증을 사용하여 스페이스에 사용자를 추가합니다.

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()

자바

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);
}

샘플을 실행하려면 다음을 바꿉니다.

  • SPACE_NAME: 스페이스의 name의 ID입니다. ListSpaces() 메서드를 호출하거나 스페이스의 URL에서 ID를 가져올 수 있습니다.
  • USER_NAME: 사용자 ID입니다.

Chat API는 생성된 사용자 멤버십을 자세히 설명하는 Membership 인스턴스를 반환합니다.

스페이스에 Google 그룹 초대 또는 추가하기

사용자 인증을 사용하여 Google 그룹을 스페이스에 초대하거나 추가하려면(앱 인증은 스페이스에 Google 그룹을 초대하거나 추가할 수 없음) 요청에 다음을 전달합니다.

  • chat.memberships 승인 범위를 지정합니다.
  • CreateMembership() 메서드를 호출합니다.
  • 멤버십을 만들 스페이스의 리소스 이름으로 parent를 전달합니다.
  • membership를 Membership의 인스턴스로 전달합니다. 이때 groupMember의 필드 name를 groups/{group}로 설정합니다. 여기서 {group}는 멤버십을 만들 그룹 ID입니다. 그룹의 ID는 Cloud ID API를 사용하여 검색할 수 있습니다.

Google 그룹스는 그룹 채팅이나 채팅 메시지에 추가할 수 없으며 이름이 지정된 스페이스에만 추가할 수 있습니다.

다음 예에서는 사용자 인증이 있는 이름이 지정된 스페이스에 그룹을 추가합니다.

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()

자바

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);
}

샘플을 실행하려면 다음을 바꿉니다.

  • SPACE_NAME: 스페이스의 name의 ID입니다. ListSpaces() 메서드를 호출하거나 스페이스의 URL에서 ID를 가져올 수 있습니다.
  • GROUP_NAME: 그룹 ID입니다.

Chat API는 생성된 사용자 멤버십을 자세히 설명하는 Membership의 인스턴스를 반환합니다.

스페이스에 채팅 앱 추가하기

Chat 앱은 다른 앱을 스페이스의 구성원으로 추가할 수 없습니다. 스페이스 또는 두 사람 간의 채팅 메시지에 Chat 앱을 추가하려면 요청에 사용자 인증과 함께 다음을 전달합니다. 앱 인증은 스페이스에 Chat 앱을 초대하거나 추가하는 것을 지원하지 않습니다.

  • chat.memberships.app 승인 범위를 지정합니다.
  • CreateMembership() 메서드를 호출합니다.
  • 멤버십을 만들 스페이스의 리소스 이름으로 parent를 전달합니다.
  • membership를 Membership의 인스턴스로 전달하고 필드 member를 다음과 같이 설정합니다.
    • BOT로 설정된 type 필드
    • name 필드가 users/app로 설정됩니다. Chat API를 호출하는 앱을 나타내는 별칭입니다.

다음 예에서는 스페이스에 Chat 앱을 추가합니다.

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()

자바

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);
}

샘플을 실행하려면 SPACE_NAME를 스페이스의 name에 있는 ID로 바꿉니다. ListSpaces() 메서드를 호출하거나 스페이스의 URL에서 ID를 가져올 수 있습니다.

Chat API는 생성된 사용자 멤버십을 자세히 설명하는 Membership 인스턴스를 반환합니다.

사용자를 스페이스에 Chat 앱으로 초대하거나 추가하기

앱 인증에는 일회성 관리자 승인이 필요합니다.

앱 인증으로 스페이스에 사용자를 초대하거나 추가하려면 요청에 다음을 전달합니다.

  • chat.app.memberships 승인 범위를 지정합니다.
  • membership 리소스에서 create 메서드를 호출합니다.
  • parent을 멤버십을 만들 스페이스의 리소스 이름으로 설정합니다.
  • member을 users/{user}로 설정합니다. 여기서 {user}은 멤버십을 만들려는 사용자이며 다음 중 하나입니다.
    • People API의 사용자 ID입니다. 예를 들어 People API person resourceName이 people/123456789이면 membership.member.name을 users/123456789로 설정합니다.
    • Directory API의 사용자 ID입니다.
    • 사용자의 이메일 주소 예를 들면 users/222larabrown@gmail.com 또는 users/larabrown@cymbalgroup.com입니다. 사용자가 Google 계정을 사용하거나 다른 Google Workspace 조직에 속해 있는 경우 사용자의 이메일 주소를 사용해야 합니다.

API 키 만들기

개발자 프리뷰 API 메서드를 호출하려면 API 검색 문서의 비공개 개발자 프리뷰 버전을 사용해야 합니다. 요청을 인증하려면 API 키를 전달해야 합니다.

API 키를 만들려면 앱의 Google Cloud 프로젝트를 열고 다음을 수행합니다.

  1. Google Cloud 콘솔에서 메뉴 > API 및 서비스 > 사용자 인증 정보로 이동합니다.

    사용자 인증 정보로 이동

  2. 사용자 인증 정보 만들기 > API 키를 클릭합니다.
  3. 새 API 키가 표시됩니다.
    • 복사 를 클릭하여 앱 코드에서 사용할 API 키를 복사합니다. API 키는 프로젝트 사용자 인증 정보의 'API 키' 섹션에서도 확인할 수 있습니다.
    • 키 제한을 클릭하여 고급 설정을 업데이트하고 API 키 사용을 제한합니다. 자세한 내용은 API 키 제한 적용을 참고하세요.

Chat API를 호출하는 스크립트 작성

다음 예에서는 앱 인증으로 스페이스에 사용자를 추가합니다.

Python

  1. 작업 디렉터리에 chat_membership_app_create.py라는 파일을 만듭니다.

  2. 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. 코드에서 다음을 바꿉니다.

    • API_KEY: Chat API의 서비스 엔드포인트를 빌드하기 위해 만든 API 키입니다.

    • SPACE: Chat API의 spaces.list 메서드 또는 스페이스 URL에서 가져올 수 있는 스페이스 이름입니다.

    • USER: 사용자 ID입니다.

  4. 작업 디렉터리에서 샘플을 빌드하고 실행합니다.

    python3 chat_membership_app_create.py

Google Workspace 관리자로 스페이스에 사용자 또는 Google 그룹 추가하기

Google Workspace 관리자는 create() 메서드를 호출하여 Google Workspace 조직의 모든 스페이스에 사용자, Google 그룹 또는 Chat 앱을 추가할 수 있습니다.

Google Workspace 관리자로 이 메서드를 호출하려면 다음 단계를 따르세요.

  • 사용자 인증을 사용하여 메서드를 호출하고 관리자 권한을 사용하여 메서드 호출을 지원하는 승인 범위를 지정합니다.
  • 요청에서 쿼리 매개변수 useAdminAccess를 true로 지정합니다.

자세한 내용과 예시는 Google Workspace 관리자로 Google Chat 스페이스 관리하기를 참고하세요.

제한사항 및 고려사항

  • 앱 인증을 사용하면 채팅 앱이 사용자를 초대하거나 추가할 수 있지만 Google 그룹스 또는 채팅 앱은 추가할 수 없습니다. 자체를 추가하려면 채팅 앱에서 chat.memberships 승인 범위가 있는 사용자 인증을 사용해야 합니다.