البحث عن مساحات 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