إدارة مدى توفّر تطبيقات Chat للمستخدمين

يوضّح هذا الدليل كيفية استخدام Google Chat API لإدارة حالة توفّر المستخدم وحالته المخصّصة.

لقراءة حالة توفّر مستخدم في Chat وتعديلها، يجب أن يصادق تطبيقك على مصادقة المستخدم. لا يمكن الوصول إلى معلومات مدى توفّر المستخدم الذي تمّت مصادقته أو تعديلها.

المتطلبات الأساسية

Node.js

Python

جافا

برمجة التطبيقات

الحصول على معلومات حول مدى توفّر مستخدم

لقراءة حالة توفّر مستخدم 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);
    }
  }
}

برمجة التطبيقات

/**
 * 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()

جافا

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

يعدّل Chat API مثيلاً من Availability ويعرضه مع الحالة المخصّصة الجديدة.

لمحو حالة مخصّصة لمستخدم، عدِّل مدى التوفّر واحذف تفاصيل customStatus.

تعديل حالة التوفّر

استنادًا إلى حالة الحضور المستهدَفة، يمكنك تعديل حالة توفّر المستخدم من خلال استدعاء إحدى الطرق المخصّصة التالية:

  • نشط: استدعِ الدالة MarkAsActive لضبط حالة التواجد على "نشط". يمكن تقديم قيم انتهاء الصلاحية الاختيارية (ttl أو expireTime).
  • بعيد عن الجهاز: استخدِم طريقة MarkAsAway لضبط حالة الحضور على "بعيد عن الجهاز".
  • عدم الإزعاج: استخدِم طريقة MarkAsDoNotDisturb لكتم صوت الإشعارات.

للحصول على التفاصيل، بما في ذلك أوصاف الحقول ونماذج طلبات البحث، يمكنك الاطّلاع على دليل المرجع الخاص بكل طريقة.

تحديد تغييرات مدى التوفّر من حدث

يمكن لتطبيق Chat الاشتراك في google.workspace.chat.availability.v1.updatedالأحداث لتلقّي إشعارات عند تغيُّر حالة توفّر المستخدم. عندما يتم تعديل حالة التوفّر، يتلقّى التطبيق حدثًا يتضمّن حمولة تحتوي على المورد Availability.