עדכון מצב הקריאה למרחב המשותף של המשתמש

מדריך זה מסביר איך משתמשים בשיטה updateSpaceReadState במשאב SpaceReadState של Google Chat API כדי לסמן מרחבים משותפים כ'כבר קראתי' או 'עוד לא קראתי'.

המשאב SpaceReadState הוא משאב בודד ב-Google Chat, שמייצג פרטים על ההודעה האחרונה שהמשתמש קרא במרחב המשותף ב-Google Chat.

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

Python

  • Python 3.6 ואילך
  • הכלי pip לניהול חבילות

  • ספריות הלקוח העדכניות של Google ל-Python. כדי להתקין או לעדכן אותן, מריצים את הפקודה הבאה בממשק שורת הפקודה:

    pip3 install --upgrade google-api-python-client google-auth-oauthlib
  • פרויקט ב-Google Cloud עם ממשק Google Chat API פעיל ומוגדר. במאמר איך יוצרים אפליקציה ל-Google Chat מוסבר איך עושים זאת.

  • הוגדרה הרשאה לאפליקציית Chat. כדי לקבל פרטים על מצב הקריאה של משתמש במרחב משותף, צריך אימות משתמש עם היקף ההרשאה chat.users.readstate.

Node.js

  • Node.js ו-npm

  • ספריות הלקוח העדכניות של Google ל-Node.js. כדי להתקין אותם, מריצים את הפקודה הבאה בממשק שורת הפקודה:

    npm install @google-cloud/local-auth @googleapis/chat
  • פרויקט ב-Google Cloud עם ממשק Google Chat API פעיל ומוגדר. במאמר איך יוצרים אפליקציה ל-Google Chat מוסבר איך עושים זאת.

  • הוגדרה הרשאה לאפליקציית Chat. כדי לקבל פרטים על מצב הקריאה של משתמש במרחב משותף, צריך אימות משתמש עם היקף ההרשאה chat.users.readstate.

Apps Script

  • חשבון Google Workspace עם גישה ל-Google Chat.
  • אפליקציה שפורסמה ב-Chat. כדי ליצור אפליקציה ל-Chat, תוכלו להיעזר בquickstart.
  • הוגדרה הרשאה לאפליקציית Chat. כדי לקבל פרטים על מצב הקריאה של משתמש במרחב משותף, צריך אימות משתמש עם היקף ההרשאה chat.users.readstate.

עדכון מצב הקריאה במרחב המשותף של המשתמש המתקשר

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

  • צריך לציין את היקף ההרשאה של chat.users.readstate.
  • קוראים ל-method updateSpaceReadState במשאב SpaceReadState.
  • מעבירים את name של מצב הקריאה של המרחב המשותף, כולל מזהה משתמש או כינוי ומזהה מרחב משותף. קבלת מצב קריאת מרחב תומכת רק בקבלת מצב הקריאה של המשתמש שמתקשר. אפשר לבחור את אחת מהאפשרויות הבאות:
    • כתובת האימייל החלופית של me. לדוגמה, users/me/spaces/SPACE/spaceReadState.
    • כתובת האימייל של המשתמש המתקשר ב-Workspace. לדוגמה, users/user@example.com/spaces/SPACE/spaceReadState.
    • מזהה המשתמש של המשתמש שמתקשר. לדוגמה, users/USER/spaces/SPACE/spaceReadState.
  • מעבירים את updateMask, שמציין את ההיבטים של מצב הקריאה במרחב המשותף שרוצים לעדכן, שתומך בנתיבי השדות הבאים:
    • lastReadTime: השעה שבה מצב הקריאה במרחב המשותף של המשתמש עודכן. בדרך כלל הוא תואם לחותמת הזמן של ההודעה האחרונה שנקראה, או לחותמת הזמן שהמשתמש ציין כדי לסמן את מיקום הקריאה האחרון במרחב. כשהשדה lastReadTime מופיע לפני שעת היצירה של ההודעה האחרונה, המרחב המשותף מופיע בממשק המשתמש כמרחב שלא נקרא. כדי לסמן את המרחב המשותף כנקרא, מגדירים את lastReadTime לערך מאוחר יותר (גדול יותר) מזמן יצירת ההודעה האחרונה. הערך של lastReadTime צריך להתאים לשעת היצירה של ההודעה האחרונה. שימו לב שמצב הקריאה במרחב המשותף משפיע רק על מצב הקריאה של ההודעות הגלויות בשיחה ברמה העליונה של המרחב המשותף. התשובות בשרשורים לא מושפעות מחותמת הזמן הזו, ובמקום זאת מסתמכות על מצב הקריאה של השרשור.

