البحث عن مساحات Google Chat وإدارتها لمؤسستك في Google Workspace

يوضّح هذا الدليل كيف يمكن لمشرف Google Workspace استخدام طريقة search() على Space في Google Chat API لإدارة المساحات المسماة في مؤسسته وتنفيذ مهام إدارية.

بصفتك مشرفًا في Google Workspace، يمكنك استخدام Chat API فقط لإدارة المساحات المسماة، والتي يتم تعريفها على أنّها SpaceType من SPACE. المساحات المسماة هي مساحات دائمة يرسل فيها المستخدمون الرسائل ويشاركون الملفات ويتعاونون. لا يمكنك استخدام Chat API لإدارة الرسائل المباشرة أو المحادثات الجماعية.

يمثّل Space المورد مكانًا يمكن فيه للمستخدمين وتطبيقات Chat إرسال الرسائل ومشاركة الملفات والتعاون. تتوفّر عدة أنواع من المساحات:

  • الرسائل المباشرة هي محادثات بين مستخدمَين أو بين مستخدم وتطبيق Chat.
  • المحادثات الجماعية هي محادثات بين ثلاثة مستخدمين أو أكثر وتطبيقات Chat.
  • المساحات المسماة هي مساحات دائمة يرسل فيها المستخدمون الرسائل ويشاركون الملفات ويتعاونون.

بصفتك مشرفًا في Google Workspace، يمكنك استخدام Chat API للبحث عن مساحات مسمّاة وإدارتها في مؤسستك بالطرق التالية:

  • تدقيق المساحات في المؤسسة: باستخدام طريقة search()، يمكنك استرداد قائمة بجميع المساحات في مؤسسة مع معلومات تفصيلية حول إعدادات كل مساحة وبياناتها الوصفية، مثل تاريخ الإنشاء وتاريخ آخر نشاط وعدد الأعضاء وحالة إعداد السجلّ والقدرة على دعوة ضيوف خارجيين.
  • البحث عن المساحات غير النشطة وحذفها باستخدام طريقة search()، يمكنك العثور على المساحات التي لم يتم استخدامها منذ تاريخ ووقت محدّدين ثم حذفها. لمزيد من التفاصيل ونموذج الرمز، يُرجى الاطّلاع على العثور على مساحات غير نشطة وحذفها.
  • تصدير قائمة بالمساحات استنادًا إلى معايير البحث باستخدام طريقة search()، يمكنك استرداد قائمة بالمساحات التي تستوفي المعايير المحدّدة في query وتصدير النتائج إلى ملف CSV لتحليلها.
  • البحث عن مدراء المساحات والتواصل معهم باستخدام طريقة search()، يمكنك استرداد قائمة بجميع المساحات في مؤسسة، ثم استخدام طريقة members.list() لاسترداد قائمة بجميع أعضاء المساحة الذين لديهم دور "مدير".
  • البحث عن مساحات بدون مدراء محدّدين باستخدام طريقة search()، يمكنك استرداد قائمة بجميع المساحات في مؤسسة، ثم استخدام طريقة members.list() لاسترداد قائمة بالمساحات التي لا تضم أي مديرين.

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

Python

إجراء مكالمة باستخدام Google Chat API بصفتك مشرفًا

لإثبات هويتك كمستخدم لديه امتيازات المشرف، يجب تضمين ما يلي في طلبك:

  • حدِّد نطاق تفويض يتيح استخدام مصادقة المستخدم مع امتيازات المشرف.
  • اضبط الحقل useAdminAccess على true.

يعرض هذا القسم الأمثلة التالية على طلب بيانات من Chat API بصفتك مشرفًا:

البحث عن مساحات في مؤسستك

يوضّح هذا المثال كيف يمكن لمشرفي Google Workspace استخدام طريقة search() في مورد Space لواجهة برمجة التطبيقات Chat API للبحث عن مساحات في مؤسسة استنادًا إلى معايير محدّدة.

لاستدعاء طريقة search() مع مصادقة المستخدم و امتيازات المشرف، يجب تحديد ما يلي في الطلب:

  • حدِّد نطاق إذن chat.admin.spaces أو chat.admin.spaces.readonly.
  • حدِّد useAdminAccess=true.
  • حدِّد مَعلمات البحث query لتصفية النتائج:
    • customer = "customers/my_customer" - مطلوبة والقيمة الوحيدة المسموح بها هي customers/my_customer
    • spaceType = "SPACE": مطلوب، والقيمة الوحيدة المسموح بها هي SPACE
    • اختياريًا، يمكنك إدخال طلب بحث إضافي واحد أو أكثر لفلترة البحث في مساحتك بشكل أكبر، مثل الكلمات الرئيسية في الأسماء المعروضة (displayName) أو تاريخ الإنشاء (createTime) أو استنادًا إلى نشاط المساحة (lastActiveTime).

يوضّح الرمز التالي مثالاً على كيفية استخدام امتيازات المشرف للبحث عن مساحات يتضمّن اسمها المعروض الكلمتَين "Hello" و "World" بأي ترتيب:

Python

  1. في دليل العمل، أنشئ ملفًا باسم search_spaces_for_hello_world.py.

  2. أدرِج الرمز التالي في search_spaces_for_hello_world.py:

    from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = [
  'https://www.googleapis.com/auth/chat.admin.spaces.readonly',
]

def main():
# Authenticate with Google Workspace
# and get user authorization.
flow = InstalledAppFlow.from_client_secrets_file(
    'credentials.json',
    SCOPES,
)
creds = flow.run_local_server()

