איך מזמינים משתמשים, קבוצות ב-Google או אפליקציית Google Chat למרחבים משותפים

במדריך הזה מוסבר איך להשתמש בשיטה create() במשאב Membership של Google Chat API כדי להזמין או להוסיף משתמש, קבוצת Google או אפליקציה ל-Chat למרחב, או במילים אחרות, ליצור חברות. כשיוצרים חברות, אם המדיניות של החבר שצוין לגבי אישור אוטומטי מושבתת, הוא מוזמן וצריך לאשר את ההזמנה למרחב לפני שהוא מצטרף. אחרת, כשיוצרים חברות, המשתמש מצורף ישירות למרחב שצוין.

אדמינים ב-Google Workspace יכולים להוסיף משתמשים, קבוצות Google או אפליקציות ל-Chat לכל מרחב בארגון שלהם ב-Google Workspace.

המשאב Membership מייצג אם משתמש אנושי או אפליקציית Google Chat הוזמנו למרחב, הם חלק ממנו או שהם לא נמצאים בו.

דרישות מוקדמות

Node.js

Python

Java

Apps Script

הזמנה או הוספה של משתמש למרחב כמשתמש

כדי להזמין או להוסיף משתמש למרחב עם אימות משתמש, צריך להעביר את הפרטים הבאים בבקשה:

  • מציינים את chat.memberships היקף ההרשאה.
  • מבצעים קריאה ל-method‏ CreateMembership().
  • מעבירים את parent כשם המשאב של המרחב שבו רוצים ליצור את החברות.
  • מעבירים את membership כמופע של Membership כשהשדה member שלו מוגדר עם הערכים הבאים:
    • השדה type מוגדר ל-HUMAN.
    • השדה name מוגדר ל-users/{user}, כאשר {user} הוא האדם שרוצים להוסיף למרחב. כדי לציין את המשתמש ב-Chat, מחליפים את {user} באחת מהאפשרויות הבאות:
      • המזהה של האדם ב-People API. לדוגמה, אם הערך של person ב-People API‏ resourceName הוא people/123456789, צריך להשתמש בערך users/123456789.
      • המזהה של המשתמש ב-Directory API.
      • כתובת האימייל של המשתמש. לדוגמה, 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()

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

כדי להריץ את הדוגמה, מחליפים את הערכים הבאים:

  • ‫SPACE_NAME: המזהה מname של המרחב. אפשר לקבל את המזהה על ידי הפעלת השיטה ListSpaces() או מכתובת ה-URL של המרחב.
  • ‫USER_NAME: מזהה משתמש.

ה-API של Chat מחזיר מופע של Membership שמפרט את חברות המשתמש שנוצרה.

איך מזמינים או מצרפים קבוצות ב-Google למרחבים

כדי להזמין או להוסיף קבוצה ב-Google לחלל עם אימות משתמש (אימות אפליקציה לא תומך בהזמנה או בהוספה של קבוצה ב-Google לחלל), צריך להעביר את הפרטים הבאים בבקשה:

  • מציינים את chat.memberships היקף ההרשאה.
  • מבצעים קריאה ל-method‏ CreateMembership().
  • מעבירים את parent כשם המשאב של המרחב שבו רוצים ליצור את החברות.
  • מעבירים את membership כעותק של Membership עם השדה name של groupMember שמוגדר ל-groups/{group}, כאשר {group} הוא מזהה הקבוצה שרוצים ליצור חברות בה. אפשר לאחזר את המזהה של הקבוצה באמצעות Cloud Identity API.

אי אפשר להוסיף קבוצות מ-Google Groups לצ'אטים קבוצתיים או לצ'אטים ישירים, אלא רק למרחבים עם שם.

בדוגמה הבאה מוסיפים קבוצה למרחב עם שם שמוגדר בו אימות משתמשים:

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

כדי להריץ את הדוגמה, מחליפים את הערכים הבאים:

  • ‫SPACE_NAME: המזהה מname של המרחב. אפשר לקבל את המזהה על ידי הפעלת השיטה ListSpaces() או מכתובת ה-URL של המרחב.
  • ‫GROUP_NAME: מזהה קבוצה.

ה-API של Chat מחזיר מופע של Membership שמפרט את חברות המשתמש שנוצרה.

איך מוסיפים אפליקציות ל-Chat למרחבים

