Chat uygulamaları için kullanıcı kullanılabilirliğini yönetme

Bu kılavuzda, kullanıcının uygunluk durumunu ve özel durumunu yönetmek için Google Chat API'sinin nasıl kullanılacağı açıklanmaktadır.

Bir Chat kullanıcısının müsaitlik durumunu okumak ve güncellemek için uygulamanızın kullanıcı kimlik doğrulaması ile kimliğini doğrulaması gerekir. Yalnızca kimliği doğrulanmış kullanıcının uygunluk durumuna erişilebilir veya bu durum değiştirilebilir.

Ön koşullar

Node.js

Python

Java

Apps Komut Dosyası

Kullanıcının müsaitlik durumunu alma

Bir Google Chat kullanıcısının müsaitlik durumunu okumak için isteğinizde aşağıdakileri iletin:

  • chat.users.availability.readonly veya chat.users.availability yetkilendirme kapsamını belirtin.
  • GetAvailability yöntemini çağırın.
  • Alınacak müsaitlik durumu kaynağının name değerini iletin. Ad, users/{user}/availability biçiminde olmalıdır. Arayandan bahsederken kullanıcının e-posta adresi veya me takma adı kullanılabilir. Örneğin, users/me/availability.

Kullanıcının uygunluk durumunu öğrenmek için:

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 Komut Dosyası

/**
 * 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, kullanıcının varlık durumunu ve özel durumunu ayrıntılı olarak açıklayan bir Availability örneği döndürür.

Özel durumu güncelleme

Bir kullanıcının özel durumunu güncellemek için isteğinizde aşağıdakileri iletin:

  • chat.users.availability yetkilendirme kapsamını belirtin.
  • UpdateAvailability yöntemini çağırın.
  • Yeni customStatus ayrıntılarını belirterek Availability kaynağını iletin.
  • update_mask parametresini custom_status alanını içerecek şekilde ayarlayın.

Kullanıcının özel durumunu güncellemek için:

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 Komut Dosyası

/**
 * 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 örneğini yeni özel durumla günceller ve döndürür.

Bir kullanıcının özel durumunu temizlemek için müsaitlik durumunu güncelleyin ve customStatus ayrıntılarını atlayın.

Görünürlük durumunu güncelleme

Hedef varlık durumuna bağlı olarak, aşağıdaki özel yöntemlerden birini çağırarak kullanıcının uygunluk durumunu güncelleyebilirsiniz:

  • Etkin: Mevcudiyeti etkin olarak ayarlamak için MarkAsActive yöntemini çağırın. İsteğe bağlı son kullanma tarihi değerleri (ttl veya expireTime) sağlanabilir.
  • Uzakta: Durumu uzakta olarak ayarlamak için MarkAsAway yöntemini çağırın.
  • Rahatsız etmeyin: Bildirimleri sessize almak için MarkAsDoNotDisturb yöntemini çağırın.

Alan açıklamaları ve sorgu şablonları dahil olmak üzere ayrıntılar için her yöntemin referans kılavuzunu inceleyin.

Bir etkinlikteki müsaitlik durumunda yapılan değişiklikleri belirleme

Chat uygulamanız, kullanıcının müsaitlik durumu değiştiğinde bildirim almak için google.workspace.chat.availability.v1.updated etkinliklerine abone olabilir. Kullanılabilirlik güncellemesi yapıldığında uygulama, Availability kaynağını içeren bir yükle birlikte etkinlik alır.