הדוגמה הבאה מעדכנת את מצב הקריאה במרחב המשותף של המשתמש המתקשר:

Python

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

  2. יש לכלול את הקוד הבא ב-chat_spaceReadState_update.py:

    from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.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.users.readstate"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then updates the space read state for the calling user.
    '''

    # Authenticate with Google Workspace
    # and get user authorization.
    flow = InstalledAppFlow.from_client_secrets_file(
                      'client_secrets.json', SCOPES)
    creds = flow.run_local_server()

    # Build a service endpoint for Chat API.
    chat = build('chat', 'v1', credentials=creds)

    # Use the service endpoint to call Chat API.
    result = chat.users().spaces().updateSpaceReadState(

        # The space read state to update.
        #
        # Replace USER with the calling user's ID, Workspace email,
        # or the alias me.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        name='users/me/spaces/SPACE/spaceReadState',
        updateMask='lastReadTime',
        body={'lastReadTime': f'{datetime.datetime(2000, 1, 3).isoformat()}Z'}

      ).execute()

    # Prints the API's response.
    print(result)

if __name__ == '__main__':
    main()

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

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

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

    python3 chat_spaceReadState_update.py

Node.js

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

  2. יש לכלול את הקוד הבא ב-chat_spaceReadState_update:

    const chat = require('@googleapis/chat');
const {authenticate} = require('@google-cloud/local-auth');

/**
* Authenticates with Chat API via user credentials,
* then updates the space read state for the calling user.
* @return {!Promise<!Object>}
*/
async function updateSpaceReadState() {

  /**
  * Authenticate with Google Workspace
  * and get user authorization.
  */
  const scopes = [
    'https://www.googleapis.com/auth/chat.users.readstate',
  ];

  const authClient =
      await authenticate({scopes, keyfilePath: 'client_secrets.json'});

  /**
  * Build a service endpoint for Chat API.
  */
  const chatClient = await chat.chat({version: 'v1', auth: authClient});

  /**
  * Use the service endpoint to call Chat API.
  */
  return await chatClient.users.spaces.updateSpaceReadState({

    /**
    * The space read state to update.
    *
    * Replace USER with the calling user's ID, Workspace email,
    * or the alias me.
    *
    * Replace SPACE with a space name.
    * Obtain the space name from the spaces resource of Chat API,
    * or from a space's URL.
    */
    name: 'users/me/spaces/SPACE/spaceReadState',
    updateMask: 'lastReadTime',
    requestBody: {
      lastReadTime: '{datetime.datetime(2000, 1, 3).isoformat()}Z'
    }
  });
}

/**
* Use the service endpoint to call Chat API.
*/
getSpaceReadState().then(console.log);

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

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

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

    node chat_spaceReadState_update.js

Apps Script

הדוגמה הזו מפעילה את Chat API באמצעות Advanced Chat Service.

  1. מוסיפים את היקף ההרשאה chat.users.readstate לקובץ appsscript.json של פרויקט Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.users.readstate"
]

  2. מוסיפים פונקציה כמו זו לקוד של הפרויקט ב-Apps Script:

    /**
* Authenticates with Chat API via user credentials,
* then updates the space read state for the calling user.
* @param {string} spaceReadStateName The resource name of the space read state.
*/
function updateSpaceReadState(spaceReadStateName) {
  try {
    const time = new Date('January 1, 2000')).toJSON();
    const body = {'lastReadTime': time};
    Chat.Users.Spaces.updateSpaceReadState(spaceReadStateName, body);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to update read state with error %s', err.message);
  }
}

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