Mengundang atau menambahkan pengguna, grup Google, atau aplikasi Google Chat ke ruang

Panduan ini menjelaskan cara menggunakan metode create() di resource Membership Google Chat API untuk mengundang atau menambahkan pengguna, Grup Google, atau aplikasi Chat ke ruang yang juga dikenal sebagai membuat keanggotaan. Saat membuat langganan, jika kebijakan terima otomatis anggota yang ditentukan dinonaktifkan, mereka akan diundang, dan harus menerima undangan ruang sebelum bergabung. Jika tidak, pembuatan langganan akan menambahkan anggota langsung ke ruang yang ditentukan.

Jika Anda adalah administrator Google Workspace, Anda dapat menambahkan pengguna, Google Grup, atau aplikasi Chat ke ruang mana pun di organisasi Google Workspace Anda.

Resource Membership mewakili apakah pengguna manusia atau aplikasi Google Chat diundang ke, menjadi bagian dari, atau tidak ada di ruang.

Prasyarat

Node.js

Python

Java

Apps Script

Mengundang atau menambahkan pengguna ke ruang sebagai pengguna

Untuk mengundang atau menambahkan pengguna ke ruang dengan autentikasi pengguna, teruskan hal berikut dalam permintaan Anda:

  • Tentukan cakupan otorisasi chat.memberships.
  • Panggil metode CreateMembership().
  • Teruskan parent sebagai nama resource ruang tempat membuat langganan.
  • Teruskan membership sebagai instance Membership dengan kolom member yang ditetapkan dengan hal berikut:
    • Kolom type ditetapkan ke HUMAN.
    • Kolom name ditetapkan ke users/{user} dengan {user} adalah orang yang ingin Anda tambahkan ke ruang. Untuk menentukan pengguna Chat, ganti {user} dengan salah satu dari berikut:
      • ID untuk orang di People API. Misalnya, jika People API person resourceName adalah people/123456789, gunakan nilai users/123456789.
      • ID untuk pengguna di Directory API.
      • Alamat email pengguna. Misalnya, users/222larabrown@gmail.com atau users/larabrown@cymbalgroup.com. Jika pengguna menggunakan Akun Google atau merupakan bagian dari organisasi Google Workspace yang berbeda, Anda harus menggunakan alamat emailnya.

Contoh berikut menambahkan pengguna ke ruang dengan autentikasi pengguna:

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

Untuk menjalankan contoh, ganti kode berikut:

  • SPACE_NAME: ID dari name ruang. Anda bisa mendapatkan ID dengan memanggil metode ListSpaces() atau dari URL ruang.
  • USER_NAME: ID pengguna.

Chat API menampilkan instance Membership yang menjelaskan langganan pengguna yang dibuat.

Mengundang atau menambahkan grup Google ke ruang

Untuk mengundang atau menambahkan Grup Google ke ruang dengan autentikasi pengguna (Autentikasi aplikasi tidak mendukung untuk mengundang atau menambahkan Grup Google ke ruang), teruskan hal berikut dalam permintaan Anda:

  • Tentukan cakupan otorisasi chat.memberships.
  • Panggil metode CreateMembership().
  • Teruskan parent sebagai nama resource ruang tempat membuat langganan.
  • Teruskan membership sebagai instance Membership dengan kolom name dari groupMember ditetapkan ke groups/{group} dengan {group} adalah ID grup yang ingin Anda buat keanggotaannya. ID untuk grup dapat diambil menggunakan Cloud Identity API.

Google Grup tidak dapat ditambahkan ke chat grup atau pesan langsung, tetapi hanya ke ruang yang dinamai.

Contoh berikut menambahkan grup ke ruang bernama dengan autentikasi pengguna:

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

Untuk menjalankan contoh, ganti kode berikut:

  • SPACE_NAME: ID dari name ruang. Anda bisa mendapatkan ID dengan memanggil metode ListSpaces() atau dari URL ruang.
  • GROUP_NAME: ID grup.

Chat API menampilkan instance Membership yang menjelaskan langganan pengguna yang dibuat.

Menambahkan aplikasi Chat ke ruang

Aplikasi Chat tidak dapat menambahkan aplikasi lain sebagai anggota ke ruang. Untuk menambahkan aplikasi Chat ke ruang atau pesan langsung antara dua pengguna manusia, teruskan hal berikut dalam permintaan Anda dengan autentikasi pengguna (Autentikasi aplikasi tidak mendukung undangan atau penambahan aplikasi Chat ke ruang):

  • Tentukan cakupan otorisasi chat.memberships.app.
  • Panggil metode CreateMembership().
  • Teruskan parent sebagai nama resource ruang tempat membuat langganan.
  • Teruskan membership sebagai instance Membership dengan kolom member-nya yang ditetapkan dengan hal berikut:
    • Kolom type ditetapkan ke BOT.
    • Kolom name ditetapkan ke users/app; alias yang mewakili aplikasi yang memanggil Chat API.

