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

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

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

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

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

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

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

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

Python

  • يجب أن يكون لديك امتيازات المشرف لإدارة المحادثات في Chat وفي "المساحات" لمؤسستك على Google Workspace.

الاتصال بواجهة برمجة التطبيقات Google Chat API بصفتك مشرفًا

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

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

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

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

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

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

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

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

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(
    'client_secrets.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(
      'client_secrets.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