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

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

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

إنشاء مجموعة

لإنشاء مجموعة، استخدِم طلب 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 وقيمة المجموعة اسم مجموعة مبيعات آسيا والمحيط الهادئ: 

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

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

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

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

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

لحذف اسم مستعار لمجموعة، يمكنك استخدام طلب DELETE التالي وتضمين التفويض الموضّح في تفويض الطلبات يمكن أن يكون groupKey هو عنوان البريد الإلكتروني الرئيسي للمجموعة، وهو عنوان id أو أي من الأسماء المستعارة للمجموعة رسائل البريد الإلكتروني. aliasId هو الاسم المستعار الذي يتم حذف. لمعرفة خصائص الطلب والاستجابة، اطّلِع على مرجع 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.

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

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