עדכון חברות של משתמש במרחב משותף ב-Google Chat

במדריך הזה נסביר איך משתמשים ב-method‏ update() במשאב Membership של Google Chat API כדי לשנות מאפיינים של חברות במרחב משותף, למשל שינוי של משתתף במרחב משותף למנהל מרחב משותף, או שינוי של מנהל מרחב משותף למשתתף במרחב משותף.

אדמינים ב-Google Workspace יכולים להפעיל את השיטה update() כדי לעדכן את החברים במרחבים משותפים בארגון ב-Google Workspace.

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

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

Node.js

עדכון מינוי

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

  • מציינים היקף הרשאה:
    • באימות משתמש, מציינים את היקף ההרשאה chat.memberships.
    • באימות האפליקציה (זמין בגרסת Developer Preview), מציינים את היקף ההרשאה chat.app.memberships. כשאתם מעדכנים את החברות באמצעות אימות באפליקציה, אתם יכולים לעדכן את החברות רק במרחבים משותפים שנוצרו באפליקציות של Chat. כדי לאמת אפליקציה, נדרש אישור אדמין חד-פעמי.
  • קוראים ל-method‏ UpdateMembership().
  • מעבירים את membership כמכונה של Membership באמצעות הקוד הבא:
    • השדה name מוגדר לחברות שרוצים לעדכן, והוא כולל מזהה מרחב משותף ומזהה חבר.
    • שדות החברות שרוצים לעדכן מוגדרים לערכים החדשים.
  • מעבירים את הערך updateMask כדי לציין את ההיבטים של החברות שרוצים לעדכן. הערך כולל את הפרטים הבאים:
    • role: התפקיד של המשתמש במרחב המשותף ב-Chat, שמגדיר את הפעולות שהוא יכול לבצע במרחב. הערכים האפשריים הם:
      • ROLE_MEMBER: חבר/ה במרחב המשותף. למשתמש יש הרשאות בסיסיות, כמו שליחת הודעות למרחב המשותף. בשיחות 1:1 ובשיחות קבוצתיות ללא שם, כל המשתתפים הם 'חברים'.
      • ROLE_MANAGER: מנהל/ת המרחב המשותף. למשתמש יש את כל ההרשאות הבסיסיות וגם הרשאות ניהול שמאפשרות לו לנהל את המרחב המשותף, כמו הוספה או הסרה של משתמשים. התכונה נתמכת רק במרחבים משותפים שבהם הערך של spaceType הוא SPACE (מרחבים משותפים עם שם).

איך הופכים משתמש רגיל במרחב משותף למנהל/ת של המרחב המשותף בתור משתמש

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

Node.js

chat/client-libraries/cloud/update-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 update a membership with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    membership: {
      // Replace SPACE_NAME and MEMBER_NAME here
      name: 'spaces/SPACE_NAME/members/MEMBER_NAME',
      // Replace ROLE_NAME here with ROLE_MEMBER or ROLE_MANAGER
      role: 'ROLE_NAME'
    },
    updateMask: {
      // The field paths to update.
      paths: ['role']
    }
  };

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

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

main().catch(console.error);

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

  • SPACE_NAME: המזהה מ-name של המרחב המשותף. אפשר לקבל את המזהה על ידי קריאה ל-method‏ ListSpaces() או מכתובת ה-URL של המרחב המשותף.
  • ‫MEMBER_NAME: המזהה מ-name של המינוי. אפשר לקבל את המזהה באמצעות קריאה ל-method‏ ListMemberships(), או מגוף התגובה שמוחזר אחרי יצירת חברות באופן אסינכרוני באמצעות Chat API.
  • ROLE_NAME: התפקיד המעודכן, ROLE_MANAGER.

Google Chat API מעדכן את החברות שצוינה כמנהל המרחב המשותף ומחזיר מופע של Membership.

איך הופכים מנהל מרחב משותף למשתמש רגיל

בדוגמה הבאה מתבצעת קריאה ל-Chat API באמצעות אימות משתמש כדי להפוך מנהל מרחב משותף למשתתף רגיל במרחב המשותף, על ידי ציון role בתור ROLE_MEMBER:

Node.js

