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

במדריך הזה מוסבר איך להשתמש בשיטה setUp() במשאב Space של Google Chat API כדי ליצור מרחב ב-Chat ולהוסיף אליו משתתפים.

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

  • צ'אטים ישירים הם שיחות בין שני משתמשים או בין משתמש לבין אפליקציית Chat.
  • צ'אטים קבוצתיים הם שיחות בין שלושה משתמשים או יותר לבין אפליקציות ל-Chat.
  • מרחבים משותפים עם שם הם מקומות קבועים שבהם אנשים יכולים לשלוח הודעות, לשתף קבצים ולעבוד יחד.

אפשר להשתמש בשיטה setUp() כדי לבצע כל אחת מהפעולות הבאות:

  • יוצרים מרחב עם שם וחברים ראשוניים.
  • ליצור צ'אט ישיר בין שני אנשים.
  • להגדיר צ'אט קבוצתי עם כמה אנשים.

כשמגדירים מרחב, כדאי לקחת בחשבון את הנקודות הבאות:

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

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

Node.js

Python

Java

Apps Script

הגדרת מרחב

כדי להגדיר מרחב, מעבירים את הפרטים הבאים בבקשה:

  • מציינים את היקף ההרשאות של chat.spaces.create או chat.spaces.
  • מבצעים קריאה ל-method‏ SetUpSpace().
  • מעבירים את space כמופע של Space עם כל השדות הנדרשים, כמו displayName או spaceType.
  • מעבירים את memberships כמערך של מופעי Membership. לכל מופע:
    • מציינים users/{user} כדי להוסיף משתמש אנושי כחבר במרחב, כאשר {user} הוא {person_id} של person מ-People API, או המזהה של user ב-Directory API. לדוגמה, אם הערך של resourceName באובייקט person של People API הוא people/123456789, אפשר להוסיף את המשתמש למרחב על ידי הוספת חברות עם users/123456789 כ-member.name.
    • מציינים groups/{group} כדי להוסיף קבוצה כמשתתפת במרחב, כאשר {group} הוא מזהה הקבוצה שרוצים ליצור לה חברות. אפשר לאחזר את המזהה של הקבוצה באמצעות Cloud Identity API. לדוגמה, אם Cloud Identity API מחזיר קבוצה עם השם groups/123456789, צריך להגדיר את membership.groupMember.name כ-groups/123456789. אי אפשר להוסיף קבוצות מ-Google Groups לצ'אטים קבוצתיים או לצ'אטים ישירים, אלא רק למרחבים עם שם.

כדי ליצור צ'אט ישיר בין המשתמש המתקשר לבין משתמש אנושי אחר, צריך לציין את החברות של המשתמש האנושי בבקשה.

כדי ליצור צ'אט ישיר בין המשתמש המתקשר לבין האפליקציה המתקשרת, מגדירים את space.singleUserBotDm ל-true ולא מציינים חברות כלשהי. אפשר להשתמש בשיטה הזו רק כדי להגדיר צ'אט ישיר עם אפליקציית הטלפון. כדי להוסיף את אפליקציית הטלפון כמשתתפת במרחב או בצ'אט ישיר קיים בין שני משתמשים, אפשר לעיין במאמר בנושא יצירת חברות.

בדוגמה הבאה נוצר מרחב עם שם, ונוצרת חברות אחת במרחב עבור שני משתמשים אנושיים (המשתמש המאומת ומשתמש נוסף).

Node.js

chat/client-libraries/cloud/set-up-space-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.spaces.create'];

// This sample shows how to set up a named space with one initial member
// with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    space: {
      spaceType: 'SPACE',
      // Replace DISPLAY_NAME here.
      displayName: 'DISPLAY_NAME'
    },
    memberships: [{
      member: {
        // Replace USER_NAME here.
        name: 'users/USER_NAME',
        type: 'HUMAN'
      }
    }]
  };

  // Make the request
  const response = await chatClient.setUpSpace(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/set_up_space_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.spaces.create"]

def set_up_space_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.SetUpSpaceRequest(
        space = {
            "space_type": 'SPACE',
            # Replace DISPLAY_NAME here.
            "display_name": 'DISPLAY_NAME'
        },
        memberships = [{
            "member": {
                # Replace USER_NAME here.
                "name": 'users/USER_NAME',
                "type_": 'HUMAN'
            }
        }]
    )

    # Make the request
    response = client.set_up_space(request)

    # Handle the response
    print(response)

set_up_space_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/SetUpSpaceUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SetUpSpaceRequest;
import com.google.chat.v1.Space;
import com.google.chat.v1.User;

// This sample shows how to set up a named space with one initial member with
// user credential.
public class SetUpSpaceUserCred {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.spaces.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      SetUpSpaceRequest.Builder request = SetUpSpaceRequest.newBuilder()
        .setSpace(Space.newBuilder()
          .setSpaceType(Space.SpaceType.SPACE)
          // Replace DISPLAY_NAME here.
          .setDisplayName("DISPLAY_NAME"))
        .addAllMemberships(ImmutableList.of(Membership.newBuilder()
          .setMember(User.newBuilder()
            // Replace USER_NAME here.
            .setName("users/USER_NAME")
            .setType(User.Type.HUMAN)).build()));
      Space response = chatServiceClient.setUpSpace(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to set up a named space with one initial member with
 * user credential.
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.spaces.create'
 * referenced in the manifest file (appsscript.json).
 */
function setUpSpaceUserCred() {
  // Initialize request argument(s)
  const space = {
    spaceType: 'SPACE',
    // TODO(developer): Replace DISPLAY_NAME here
    displayName: 'DISPLAY_NAME'
  };
  const memberships = [{
    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.setup({ space: space, memberships: memberships });

  // Handle the response
  console.log(response);
}

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

  • ‫DISPLAY_NAME: השם המוצג של המרחב החדש.
  • ‫USER_NAME: המזהה של המשתמש השני שרוצים לכלול את החברות שלו.

כדי לעבור לחלל, משתמשים במזהה המשאב של החלל כדי ליצור את כתובת ה-URL של החלל. אפשר לקבל את מזהה מקור המידע מהמרחב name בגוף התגובה של Google Chat. לדוגמה, אם המזהה של המרחב name הוא spaces/1234567, אפשר להיכנס למרחב באמצעות כתובת ה-URL הבאה: https://mail.google.com/chat/u/0/#chat/space/1234567.