אפליקציה ב-Chat לא יכולה להוסיף אפליקציה אחרת כמשתתפת בחלל. כדי להוסיף אפליקציית Chat למרחב או לצ'אט ישיר בין שני משתמשים אנושיים, צריך להעביר את הפרטים הבאים בבקשה עם אימות משתמש (אימות אפליקציה לא תומך בהזמנה או בהוספה של אפליקציית Chat למרחב):

  • מציינים את chat.memberships.app היקף ההרשאה.
  • מבצעים קריאה ל-method‏ CreateMembership().
  • מעבירים את parent כשם המשאב של המרחב שבו רוצים ליצור את החברות.
  • מעבירים את membership כמופע של Membership כשהשדה member שלו מוגדר עם הערכים הבאים:
    • השדה type מוגדר ל-BOT.
    • השדה 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()

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

כדי להריץ את הדוגמה, מחליפים את SPACE_NAME במזהה מname של המרחב. אפשר לקבל את המזהה על ידי הפעלת השיטה ListSpaces() או מכתובת ה-URL של המרחב.

ה-API של Chat מחזיר מופע של Membership שמפרט את חברות המשתמש שנוצרה.

הזמנה או הוספה של משתמש למרחב כאפליקציית Chat

כדי לאמת אפליקציה, צריך אישור אדמין חד-פעמי.

כדי להזמין או להוסיף משתמש למרחב עם אימות אפליקציה, צריך להעביר את הפרטים הבאים בבקשה:

  • מציינים את chat.app.memberships היקף ההרשאה.
  • מפעילים את השיטה create במשאב membership.
  • מגדירים את parent לשם המשאב של המרחב שבו רוצים ליצור את החברות.
  • מגדירים את member ל-users/{user}, כאשר {user} הוא האדם שרוצים ליצור עבורו חברות, והוא יכול להיות:
    • המזהה של האדם ב-People API. לדוגמה, אם הערך של person ב-People API‏ resourceName הוא people/123456789, צריך להגדיר את membership.member.name כ-users/123456789.
    • המזהה של המשתמש ב-Directory API.
    • כתובת האימייל של המשתמש. לדוגמה, users/222larabrown@gmail.com או users/larabrown@cymbalgroup.com. אם המשתמש משתמש בחשבון Google או שייך לארגון אחר ב-Google Workspace, צריך להשתמש בכתובת האימייל שלו.

יצירה של מפתח API

כדי לקרוא ל-method של API בגרסת טרום-השקה למפתחים, צריך להשתמש בגרסת טרום-השקה למפתחים של מסמך גילוי ה-API, שאינה ציבורית. כדי לאמת את הבקשה, צריך להעביר מפתח API.

כדי ליצור את מפתח ה-API, פותחים את פרויקט Google Cloud של האפליקציה ומבצעים את הפעולות הבאות:

  1. במסוף Google Cloud, לוחצים על סמל התפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על Create credentials > API key.
  3. מפתח ה-API החדש מוצג.
    • לוחצים על סמל ההעתקה כדי להעתיק את מפתח ה-API לשימוש בקוד של האפליקציה. אפשר גם למצוא את מפתח ה-API בקטע API keys (מפתחות API) בפרטי הכניסה של הפרויקט.
    • לוחצים על Restrict key כדי לעדכן את ההגדרות המתקדמות ולהגביל את השימוש במפתח ה-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: מפתח ה-API שיצרתם כדי לבנות את נקודת הקצה של השירות עבור Chat API.

    • ‫SPACE: שם המרחב, שאפשר לקבל באמצעות השיטה spaces.list ב-Chat API, או מכתובת ה-URL של המרחב.

    • ‫USER: מזהה משתמש.

  4. בספריית העבודה, מבצעים build ומריצים את הדוגמה:

    python3 chat_membership_app_create.py

איך אדמינים ב-Google Workspace מוסיפים משתמשים או קבוצות Google למרחבים

אדמינים ב-Google Workspace יכולים להשתמש בשיטת create() כדי להוסיף משתמשים, קבוצות Google או אפליקציות ל-Chat לכל מרחב בארגון שלהם ב-Google Workspace.

כדי להפעיל את ה-method הזה כאדמינים ב-Google Workspace, צריך לבצע את הפעולות הבאות:

  • קוראים ל-method באמצעות אימות משתמש, ומציינים היקף הרשאות שתומך בקריאה ל-method באמצעות הרשאות אדמין.
  • בבקשה, מציינים את פרמטר השאילתה useAdminAccess כ-true.

מידע נוסף ודוגמאות זמינים במאמר ניהול מרחבים ב-Google Chat כאדמינים ב-Google Workspace.

מגבלות ושיקולים

  • באמצעות אימות אפליקציות, אפליקציית Chat יכולה להזמין או להוסיף משתמשים, אבל לא קבוצות Google או אפליקציות Chat. כדי להוסיף את עצמה, אפליקציית Chat צריכה להשתמש באימות משתמשים עם היקף ההרשאה chat.memberships.