ניהול הזמינות של משתמשים באפליקציות צ'אט

במדריך הזה מוסבר איך להשתמש ב-Google Chat API כדי לנהל את סטטוס הזמינות והסטטוס המותאם אישית של משתמש.

כדי לקרוא ולעדכן את הזמינות של משתמש ב-Chat, האפליקציה צריכה לעבור אימות באמצעות אימות משתמשים. אפשר לגשת רק לזמינות של המשתמש המאומת או לשנות אותה.

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

Node.js

Python

Java

Apps Script

איך בודקים את הזמינות של משתמש

כדי לקרוא את סטטוס הזמינות של משתמש ב-Google Chat, צריך להעביר את הפרטים הבאים בבקשה:

  • מציינים את היקף ההרשאות של chat.users.availability.readonly או chat.users.availability.
  • מבצעים קריאה ל-method‏ GetAvailability.
  • מעבירים את name של משאב הזמינות לאחזור. השם צריך להיות בתבנית users/{user}/availability. אפשר להשתמש בכתובת האימייל של המשתמש או בכינוי me כדי להתייחס למתקשר. לדוגמה, users/me/availability.

כך בודקים את הזמינות של משתמש:

Node.js

const { ChatServiceClient } = require('@google-apps/chat').v1;

// Instantiates a client
const chatServiceClient = new ChatServiceClient();

async function getAvailability() {
  const request = {
    // The name of the availability resource to retrieve.
    // Format: users/{user}/availability
    // The 'me' alias can be used to refer to the calling user.
    name: 'users/me/availability',
  };

  try {
    const response = await chatServiceClient.getAvailability(request);
    console.log(response);
  } catch (err) {
    console.error('Error retrieving availability:', err);
  }
}

getAvailability();

Python

from google.apps import chat_v1 as google_chat

def get_availability():
    # Instantiates a client
    client = google_chat.ChatServiceClient()

    # Prepare request
    request = google_chat.GetAvailabilityRequest(
        # Format: users/{user}/availability
        # The 'me' alias refers to the calling user.
        name="users/me/availability",
    )

    # Call the API
    try:
        response = client.get_availability(request=request)
        print(response)
    except Exception as e:
        print(f"Error retrieving availability: {e}")

get_availability()

Java

import com.google.chat.v1.Availability;
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.GetAvailabilityRequest;

public class GetAvailability {
  public static void main(String[] args) throws Exception {
    // Instantiates a client
    try (ChatServiceClient chatServiceClient = ChatServiceClient.create()) {
      GetAvailabilityRequest request = GetAvailabilityRequest.newBuilder()
          // Format: users/{user}/availability
          // The 'me' alias refers to the calling user.
          .setName("users/me/availability")
          .build();

      Availability response = chatServiceClient.getAvailability(request);
      System.out.println(response);
    }
  }
}

Apps Script

/**
 * Retrieves the calling user's availability details.
 */
function getUserAvailability() {
  const name = 'users/me/availability';
  try {
    const availability = Chat.Users.Availability.get(name);
    console.log(availability);
  } catch (err) {
    console.error('Failed to get availability: ' + err.message);
  }
}

‫Chat API מחזיר מופע של Availability שמפרט את סטטוס הנוכחות של המשתמש ואת הסטטוס המותאם אישית שלו.

עדכון סטטוס מותאם אישית

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

  • מציינים את chat.users.availability היקף ההרשאה.
  • מבצעים קריאה ל-method‏ UpdateAvailability.
  • מעבירים את המשאב Availability ומציינים את הפרטים החדשים customStatus.
  • מגדירים את הפרמטר update_mask כך שיכלול את השדה custom_status.

כך מעדכנים את הסטטוס המותאם אישית של משתמש:

Node.js

const { ChatServiceClient } = require('@google-apps/chat').v1;

// Instantiates a client
const chatServiceClient = new ChatServiceClient();