chat/client-libraries/cloud/update-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 update a membership with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    membership: {
      // Replace SPACE_NAME and MEMBER_NAME here
      name: 'spaces/SPACE_NAME/members/MEMBER_NAME',
      // Replace ROLE_NAME here with ROLE_MEMBER or ROLE_MANAGER
      role: 'ROLE_NAME'
    },
    updateMask: {
      // The field paths to update.
      paths: ['role']
    }
  };

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

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

main().catch(console.error);

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

  • SPACE_NAME: המזהה מ-name של המרחב המשותף. אפשר לקבל את המזהה על ידי קריאה ל-method‏ ListSpaces() או מכתובת ה-URL של המרחב המשותף.
  • ‫MEMBER_NAME: המזהה מ-name של המינוי. אפשר לקבל את המזהה באמצעות קריאה ל-method‏ ListMemberships(), או מגוף התגובה שמוחזר אחרי יצירת חברות באופן אסינכרוני באמצעות Chat API.
  • ROLE_NAME: התפקיד המעודכן, ROLE_MEMBER.

Google Chat API מעדכן את החברות שצוינה כמנהל המרחב המשותף ומחזיר מופע של Membership.

איך הופכים משתתף רגיל במרחב משותף למנהל שלו באפליקציית Chat

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

יצירה של מפתח 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

בדוגמה הבאה מוצגת קריאה ל-Chat API באמצעות אימות אפליקציה כדי להפוך חבר רגיל במרחב משותף למנהל של המרחב. לשם כך, מציינים את role בתור ROLE_MANAGER ב-body שמציין את מאפייני החברות המעודכנים:

Python

  1. בספריית העבודה, יוצרים קובץ בשם chat_membership_update_to_manager_app.py.

  2. מוסיפים את הקוד הבא ל-chat_membership_update_to_manager_app.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 updates a specified space member to change
    it from a regular member to a space manager.
    '''

    # 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().patch(

        # The membership to update, and the updated role.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        #
        # Replace MEMBERSHIP with a membership name.
        # Obtain the membership name from the membership of Chat API.
        name='spaces/SPACE/members/MEMBERSHIP',
        updateMask='role',
        body={'role': 'ROLE_MANAGER'}

      ).execute()

    # Prints details about the updated membership.
    print(result)

if __name__ == '__main__':
    main()

  3. בקוד, מחליפים את הפרטים הבאים:

    • API_KEY: מפתח ה-API שיצרתם כדי ליצור את נקודת הקצה של השירות ל-Chat API.

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

    • MEMBERSHIP: שם המינוי, שאפשר לקבל מ-method‏ spaces.members.list ב-Chat API.

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

    python3 chat_membership_update_to_manager_app.py

איך הופכים מנהל מרחב משותף למשתתף רגיל באפליקציית Chat

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

יצירה של מפתח 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

בדוגמה הבאה מוצגת קריאה ל-Chat API באמצעות אימות אפליקציה כדי להפוך מנהל מרחב משותף לחבר רגיל במרחב המשותף. לשם כך, מציינים את role בתור ROLE_MEMBER ב-body שמציין את מאפייני החברות המעודכנים:

Python

  1. בספריית העבודה, יוצרים קובץ בשם chat_membership_update_to_member_app.py.

  2. מוסיפים את הקוד הבא ל-chat_membership_update_to_member_app.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 via user credentials,
    then updates a specified space member to change
    it from a regular member to a space manager.
    '''

    # 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().patch(

        # The membership to update, and the updated role.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        #
        # Replace MEMBERSHIP with a membership name.
        # Obtain the membership name from the membership of Chat API.
        name='spaces/SPACE/members/MEMBERSHIP',
        updateMask='role',
        body={'role': 'ROLE_MEMBER'}

      ).execute()

    # Prints details about the updated membership.
    print(result)

if __name__ == '__main__':
    main()

  3. בקוד, מחליפים את הפרטים הבאים:

    • API_KEY: מפתח ה-API שיצרתם כדי ליצור את נקודת הקצה של השירות ל-Chat API.

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

    • MEMBERSHIP: שם המינוי, שאפשר לקבל מ-method ‏spaces.members.list ב-Chat API.

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

    python3 chat_membership_update_to_member_app.py

עדכון החברויות כאדמינים ב-Google Workspace

אדמינים ב-Google Workspace יכולים להפעיל את השיטה update() כדי לעדכן את החברים בכל מרחב משותף בארגון שלהם ב-Google Workspace.

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

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

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