จัดการความพร้อมของผู้ใช้สำหรับแอปใน Chat

คู่มือนี้อธิบายวิธีใช้ Google Chat API เพื่อจัดการสถานะความพร้อมใช้งานและสถานะที่กำหนดเองของผู้ใช้

หากต้องการอ่านและอัปเดตความพร้อมใช้งานของผู้ใช้ Chat แอปของคุณต้องตรวจสอบสิทธิ์ ด้วย การตรวจสอบสิทธิ์ของผู้ใช้ โดยจะเข้าถึงหรือแก้ไขได้เฉพาะความพร้อมใช้งานของผู้ใช้ที่ผ่านการตรวจสอบสิทธิ์แล้วเท่านั้น

ข้อกำหนดเบื้องต้น

Node.js

  • บัญชี Google Workspace สำหรับธุรกิจหรือ Enterprise ที่มีสิทธิ์เข้าถึง Google Chat

Python

  • บัญชี Google Workspace สำหรับธุรกิจหรือ Enterprise ที่มีสิทธิ์เข้าถึง Google Chat

Java

  • บัญชี Google Workspace สำหรับธุรกิจหรือ Enterprise ที่มีสิทธิ์เข้าถึง Google Chat

Apps Script

  • บัญชี Google Workspace สำหรับธุรกิจหรือ Enterprise ที่มีสิทธิ์เข้าถึง Google Chat

รับความพร้อมใช้งานของผู้ใช้

หากต้องการอ่านความพร้อมใช้งานของผู้ใช้ 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()

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
  • เรียกใช้เมธอด 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)
  • ไม่อยู่: เรียกใช้ MarkAsAway เมธอดเพื่อตั้งสถานะการแสดงตัวเป็น "ไม่อยู่"
  • ห้ามรบกวน: เรียกใช้ MarkAsDoNotDisturb เมธอดเพื่อปิดเสียงการแจ้งเตือน

โปรดดูรายละเอียด รวมถึงคำอธิบายช่องและเทมเพลตการค้นหาในคู่มืออ้างอิงของแต่ละเมธอด

ระบุการเปลี่ยนแปลงความพร้อมใช้งานจากเหตุการณ์

แอป Chat สามารถสมัครรับข้อมูลเหตุการณ์ google.workspace.chat.availability.v1.updated เพื่อรับการแจ้งเตือนเมื่อความพร้อมใช้งานของผู้ใช้มีการเปลี่ยนแปลง เมื่อมีการอัปเดตความพร้อมใช้งาน แอปจะได้รับเหตุการณ์ที่มีเพย์โหลดซึ่งมีทรัพยากร Availability