עדכון חברות של משתמש במרחב משותף ב-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: חבר/ה במרחב המשותף. למשתמש יש הרשאות בסיסיות, כמו שליחת הודעות למרחב המשותף. בשיחות אישיות ובשיחות קבוצתיות ללא שם, כל המשתתפים הם 'חברים'.
      • 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.

ממשק ה-API של Google Chat מעדכן את החברות שצוינה לניהול המרחב המשותף ומחזיר מופע של 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.

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

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

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

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

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

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

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על Create credentials (יצירת פרטי כניסה) > API key (מפתח API).
  3. מפתח ה-API החדש מוצג.
    • צריך ללחוץ על 'העתקה' כדי להעתיק את מפתח ה-API לשימוש בקוד האפליקציה. תוכלו למצוא את מפתח ה-API גם בקטע API Keys (מפתחות 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: שם המרחב, שאפשר לקבל באמצעות ה-method spaces.list ב-Chat API או מכתובת ה-URL של המרחב.

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

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

    python3 chat_membership_update_to_manager_app.py

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

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

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

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

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

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על Create credentials (יצירת פרטי כניסה) > API key (מפתח API).
  3. מפתח ה-API החדש מוצג.
    • צריך ללחוץ על 'העתקה' כדי להעתיק את מפתח ה-API לשימוש בקוד האפליקציה. תוכלו למצוא את מפתח ה-API גם בקטע API Keys (מפתחות API) בפרטי הכניסה של הפרויקט.
    • לוחצים על Restrict key כדי לעדכן את ההגדרות המתקדמות ולהגביל את השימוש במפתח ה-API. פרטים נוספים זמינים במאמר החלת הגבלות על מפתחות API.

כתיבת סקריפט שמפעיל את Chat API

בדוגמה הבאה מפעילים את ה-API של Chat באמצעות אימות אפליקציות כדי להפוך את המנהל של המרחב המשותף למשתמש רגיל. לשם כך, מציינים את הערך 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.

כדי להפעיל את השיטה הזו כאדמינים ב-Google Workspace:

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

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