إدارة المجموعات

تتناول هذه الصفحة كيفية إدارة "مجموعات Google" باستخدام واجهة برمجة التطبيقات Directory API:

  • إنشاء مجموعة
  • تعديل مجموعة
  • إضافة اسم بديل للمجموعة
  • استرداد مجموعة
  • استرداد جميع المجموعات لنطاق أو حساب
  • استرداد جميع المجموعات التي يشترك فيها العضو
  • استرداد جميع الأسماء البديلة للمجموعات
  • حذف اسم بديل لمجموعة
  • حذف مجموعة

إنشاء مجموعة

لإنشاء مجموعة، استخدِم طلب POST التالي وأضِف التفويض الموضّح في طلبات التفويض. يمكنك إنشاء مجموعة لأي نطاق مرتبط بالحساب. للاطّلاع على سمات سلاسل طلبات البحث وطلبات البيانات والاستجابة، اطّلِع على طريقة groups.insert. 

POST https://admin.googleapis.com/admin/directory/v1/groups

يعرض طلب JSON التالي نموذجًا لنص الطلب الذي ينشئ مجموعة. عنوان البريد الإلكتروني للمجموعة هو sales_group@example.com: 

{
   "email": "sales_group@example.com",
   "name": "Sales Group",
   "description": "This is the Sales group."
}

تعرِض الاستجابة الناجحة رمز حالة HTTP‏ 201 وسمات المجموعة الجديدة.

تعديل مجموعة

لتعديل إعدادات مجموعة، استخدِم طلب PUT التالي وأضِف التفويض الموضّح في طلبات التفويض. groupKey هو عنوان البريد الإلكتروني للمجموعة أو أي من عناوين البريد الإلكتروني للاسم المستعار للمجموعة، أو groupKey الفريد للمجموعة.id للاطّلاع على سمات سلاسل طلبات البحث وطلبات البيانات والاستجابة، اطّلِع على طريقة groups.update. 

PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey

بوجهٍ عام، تنصح Google بعدم استخدام عنوان البريد الإلكتروني للمجموعة كمفتاح للبيانات الثابتة، لأنّ عنوان البريد الإلكتروني يخضع للتغيير.

في المثال التالي، القيمة الفريدة لـ groupKey هي nnn واسم المجموعة هو مجموعة المبيعات في منطقة آسيا والمحيط الهادئ: 

PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn

{
    "email": "sales_group@example.com",
    "name": "APAC Sales Group"
}

لطلب تعديل، ما عليك سوى إرسال المعلومات المعدَّلة في طلبك. ليس عليك إدخال جميع خصائص المجموعة في الطلب.

يعرض الردّ الناجح رمز حالة HTTP‏ 201 وسمات المجموعة الجديدة: 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "liz@test.com"
     }
    ]
}

إضافة اسم بديل للمجموعة

لإضافة عنوان بديل للمجموعة، استخدِم طلب POST التالي وأضِف التفويض الموضّح في طلبات التفويض. groupKey هو عنوان البريد الإلكتروني للمجموعة أو أي من عناوين البريد الإلكتروني للأسماء البديلة للمجموعة أو groupKey الفريد للمجموعة.id للاطّلاع على سمات سلاسل طلبات البحث وطلبات البيانات والاستجابة، يُرجى مراجعة مرجع groups. 

POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

بوجهٍ عام، تنصح Google بعدم استخدام عنوان البريد الإلكتروني للمجموعة كمفتاح للبيانات الثابتة، لأنّ عنوان البريد الإلكتروني يخضع للتغيير.

يعرض طلب JSON التالي نموذج طلب لإنشاء عنوان بديل للمجموعة. groupKey هو id الفريد للمجموعة ويُشار إليه بالرمز NNNN.

POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases

{
    "alias": "best_sales_group@example.com"
}

تعرض الاستجابة الناجحة رمز حالة HTTP‏ 201 وسمات الاسم المعرِّف الجديد للمجموعة.

استرداد مجموعة

لاسترداد مجموعة، استخدِم طلب GET التالي وأضِف التفويض описан في طلبات التفويض. groupKey هو عنوان البريد الإلكتروني للمجموعة أو أي من عناوين البريد الإلكتروني للأسماء البديلة للمجموعة أو groupKey الفريد للمجموعة.id للاطّلاع على سمات سلاسل طلبات البحث وطلبات البيانات والاستجابة، اطّلِع على طريقة groups.get. 
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey

