مدیریت دسترسی کاربران برای برنامه‌های چت

این راهنما نحوه استفاده از API چت گوگل را برای مدیریت وضعیت در دسترس بودن کاربر و وضعیت سفارشی توضیح می‌دهد.

برای خواندن و به‌روزرسانی در دسترس بودن یک کاربر چت، برنامه شما باید با احراز هویت کاربر، احراز هویت شود. فقط در دسترس بودن کاربر احراز هویت شده قابل دسترسی یا تغییر است.

پیش‌نیازها

نود جی اس

پایتون

جاوا

اسکریپت برنامه‌ها

دریافت در دسترس بودن کاربر

برای خواندن در دسترس بودن یک کاربر Google Chat، موارد زیر را در درخواست خود وارد کنید:

  • دامنه مجوز chat.users.availability.readonly یا chat.users.availability را مشخص کنید.
  • متد GetAvailability را فراخوانی کنید.
  • name منبع availability را برای بازیابی ارسال کنید. نام باید به صورت users/{user}/availability قالب‌بندی شود. آدرس ایمیل کاربر یا نام مستعار me می‌تواند برای ارجاع به فراخوانی‌کننده استفاده شود. به عنوان مثال، users/me/availability .

نحوه دریافت وضعیت دسترسی کاربر به شرح زیر است:

نود جی اس 

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

پایتون 

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

اسکریپت برنامه‌ها 

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

API چت نمونه‌ای از Availability را برمی‌گرداند که جزئیات وضعیت حضور کاربر و وضعیت سفارشی او را نشان می‌دهد.

به‌روزرسانی وضعیت سفارشی

برای به‌روزرسانی وضعیت سفارشی کاربر، موارد زیر را در درخواست خود ارسال کنید:

  • دامنه مجوز chat.users.availability را مشخص کنید.
  • متد UpdateAvailability را فراخوانی کنید.
  • منبع Availability را ارسال کنید و جزئیات customStatus جدید را مشخص کنید.
  • پارامتر update_mask را طوری تنظیم کنید که فیلد custom_status را نیز شامل شود.

در اینجا نحوه به‌روزرسانی وضعیت سفارشی کاربر آمده است:

نود جی اس 

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

پایتون 

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

اسکریپت برنامه‌ها 

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

API چت به‌روزرسانی می‌شود و نمونه‌ای از Availability را با وضعیت سفارشی جدید برمی‌گرداند.

برای پاک کردن وضعیت سفارشی کاربر، در دسترس بودن را به‌روزرسانی کنید و جزئیات customStatus حذف کنید.

به‌روزرسانی وضعیت حضور

بسته به وضعیت حضور هدف، می‌توانید با فراخوانی یکی از روش‌های سفارشی زیر، وضعیت دسترسی کاربر را به‌روزرسانی کنید:

  • فعال : متد MarkAsActive را برای تنظیم حضور به فعال فراخوانی کنید. مقادیر انقضای اختیاری ( ttl یا expireTime ) می‌توانند ارائه شوند.
  • دور از دسترس : متد MarkAsAway را برای تنظیم حضور به حالت دور از دسترس فراخوانی کنید.
  • مزاحم نشوید : برای بی‌صدا کردن اعلان‌ها، متد MarkAsDoNotDisturb را فراخوانی کنید.

برای جزئیات، از جمله توضیحات فیلدها و الگوهای پرس‌وجو، به راهنمای مرجع هر روش مراجعه کنید.

شناسایی تغییرات در دسترس بودن از یک رویداد

برنامه چت شما می‌تواند در رویدادهای google.workspace.chat.availability.v1.updated مشترک شود تا هنگام تغییر در دسترس بودن کاربر، اعلان دریافت کند. هنگامی که یک به‌روزرسانی در دسترس بودن اتفاق می‌افتد، برنامه رویدادی را با یک payload حاوی منبع Availability دریافت می‌کند.