Chat 앱의 사용자 사용 가능 여부 관리

이 가이드에서는 Google Chat API를 사용하여 사용자의 사용 가능 여부 상태와 맞춤 상태를 관리하는 방법을 설명합니다.

Chat 사용자의 사용 가능 여부를 읽고 업데이트하려면 앱이 사용자 인증으로 인증해야 합니다. 인증된 사용자의 사용 가능 여부만 액세스하거나 수정할 수 있습니다.

기본 요건

Node.js

Python

자바

Apps Script

사용자의 사용 가능 여부 가져오기

Google Chat 사용자의 사용 가능 여부를 읽으려면 요청에 다음을 전달하세요.

  • chat.users.availability.readonly 또는 chat.users.availability 승인 범위를 지정합니다.
  • 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()

자바

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 승인 범위를 지정합니다.
  • UpdateAvailability 메서드를 호출합니다.
  • 새 customStatus 세부정보를 지정하여 Availability 리소스를 전달합니다.
  • 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()

자바

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)을 제공할 수 있습니다.
  • 자리 비움: MarkAsAway 메서드를 호출하여 상태를 자리 비움으로 설정합니다.
  • 방해 금지 모드: MarkAsDoNotDisturb 메서드를 호출하여 알림을 사용 중지합니다.

필드 설명 및 쿼리 템플릿을 비롯한 자세한 내용은 각 메서드의 참조 가이드를 참고하세요.

이벤트에서 사용 가능 여부 변경사항 식별

Chat 앱은 사용자의 사용 가능 여부가 변경될 때 알림을 받기 위해 google.workspace.chat.availability.v1.updated 이벤트를 구독할 수 있습니다. 사용 가능 여부가 업데이트되면 앱은 Availability 리소스가 포함된 페이로드가 있는 이벤트를 수신합니다.