تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إدارة الأدوار

تتيح لك Directory API استخدام التحكّم في الوصول استنادًا إلى الدور (RBAC) لإدارة إمكانية الوصول إلى الميزات في نطاق Google Workspace. يمكنك إنشاء أدوار مخصّصة تتضمّن امتيازات للحدّ من وصول المشرف بشكل أكثر تحديدًا من الأدوار المُحدَّدة مسبقًا التي يتم توفيرها مع Google Workspace. يمكنك إسناد أدوار إلى المستخدمين أو مجموعات الأمان. يوضّح هذا الدليل كيفية تنفيذ بعض المهام الأساسية المرتبطة بالأدوار.

في ما يلي قائمة بالمصطلحات الشائعة التي تستخدمها Directory API في ما يتعلق بالتحكّم المستند إلى الأدوار (RBAC) في Google Workspace:

الامتياز: الإذن اللازم لتنفيذ مهمة أو عملية في نطاق Google Workspace يتم تمثيلها من خلال مورد Privilege. لا تتوفّر بيانات دائمة مرتبطة بهذا المرجع.
Role: مجموعة من الامتيازات التي تمنح الكيانات التي لديها هذا الدور القدرة على تنفيذ مهام أو عمليات معيّنة. يتم تمثيلها من خلال مورد Role.
إسناد الدور: سجلّ دور معيّن تم منحه للمستخدم أو المجموعة. يتم تمثيله من خلال المورد RoleAssignment.
مجموعة الأمان: أحد أنواع مجموعات Cloud Identity المستخدَمة للتحكّم في الوصول إلى موارد المؤسسة. يمكن أن تحتوي مجموعات الأمان على مستخدمين فرديين ومجموعات.

حدود الأدوار وإسناد الأدوار

يمكنك إنشاء عدد محدود فقط من الأدوار المخصّصة أو عمليات إسناد الأدوار، لذا إذا كنت على وشك بلوغ الحدّ الأقصى، عليك دمجها أو إزالتها لتجنُّب تجاوز الحدّ الأقصى. تنطبق الحدود التالية على الأدوار وتعيينات الأدوار:

يمكنك إنشاء ما يصل إلى 750 دورًا مخصصًا لمؤسستك بأكملها.
يمكنك إنشاء ما يصل إلى 1000 عملية إسناد أدوار لكل وحدة تنظيمية، مع العلم أنّ المؤسسة الجذرية تُعتبر وحدة. على سبيل المثال، يمكنك إسناد 600 دور في المؤسسة الرئيسية و700 دور ضمن وحدة تنظيمية أخرى حدّدتها، مثل قسم في شركة. تكون جميع أدوار المشرفين السابقة التحديد في Google Workspace مضبوطة تلقائيًا على نطاق المؤسسة. مزيد من المعلومات حول القيود المفروضة على الامتيازات التي يمكن منحها على مستوى الوحدة التنظيمية

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

يمكنك إسناد أي دور باستثناء دور المشرف المتميّز.
يمكنك إجراء ما يصل إلى 250 عملية إسناد الأدوار إلى المجموعات إجمالاً على مستوى الوحدة التنظيمية ككل وداخل كل وحدة تنظيمية.
يجب أن تكون المجموعة مجموعة أمان في مؤسستك.
ننصح بقصر عضوية المجموعة على المستخدمين في مؤسستك. يمكنك إضافة مستخدمين من خارج مؤسستك، ولكن قد لا يحصلون على امتيازات الدور. لمعرفة التفاصيل، يُرجى الاطّلاع على تقييد عضوية المجموعة. ### إسناد الأدوار إلى المجموعات

إذا كنت بحاجة إلى إسناد أكثر من 1000 دور في وحدة تنظيمية، يمكنك إضافة عدة أعضاء إلى مجموعة أمان وتحديد دور لها. تخضع عمليات تعيين أدوار المجموعة لبعض القيود الإضافية، لذا يُرجى الاطّلاع على مركز مساعدة المشرف للحصول على معلومات محدّدة.

