تتناول هذه الصفحة كيفية إدارة "مجموعات 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
هو عنوان البريد الإلكتروني للمجموعة أو أي عنوان من عناوين البريد الإلكتروني للاسم المستعار للمجموعة أو 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
التالي وأدرِج التفويض الموضّح في طلبات التفويض.
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
.
عند حذف مجموعة، يحدث ما يلي:
- يتم حذف جميع أعضاء المجموعة. لا يتم حذف حسابات المستخدمين الخاصة بالعضو.
- يتم حذف أرشيف المجموعة.
- لا يتم تسليم الرسائل المُرسَلة إلى عنوان المجموعة المحذوفة. وبدلاً من ذلك، يتلقى المرسِل رسالة مرتدة.