Contoh berikut menambahkan aplikasi Chat ke ruang:

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

Untuk menjalankan contoh, ganti SPACE_NAME dengan ID dari name ruang. Anda bisa mendapatkan ID dengan memanggil metode ListSpaces() atau dari URL ruang.

Chat API menampilkan instance Membership yang menjelaskan langganan pengguna yang dibuat.

Mengundang atau menambahkan pengguna ke ruang sebagai aplikasi Chat

Autentikasi aplikasi memerlukan persetujuan administrator satu kali.

Untuk mengundang atau menambahkan pengguna ke ruang dengan autentikasi aplikasi, teruskan hal berikut dalam permintaan Anda:

  • Tentukan cakupan otorisasi chat.app.memberships.
  • Panggil metode create pada resource membership.
  • Tetapkan parent ke nama resource ruang tempat membuat langganan.
  • Tetapkan member ke users/{user} dengan {user} adalah orang yang ingin Anda buatkan langganan, dan merupakan:
    • ID untuk orang di People API. Misalnya, jika orang resourceName People API adalah people/123456789, tetapkan membership.member.name ke users/123456789.
    • ID untuk pengguna di Directory API.
    • Alamat email pengguna. Misalnya, users/222larabrown@gmail.com atau users/larabrown@cymbalgroup.com. Jika pengguna menggunakan Akun Google atau merupakan bagian dari organisasi Google Workspace yang berbeda, Anda harus menggunakan alamat emailnya.

Membuat kunci API

Untuk memanggil metode Developer Preview API, Anda harus menggunakan versi pratinjau developer non-publik dari dokumen penemuan API. Untuk mengautentikasi permintaan, Anda harus meneruskan kunci API.

Untuk membuat Kunci API, buka project Google Cloud aplikasi Anda dan lakukan hal berikut:

  1. Di konsol Google Cloud, buka Menu > APIs & Services > Credentials.

    Buka Kredensial

  2. Klik Create credentials > API key.
  3. Kunci API baru Anda akan ditampilkan.
    • Klik Salin untuk menyalin kunci API Anda agar dapat digunakan dalam kode aplikasi. Kunci API juga dapat ditemukan di bagian "API keys" pada kredensial project Anda.
    • Klik Batasi kunci untuk memperbarui setelan lanjutan dan membatasi penggunaan kunci API Anda. Untuk mengetahui detail selengkapnya, lihat Menerapkan pembatasan kunci API.

Menulis skrip yang memanggil Chat API

Contoh berikut menambahkan pengguna ke ruang dengan autentikasi aplikasi:

Python

  1. Di direktori kerja Anda, buat file bernama chat_membership_app_create.py.

  2. Sertakan kode berikut di 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. Dalam kode, ganti kode berikut:

    • API_KEY: kunci API yang Anda buat untuk membuat endpoint layanan untuk Chat API.

    • SPACE: nama ruang, yang dapat Anda peroleh dari metode spaces.list di Chat API, atau dari URL ruang.

    • USER: ID pengguna.

  4. Di direktori kerja, build dan jalankan contoh:

    python3 chat_membership_app_create.py

Menambahkan pengguna atau Google Grup ke ruang sebagai administrator Google Workspace

Jika Anda adalah administrator Google Workspace, Anda dapat memanggil metode create() untuk menambahkan pengguna, Google Grup, atau aplikasi Chat ke ruang mana pun di organisasi Google Workspace Anda.

Untuk memanggil metode ini sebagai administrator Google Workspace, lakukan hal berikut:

  • Panggil metode menggunakan autentikasi pengguna, dan tentukan cakupan otorisasi yang mendukung pemanggilan metode menggunakan hak istimewa administrator.
  • Dalam permintaan, tentukan parameter kueri useAdminAccess ke true.

Untuk mengetahui informasi selengkapnya dan contoh, lihat Mengelola ruang Google Chat sebagai administrator Google Workspace.

Batasan dan pertimbangan

  • Dengan Autentikasi aplikasi, aplikasi Chat dapat mengundang atau menambahkan pengguna, tetapi tidak dapat mengundang atau menambahkan pengguna ke Google Grup atau aplikasi Chat. Untuk menambahkan dirinya sendiri, aplikasi Chat harus menggunakan autentikasi pengguna dengan cakupan otorisasi chat.memberships.