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

توضّح هذه الصفحة كيفية إدارة "مجموعات 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."
}

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

تعديل مجموعة

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

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

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

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

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

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

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

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

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

{
    "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 هو عنوان البريد الإلكتروني للمجموعة أو أي من عناوين البريد الإلكتروني البديلة للمجموعة أو 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"
}

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

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

لاسترداد مجموعة، استخدِم طلب GET التالي وأضِف التفويض الموضّح في طلبات التفويض. 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

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

{
    "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. لسهولة القراءة، يستخدم هذا المثال أحرف الرجوع إلى أول السطر: 

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

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

{
"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"
     }
  ],
   "nextPageToken": "NNNNN"
}

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

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

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

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

حذف اسم مستعار للمجموعة

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

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

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

حذف مجموعة

لحذف مجموعة، استخدِم طلب 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

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

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

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