# Build a service endpoint for Chat API.
chat = build('chat', 'v1', credentials=creds)

spaces = []
page_token = ''

# Search for all spaces.
while True:
  result = (
      chat.spaces()
      .search(
          useAdminAccess=True,
          query=(
            'customer = "customers/my_customer"'
            'AND spaceType = "SPACE"'
            'AND displayName:"Hello World"'
            )
pageToken=page_token,
      )
      .execute()
  )
  if 'spaces' not in result:
    print('No spaces found named Hello World.')
    return
  spaces.extend(result['spaces'])
  if 'nextPageToken' in result:
    page_token = result['nextPageToken']
  else:
    break

print(str(len(spaces)) + ' spaces found:')
# Prints the list of spaces.
print(spaces)

  3. في دليل العمل، أنشئ النموذج وشغِّله:

    python3 search_spaces_for_hello_world.py

العثور على المساحات غير النشطة وحذفها

يوضّح هذا المثال كيف يمكن لمشرفي Google Workspace استخدام طريقة search() في مورد Space ضِمن Chat API للعثور على المساحات غير النشطة ثم حذفها باستخدام طريقة delete() مع المَعلمة useAdminAccess.

يمكن أن تشغل مساحات Google Chat غير النشطة، أي تلك التي لم يعُد يتم استخدامها بشكل متكرر، مساحة تخزين قيّمة وتتسبّب في حدوث فوضى في واجهة المستخدم. باستخدام طريقة search()، يمكن للمشرفين العثور على المساحات التي لم يتم استخدامها منذ تاريخ ووقت محدّدَين، مثل شهرَين مضيَين. بعد إعداد قائمة بالمساحات، يمكن للمشرفين اتّخاذ إجراءات بشأنها، مثل تعديلها أو حذفها.

للبحث عن قائمة بالمساحات غير النشطة ثم حذفها باستخدام مصادقة المستخدم وامتيازات المشرف، مرِّر ما يلي في طلباتك:

  • للبحث عن المساحات غير النشطة، حدِّد ما يلي:
    • حدِّد نطاق إذن chat.admin.spaces أو chat.admin.spaces.readonly.
    • استدعِ الدالة search() على المورد Spaces.
    • اضبط INACTIVE_SPACE_DEADLINE على تاريخ ووقت آخر نشاط يحدّد المساحات التي سيتم عرضها.
    • حدِّد useAdminAccess=true.
    • حدِّد مَعلمات البحث query لتصفية النتائج:
      • customer = "customers/my_customer": سمة مطلوبة والقيمة الوحيدة المسموح بها هي customers/my_customer
      • spaceType = "SPACE": مطلوب، والقيمة الوحيدة المسموح بها هي SPACE
      • lastActiveTime: لفلترة طلبك وعرض المساحات غير النشطة فقط، حدِّد lastActiveTime
  • لحذف المساحات غير النشطة من نتائج البحث، حدِّد ما يلي:
    • حدِّد chat.admin.delete نطاق التفويض.
    • استدعِ الدالة delete() على المورد Spaces.
    • حدِّد useAdminAccess=true.

يوضّح الرمز التالي مثالاً على كيفية البحث عن مساحات غير نشطة وحذفها باستخدام امتيازات المشرف:

Python

  1. في دليل العمل، أنشئ ملفًا باسم find_and_delete_inactive_spaces.py.

  2. أدرِج الرمز التالي في find_and_delete_inactive_spaces.py:

    
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = [
    'https://www.googleapis.com/auth/chat.admin.spaces.readonly',
    'https://www.googleapis.com/auth/chat.admin.delete',
]

# Any spaces that have not been active since this time will be deleted.
INACTIVE_SPACE_DEADLINE = '"INACTIVE_DATE"'

def main():
  # Authenticate with Google Workspace
  # and get user authorization.
  flow = InstalledAppFlow.from_client_secrets_file(
      'credentials.json',
      SCOPES,
  )
  creds = flow.run_local_server()

  # Build a service endpoint for Chat API.
  chat = build('chat', 'v1', credentials=creds)

  spaces = []
  page_token = ''

  # Search for all inactive spaces.
  while True:
    result = (
        chat.spaces()
        .search(
            useAdminAccess=True,
            query=(
                'customer = "customers/my_customer" AND spaceType = "SPACE" AND'
                ' lastActiveTime < '
            )
            + INACTIVE_SPACE_DEADLINE,
            pageToken=page_token,
        )
        .execute()
    )
    if 'spaces' not in result:
      print('No inactive spaces found.')
      return
    spaces.extend(result['spaces'])
    if 'nextPageToken' in result:
      page_token = result['nextPageToken']
    else:
      break

  print(str(len(spaces)) + ' inactive spaces found:')
  # Prints the list of inactive spaces.
  print(spaces)

  # Delete all inactive spaces.
  for space in spaces:
    (
        chat.spaces()
        .delete(
            useAdminAccess=True,
            name=space['name'],
        )
        .execute()
    )
    print(
        'Deleted space: '
        + space['displayName']
        + ', Resource Name: '
        + space['name']
    )

if __name__ == '__main__':
  main()

  3. في الرمز، استبدِل INACTIVE_DATE بتاريخ ووقت بالتنسيق YYYY-MM-DDTHH:MM:SS+HH:MM، مثلاً "2024-06-01T00:00:00+00:00".

  4. في دليل العمل، أنشئ النموذج وشغِّله:

    python3 find_and_delete_inactive_spaces.py