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

إنشاء مجموعة

لإنشاء مجموعة، استخدِم طلب 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 هو عنوان البريد الإلكتروني للمجموعة أو أي عنوان من عناوين البريد الإلكتروني للاسم المستعار للمجموعة أو id الفريد للمجموعة. للاطّلاع على سلاسل طلبات البحث وسمات الطلب والاستجابة، يمكنك الاطّلاع على طريقة groups.update.

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

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

في المثال التالي، قيمة groupKey الفريدة هي nnn واسم المجموعة هو APAC Sales Group:

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

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: تعرض واجهة برمجة التطبيقات للدليل جميع مجموعات السمة domain.
• في حال عدم استخدام الوسيطات domain وcustomer: تعرض واجهة برمجة التطبيقات للدليل جميع المجموعات للحساب المرتبط بـ my_customer. هذا هو الحساب customerId الخاص بالمشرف الذي أرسل الطلب.
• عند استخدام كلٍ من الوسيطتين customer وuserKey: تعرض واجهة برمجة التطبيقات الدليل رسالة خطأ. يجب تقديم طلبَين منفصلَين باستخدام هذه الوسيطات.

في المثال التالي، يستخدم مشرف الحساب 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: تعرض واجهة برمجة التطبيقات الدليل رسالة خطأ. يجب تقديم طلبَين منفصلَين باستخدام هذه الوسيطات.

للاطّلاع على سمات الطلب والاستجابة، يمكنك الاطّلاع على طريقة 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 https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

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

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

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 https://admin.googleapis.com/admin/directory/v1/group/nnnn

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

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

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