بوجهٍ عام، تنصح Google بعدم استخدام عنوان البريد الإلكتروني للمجموعة كمفتاح للبيانات الثابتة، لأنّ عنوان البريد الإلكتروني يخضع للتغيير.

في المثال التالي، المعرّف الفريد groupKey هو nnnn: 

GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn

يعرض الردّ الناجح رمز حالة HTTP‏ 200 وإعدادات المجموعة: 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "liz@test.com"
     }
    ]
}

استرداد جميع المجموعات لنطاق أو حساب

لاسترداد جميع المجموعات لنطاق أو حساب معيّن، استخدِم طلب GET التالي وأضِف التفويض الموضّح في طلبات التفويض. للاطّلاع على سمات سلاسل طلبات البحث وطلبات البيانات والاستجابة، اطّلِع على groups.list method. بغرض سهولة القراءة، يستخدم هذا المثال أحرف الرجوع إلى أول السطر: 

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name
&customer=my_customer or customerId&pageToken=pagination token
&maxResults=max results

عند استرداد جميع المجموعات لنطاق أو حساب، ضَع في اعتبارك ما يلي:

  • جميع المجموعات لنطاق فرعي: استخدِم الوسيطة domain مع اسم النطاق.
  • جميع المجموعات للحساب: استخدِم الوسيطة customer مع إما my_customer أو قيمة customerId للحساب. بصفتك مشرف حساب، استخدِم السلسلة my_customer لتمثيل customerId حسابك. إذا كنت مورِّدًا يصل إلى حساب عميل تم إعادة بيعه، استخدِم customerId الحساب الذي تم إعادة بيعه. بالنسبة إلى القيمة customerId، استخدِم اسم النطاق الأساسي للحساب في طلب عملية استرداد جميع المستخدمين في نطاق. تحتوي الاستجابة الناتجة على القيمة customerId.
  • باستخدام كلٍّ من الوسيطات domain وcustomer: تعرض Directory API جميع المجموعات للمستخدم domain.
  • عدم استخدام الوسيطات domain وcustomer: تعرض Directory API جميع المجموعات للحساب المرتبط my_customer. هذا هو الحساب customerId للمشرف الذي يقدّم الطلب.
  • استخدام كلّ من وسيطَي customer وuserKey: تعرض Directory API خطأً. يجب تقديم طلبَين منفصلَين باستخدام هذين الوسيطَين.

في المثال التالي، يستخدم مشرف الحساب my_customer لطلب قائمة بكل مجموعات الحساب:

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=my_customer&maxResults=2

في المثال التالي، يعرض طلب مشرف المورّد جميع المجموعات للحساب الذي تمّ إعادة بيعه باستخدام customerId C03az79cb. الحدّ الأقصى للنتائج التي يتم عرضها في كل صفحة استجابة هو 2. هناك nextPageToken لقائمة المستخدمين التي تمّت متابعتها في هذا الردّ: 

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2

يعرض الاستجابة الناجحة رمز حالة HTTP‏ 200 والمجموعات بالترتيب الأبجدي لعنوان البريد الإلكتروني للمجموعة: 

{
"kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support@sales.com",
      "name": "Sales support",
      "directMembersCount": "6",
      "description": "The sales support group",
      "adminCreated": true
     },
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "travel@sales.com",
      "name": "Sales travel",
      "directMembersCount": "2",
      "description": "The travel group supporting sales",
      "adminCreated": false,
      "aliases": [
       {
         "alias": "best_sales_group@example.com"
       }
      ],
      "nonEditableAliases: [
       {
         "alias": "liz@test.com"
       }
      ]
     },
  "nextPageToken": "NNNN"
  }

استرداد جميع المجموعات التي يشترك فيها العضو

لاسترداد جميع المجموعات التي اشترك فيها أحد الأعضاء، استخدِم طلب GET التالي وأضِف التفويض الموضّح في طلبات التفويض. بغرض سهولة القراءة، يستخدم هذا المثال أحرف الرجوع إلى أول السطر: 

GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=user key
?pageToken=pagination token
&maxResults=maximum results per response page
  • يمكن أن يكون العضو مستخدمًا أو مجموعة.
  • يمكن أن يكون userKey هو عنوان البريد الإلكتروني الرئيسي للمستخدم أو عنوان البريد الإلكتروني البديل للمستخدم، أو عنوان البريد الإلكتروني الرئيسي للمجموعة أو عنوان البريد الإلكتروني البديل للمجموعة، أو id الفريد للمستخدم والذي يمكن العثور عليه باستخدام عملية استرداد مستخدم.
  • يجب أن ينتمي المستخدم أو المجموعة المحدّدان في userKey إلى نطاقك.
  • استخدِم سلسلة طلب البحث pageToken للردود التي تتضمّن عددًا كبيرًا من المجموعات. في حالة استخدام ميزة تقسيم الصفحات، يعرض الردّ السمة nextPageToken التي توفّر رمز علامة للصفحة التالية من نتائج الاستجابة. يستخدم طلبك التالي رمز المرور هذا كقيمة لسلاسل pageToken الاستعلام.
  • استخدام كلّ من وسيطَي customer وuserKey: تعرض Directory API خطأً. يجب تقديم طلبَين منفصلَين باستخدام هذين الوسيطَين.

للاطّلاع على سمات الطلب والاستجابة، اطّلِع على طريقة groups.list.

يعرض الردّ الناجح رمز حالة HTTP 200 وقائمة بمعلومات الأعضاء:

  • يتم عرض جميع المجموعات التي اشترك فيها أحد الأعضاء، بما في ذلك المجموعات من خارج نطاق المستخدم.
  • يتم عرض المجموعات بترتيب أبجدي حسب عنوان البريد الإلكتروني لكل مجموعة.
  • في نص الاستجابة، يمثّل id المعرّف الفريد للمجموعة.
  • في الاستجابة، لا تتضمّن بيانات المجموعة من خارج نطاق المستخدم الأسماء البديلة للمجموعة الخارجية. 
{
    "kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "sales_group@example.com",
      "name": "sale group",
      "directMembersCount": "5",
      "description": "Sales group"
     },
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support_group.com",
      "name": "support group",
      "directMembersCount": "5",
      "description": "Support group"
     }
  ],
   "nextPakeToken": "NNNNN"
}

استرداد جميع الأسماء البديلة للمجموعات

لاسترداد جميع الأسماء البديلة للمجموعة، استخدِم طلب GET التالي وأضِف التفويض الموضّح في طلبات التفويض. يمكن أن يكون groupKey هو عنوان البريد الإلكتروني الأساسي للمجموعة أو id الفريد للمجموعة أو أي من عناوين البريد الإلكتروني للأسماء البديلة للمجموعة. للاطّلاع على سمات الطلب والاستجابة، يُرجى مراجعة مرجع groups. 

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

تعرض الاستجابة الناجحة رمز حالة HTTP‏ 201 وقائمة بالأسماء البديلة للمجموعة.

حذف اسم بديل لمجموعة

لحذف الاسم المعرِّف لمجموعة، استخدِم طلب DELETE التالي وأضِف التفويض الموضّح في طلبات التفويض. يمكن أن يكون groupKey هو عنوان البريد الإلكتروني الأساسي للمجموعة أو عنوان البريد الإلكتروني الفريد id للمجموعة أو أي من عناوين البريد الإلكتروني للأسماء البديلة للمجموعة. يشير الرمز aliasId إلى الاسم المستعار الذي تتم jego Deletion. للاطّلاع على سمات الطلب والاستجابة، راجِع مرجع groups: 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases/aliasId

تعرِض الاستجابة الناجحة رمز حالة HTTP 201.

حذف مجموعة

لحذف مجموعة، استخدِم طلب DELETE التالي وأضِف التفويض описанًا في طلبات التفويض. groupKey هو id الفريد للمجموعة: 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
 على سبيل المثال، يحذف طلب DELETE هذا المجموعة التي تحتوي على المجموعة nnnn id: 
DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn

تعرِض الاستجابة الناجحة رمز حالة HTTP 200.

عند حذف مجموعة، يحدث ما يلي:

  • يتم حذف جميع أعضاء المجموعة. ولا يتم حذف حسابات المستخدمين للعضو.
  • يتم حذف أرشيف المجموعة.
  • ولا يتم تسليم الرسائل المُرسَلة إلى عنوان المجموعة المحذوفة. بدلاً من ذلك، يتلقّى المُرسِل رسالة مرتدة.