ربط الأدوار بالامتيازات في "وحدة تحكّم المشرف في Google"

لتخصيص أدوار للمستخدمين الذين يصلون إلى امتيازاتهم من خلال "وحدة تحكّم المشرف"، قد تحتاج إلى منح امتيازات إضافية معيّنة. على سبيل المثال، لمنح مستخدم إذنًا بإنشاء مستخدمين آخرين من خلال "وحدة تحكّم المشرف"، يجب منحه الإذن المميّز USERS_CREATE بالإضافة إلى الإذنَين المميّزَين USERS_UPDATE وORGANIZATION_UNITS_RETRIEVE. يوضّح الجدول التالي وظائف "وحدة تحكّم المشرف" والأذونات المطلوبة لإدارة المستخدمين والوحدات التنظيمية.

وظائف "وحدة تحكّم المشرف"	الامتيازات المطلوبة
الوحدات التنظيمية - قراءة	`ORGANIZATION_UNITS_RETRIEVE`
الوحدات التنظيمية - إنشاء	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_CREATE`
تعديل الوحدات التنظيمية	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_UPDATE`
الوحدات التنظيمية - حذف	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_DELETE`
الوحدات التنظيمية	`ORGANIZATION_UNITS_ALL`
المستخدمون - قراءة	`USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
المستخدمون - إنشاء	‫`USERS_CREATE` + `USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
المستخدمون - تعديل	`USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
المستخدمون - نقل المستخدمين	‫`USERS_MOVE` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
المستخدمون - إعادة تسمية المستخدمين	‫`USERS_ALIAS` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
المستخدمون - إعادة ضبط كلمة المرور	‫`USERS_RESET_PASSWORD` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
المستخدمون - فرض تغيير كلمة المرور	‫`USERS_FORCE_PASSWORD_CHANGE` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
المستخدمون - إضافة/إزالة أسماء مستعارة	‫`USERS_ADD_NICKNAME` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
المستخدمون - تعليق حسابات المستخدمين	‫`USERS_SUSPEND` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
المجموعات	`GROUPS_ALL`
الأمان - إدارة أمان المستخدم	‫`USER_SECURITY_ALL` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`

أمثلة على حالات الاستخدام

قبل البدء

قبل تشغيل الأمثلة الواردة في هذا الدليل، عليك إعداد المصادقة والتفويض.

الحصول على قائمة بامتيازات النطاق

للحصول على قائمة مقسّمة إلى صفحات بالأذونات المتوافقة في نطاقك، استخدِم طريقة privileges.list().

إذا كنت مشرفًا بصدد الحصول على امتيازات في نطاقك الخاص، استخدِم my_customer كمعرّف العميل.
إذا كنت مورِّدًا تحصل على امتيازات لأحد عملائك، استخدِم رقم تعريف العميل الذي تعرضه عملية استرداد مستخدم.

طلب

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges

الردّ

تعرض الاستجابة الناجحة رمز الحالة HTTP 200. وإلى جانب رمز الحالة، تعرض الاستجابة الامتيازات المتاحة في النطاق:

{
  "kind": "admin\#directory\#privileges",
  "etag": ...,
  "items": [
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "02afmg282jiquyg",
      "privilegeName": "APP_ADMIN",
      "isOuScopable": false
    },
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "04f1mdlm0ki64aw",
      "privilegeName": "MANAGE_USER_SETTINGS",
      "isOuScopable": true,
      "childPrivileges": [
        {
          "kind": "admin\#directory\#privilege",
          "etag": ...,
          "serviceId": "04f1mdlm0ki64aw",
          "privilegeName": "MANAGE_APPLICATION_SETTINGS",
          "isOuScopable": true
        }
      ]
    },
    ...
  ]
}

الحصول على الأدوار الحالية

للحصول على قائمة بالأدوار الحالية، استخدِم طلب GET التالي وأضِف التفويض الموضّح في طلبات التفويض.

إذا كنت مشرفًا وتتلقّى أدوارًا في نطاقك الخاص، استخدِم my_customer كمعرّف العميل.
إذا كنت مورّدًا وتحصل على أدوار لأحد العملاء، استخدِم رقم تعريف العميل الذي حصلت عليه باستخدام عملية استرداد مستخدم.

طلب

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

الردّ

تعرض الاستجابة الناجحة رمز الحالة 200 في HTTP. بالإضافة إلى رمز الحالة، تعرض الاستجابة الأدوار المتوفّرة في النطاق:

{
  "kind": "admin\#directory\#roles",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/DywA6_jaJCYw-f0lFs2-g17UWe8\"",
  "items": [
    {
      "kind": "admin\#directory\#role",
      "etag": ... ,
      "roleId": "3894208461012993",
      "roleName": "_SEED_ADMIN_ROLE",
      "roleDescription": "Google Workspace Administrator Seed Role",
      "rolePrivileges": [
        {
          "privilegeName": "SUPER_ADMIN",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ROOT_APP_ADMIN",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_APIS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        ...
      ],
      "isSystemRole": true,
      "isSuperAdminRole": true
    },
    {
      "kind": "admin\#directory\#role",
      "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/bTXiZXfuK1NGr_f4paosCWXuHmw\"",
      "roleId": "3894208461012994",
      "roleName": "_GROUPS_ADMIN_ROLE",
      "roleDescription": "Groups Administrator",
      "rolePrivileges": [
        {
          "privilegeName": "CHANGE_USER_GROUP_MEMBERSHIP",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "USERS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "GROUPS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_DASHBOARD",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ORGANIZATION_UNITS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        }
      ],
      "isSystemRole": true
    },
    ...
  ]
}

إدراج جميع عمليات تعيين الأدوار

للحصول على قائمة مقسّمة إلى صفحات بجميع عمليات إسناد الأدوار المباشرة، استخدِم طريقة roleAssignments.list(). قد تعرض واجهة برمجة التطبيقات نتائج فارغة مع رمز مميّز للصفحة عند ضبط المَعلمة userKey. يجب مواصلة تقسيم النتائج إلى صفحات إلى أن لا يتم عرض رمز مميز للصفحة.

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

طلب

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

الردّ

تعرض الاستجابة الناجحة رمز الحالة 200 في HTTP. بالإضافة إلى رمز الحالة، تعرض الاستجابة جميع الأدوار المعيّنة في النطاق:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"user",
  "scopeType:"CUSTOMER",
}

عرض جميع عمليات إسناد الأدوار غير المباشرة

للحصول على قائمة مقسّمة إلى صفحات تتضمّن جميع عمليات إسناد الأدوار، بما في ذلك الأدوار التي تم إسنادها بشكل غير مباشر إلى مستخدم بسبب المجموعات التي ينتمي إليها، استخدِم طريقة roleAssignments.list().

قد تعرض واجهة برمجة التطبيقات نتائج فارغة مع رمز مميّز للصفحة. يجب مواصلة تقسيم النتائج إلى صفحات إلى أن لا يتم عرض رمز مميز للصفحة.

إذا كنت مشرفًا وتتلقّى مهام أدوار في نطاقك الخاص، استخدِم my_customer كمعرّف العميل.
إذا كنت مورِّدًا بائعًا بالتجزئة وتحصل على مهام أدوار لأحد عملائك، استخدِم رقم تعريف العميل الذي تعرضه عملية استرداد مستخدم.
استبدِل USER_KEY بقيمة تحدّد المستخدم في طلب واجهة برمجة التطبيقات. لمزيد من المعلومات، يُرجى الاطّلاع على users.get.

طلب

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true

الردّ

تعرض الاستجابة الناجحة رمز الحالة 200 في HTTP. بالإضافة إلى رمز الحالة، تعرض الاستجابة جميع الأدوار المحدّدة في النطاق وما إذا كان assigneeType هو user أو group:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"group",
  "scopeType:"CUSTOMER",
}

إنشاء دور

لإنشاء دور جديد، استخدِم طلب POST التالي وأضِف التفويض الموضّح في طلبات التفويض. أضِف السمتَين privilegeName وserviceId لكل امتياز يجب منحه مع هذا الدور. للاطّلاع على سمات الطلب والاستجابة، يُرجى مراجعة مرجع واجهة برمجة التطبيقات.

طلب

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

{
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

الردّ

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

{
  "kind": "admin\#directory\#role",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/uX9tXw0qyijC9nUKgCs08wo8aEM\"",
  "roleId": "3894208461013031",
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

إنشاء مهمة دور

لتعيين دور، استخدِم طريقة POST التالية وأضِف التفويض الموضّح في طلبات التفويض.

لمنح دور لمستخدم، أضِف نص JSON يتضمّن user_id الخاص بالمستخدم، والذي يمكنك الحصول عليه من users.get()، وroleId (كما هو موضّح في الحصول على الأدوار الحالية)، وscope_type.
لتخصيص الدور لحساب خدمة، أضِف نص JSON يتضمّن unique_id لحساب الخدمة (كما هو محدّد في إدارة الهوية وإمكانية الوصول (IAM)) وroleId (كما هو موضّح في الحصول على الأدوار الحالية) وscope_type.
لإسناد الدور إلى مجموعة، أضِف نص JSON يتضمّن group_id الخاص بالمجموعة، والذي يمكنك الحصول عليه من groups.get() وroleId (كما هو موضّح في الحصول على الأدوار الحالية) وscope_type.

طلب

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

الردّ

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

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

إنشاء مهمة دور تتضمّن شروطًا

يمكنك منح أدوار لتنفيذ إجراءات تستوفي شروطًا معيّنة. في الوقت الحالي، يتوفّر شرطان فقط:

لا ينطبق إلا على مجموعات الأمان
لا ينطبق على مجموعات الأمان

عند ضبط condition، لن يتم تطبيقه إلا عندما يستوفي المورد الذي يتم الوصول إليه الشرط. إذا كان condition فارغًا، يتم تطبيق الدور (roleId) على الجهة الفاعلة (assignedTo) في النطاق (scopeType) بدون شروط.

لمنح دور لمستخدم، استخدِم طريقة POST التالية وأضِف التفويض الموضّح في طلبات التفويض.

أضِف نص JSON يتضمّن user_id الخاص بالمستخدم، والذي يمكنك الحصول عليه من users.get()، وroleId كما هو موضح في الحصول على الأدوار الحالية، وcondition. يجب استخدام سلسلتَي الشرط كما هو موضّح أدناه، ولا تعملان إلا مع أدوار المشرفين المحدّدة مسبقًا في "محرّر المجموعات" و"قارئ المجموعات". تتّبع هذه الشروط بنية شروط Cloud IAM.

طلب

لا ينطبق إلا على مجموعات الأمان

POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}

لا ينطبق على مجموعات الأمان

POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}

الردّ

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

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}

إدارة الأدوار تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

حدود الأدوار وإسناد الأدوار

ربط الأدوار بالامتيازات في "وحدة تحكّم المشرف في Google"

أمثلة على حالات الاستخدام

قبل البدء

الحصول على قائمة بامتيازات النطاق

طلب

الردّ

الحصول على الأدوار الحالية

طلب

الردّ

إدراج جميع عمليات تعيين الأدوار

طلب

الردّ

عرض جميع عمليات إسناد الأدوار غير المباشرة

طلب

الردّ

إنشاء دور

طلب

الردّ

إنشاء مهمة دور

طلب

الردّ

إنشاء مهمة دور تتضمّن شروطًا

طلب

لا ينطبق إلا على مجموعات الأمان

لا ينطبق على مجموعات الأمان

الردّ

إدارة الأدوار