Zarządzanie dostępnością użytkowników w przypadku aplikacji na czacie

Ten przewodnik wyjaśnia, jak używać interfejsu Google Chat API do zarządzania stanem dostępności i stanem niestandardowym użytkownika.

Aby odczytać i zaktualizować dostępność użytkownika Google Chat, Twoja aplikacja musi uwierzytelnić się za pomocą uwierzytelniania użytkownika. Dostępna jest tylko dostępność uwierzytelnionego użytkownika, którą można modyfikować.

Wymagania wstępne

Node.js

Python

Java

Apps Script

Pobieranie dostępności użytkownika

Aby odczytać dostępność użytkownika Google Chat, w żądaniu podaj te informacje:

  • Określ zakres autoryzacji chat.users.availability.readonly lub chat.users.availability.
  • Wywołaj metodę GetAvailability.
  • Przekaż name zasobu dostępności do pobrania. Nazwa musi mieć format users/{user}/availability. Aby odwołać się do dzwoniącego, możesz użyć adresu e-mail użytkownika lub aliasu me. Na przykład users/me/availability.

Oto jak uzyskać dostępność użytkownika:

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);
  }
}

Interfejs Chat API zwraca instancję Availability zawierającą informacje o stanie obecności i stanie niestandardowym użytkownika.

Aktualizowanie stanu niestandardowego

Aby zaktualizować stan niestandardowy użytkownika, w żądaniu podaj te informacje:

  • Określ zakres autoryzacji chat.users.availability.
  • Wywołaj UpdateAvailability metodę.
  • Przekaż zasób Availability, określając nowe szczegóły customStatus.
  • Ustaw parametr update_mask, aby uwzględnić pole custom_status.

Oto jak zaktualizować stan niestandardowy użytkownika:

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);
  }
}

Interfejs Chat API aktualizuje i zwraca instancję Availability z nowym stanem niestandardowym.

Aby wyczyścić stan niestandardowy użytkownika, zaktualizuj dostępność i pomiń szczegóły customStatus.

Aktualizowanie stanu obecności

W zależności od docelowego stanu obecności możesz zaktualizować dostępność użytkownika, wywołując jedną z tych metod niestandardowych:

  • Aktywny: wywołaj metodę MarkAsActive , aby ustawić stan obecności jako aktywny. Możesz podać opcjonalne wartości wygaśnięcia (ttl lub expireTime).
  • Zaraz wracam: wywołaj metodę MarkAsAway , aby ustawić stan obecności jako zaraz wracam.
  • Nie przeszkadzać: wywołaj metodę MarkAsDoNotDisturb , aby wyciszyć powiadomienia.

Szczegółowe informacje, w tym opisy pól i szablony zapytań, znajdziesz w przewodniku po każdej metodzie.

Określanie zmian dostępności na podstawie zdarzenia

Twoja aplikacja Chat może subskrybować zdarzenia google.workspace.chat.availability.v1.updated, aby otrzymywać powiadomienia o zmianie dostępności użytkownika. Gdy nastąpi aktualizacja dostępności, aplikacja otrzyma zdarzenie z ładunkiem zawierającym zasób Availability.