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

במדריך הזה מוסבר איך להשתמש ב-method‏ 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 הוא people/123456789, צריך להשתמש בערך users/123456789.resourceName
      • המזהה של המשתמש ב-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: מזהה משתמש.

‏Chat API מחזיר מופע של 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 של המרחב המשותף. אפשר לקבל את המזהה על ידי קריאה ל-method‏ ListSpaces() או מכתובת ה-URL של המרחב המשותף.
  • GROUP_NAME: מזהה קבוצה.

‏Chat API מחזיר מופע של 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 של המרחב המשותף. אפשר לקבל את המזהה על ידי קריאה ל-method‏ ListSpaces() או מכתובת ה-URL של המרחב המשותף.

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

איך מזמינים או מוסיפים משתמשים למרחב משותף דרך אפליקציית Chat

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

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

  • מציינים את היקף ההרשאה chat.app.memberships.
  • קוראים לשיטה create במשאב membership.
  • מגדירים את parent לשם המשאב של המרחב המשותף שבו רוצים ליצור את החברות.
  • מגדירים את member כ-users/{user}, כאשר {user} הוא האדם שעבורו רוצים ליצור את החברות, והוא יכול להיות:
    • המזהה של האדם ב-People API. לדוגמה, אם הערך של person ב-People API הוא people/123456789, צריך להגדיר את membership.member.name לערך users/123456789.resourceName
    • המזהה של המשתמש ב-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 (מפתח API).
  3. מפתח ה-API החדש מוצג.
    • לוחצים על סמל ההעתקה כדי להעתיק את מפתח ה-API לשימוש בקוד של האפליקציה. אפשר למצוא את מפתח ה-API גם בקטע 'מפתחות 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. בספריית העבודה, יוצרים ומריצים את הדוגמה:

    python3 chat_membership_app_create.py

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

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

כדי לקרוא ל-method הזה כאדמינים ב-Google Workspace:

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

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

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

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