async function updateCustomStatus() {
  const request = {
    // The Availability resource to update.
    availability: {
      name: 'users/me/availability',
      customStatus: {
        text: 'In a meeting',
        emoji: {
          unicode: '📅'
        }
      }
    },
    // The fields to update. Must contain 'custom_status'.
    updateMask: {
      paths: ['custom_status']
    }
  };

  try {
    const response = await chatServiceClient.updateAvailability(request);
    console.log(response);
  } catch (err) {
    console.error('Error updating status:', err);
  }
}

updateCustomStatus();

Python

from google.apps import chat_v1 as google_chat
from google.protobuf import field_mask_pb2

def update_custom_status():
    # Instantiates a client
    client = google_chat.ChatServiceClient()

    # Define custom status and emoji
    custom_status = google_chat.CustomStatus(
        text="In a meeting",
        emoji=google_chat.Emoji(unicode="📅")
    )

    # Initialize availability object
    availability = google_chat.Availability(
        name="users/me/availability",
        custom_status=custom_status
    )

    # Specify update mask
    update_mask = field_mask_pb2.FieldMask(paths=["custom_status"])

    # Prepare request
    request = google_chat.UpdateAvailabilityRequest(
        availability=availability,
        update_mask=update_mask
    )

    # Call the API
    try:
        response = client.update_availability(request=request)
        print(response)
    except Exception as e:
        print(f"Error updating status: {e}")

update_custom_status()

Java

import com.google.chat.v1.Availability;
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CustomStatus;
import com.google.chat.v1.Emoji;
import com.google.chat.v1.UpdateAvailabilityRequest;
import com.google.protobuf.FieldMask;

public class UpdateCustomStatus {
  public static void main(String[] args) throws Exception {
    // Instantiates a client
    try (ChatServiceClient chatServiceClient = ChatServiceClient.create()) {
      CustomStatus customStatus = CustomStatus.newBuilder()
          .setText("In a meeting")
          .setEmoji(Emoji.newBuilder().setUnicode("📅"))
          .build();

      Availability availability = Availability.newBuilder()
          .setName("users/me/availability")
          .setCustomStatus(customStatus)
          .build();

      FieldMask updateMask = FieldMask.newBuilder()
          .addPaths("custom_status")
          .build();

      UpdateAvailabilityRequest request = UpdateAvailabilityRequest.newBuilder()
          .setAvailability(availability)
          .setUpdateMask(updateMask)
          .build();

      Availability response = chatServiceClient.updateAvailability(request);
      System.out.println(response);
    }
  }
}

Apps Script

/**
 * Updates the calling user's custom status message.
 */
function updateCustomStatus() {
  const name = 'users/me/availability';
  const availability = {
    customStatus: {
      text: 'In a meeting',
      emoji: {
        unicode: '📅'
      }
    }
  };
  const updateMask = 'custom_status';

  try {
    const response = Chat.Users.Availability.patch(availability, name, {
      updateMask: updateMask
    });
    console.log(response);
  } catch (err) {
    console.error('Failed to update status: ' + err.message);
  }
}

ה-Chat API מתעדכן ומחזיר מופע של Availability עם הסטטוס החדש בהתאמה אישית.

כדי לנקות את הסטטוס המותאם אישית של משתמש, מעדכנים את הזמינות ומשמיטים את הפרטים של customStatus.

עדכון סטטוס הנוכחות

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

  • פעיל: כדי להגדיר את הנוכחות כפעילה, קוראים לשיטה MarkAsActive. אפשר לציין ערכי תפוגה אופציונליים (ttl או expireTime).
  • תכף אשוב: כדי לשנות את הסטטוס ל'תכף אשוב', צריך להפעיל את ה-method‏ MarkAsAway.
  • נא לא להפריע: כדי להשתיק את ההתראות, קוראים לשיטה MarkAsDoNotDisturb.

פרטים נוספים, כולל תיאורי שדות ותבניות של שאילתות, זמינים במדריך לכל שיטה.

זיהוי שינויים בזמינות מתוך אירוע

אפליקציית Chat יכולה להירשם לgoogle.workspace.chat.availability.v1.updated אירועים כדי לקבל התראות כשמשתנה הזמינות של משתמש. כשמתרחש עדכון זמינות, האפליקציה מקבלת אירוע עם מטען ייעודי (payload) שמכיל את המשאב Availability.