إدارة حسابات المستخدمين

توفّر واجهة Directory API طرقًا آلية لإنشاء المستخدمين وتعديلهم وحذفهم. يمكنك أيضًا الحصول على معلومات عن مستخدمين فرديين أو قوائم بالمستخدمين الذين يستوفون معايير محدّدة. في ما يلي أمثلة على بعض عمليات المستخدم الأساسية.

إنشاء حساب مستخدم

يمكنك إضافة حساب مستخدم إلى أي من نطاقات حسابك على Google Workspace. قبل إضافة حساب مستخدم، عليك تأكيد ملكية النطاق.

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

لإنشاء حساب مستخدم باستخدام أحد نطاقاتك، استخدِم طلب POST التالي وأضِف التفويض الموضّح في التعرّف على المصادقة والتفويض. يمكنك الاطّلاع على النطاقات المتاحة لواجهة Directory API في قائمة نطاقات OAuth 2.0. للاطّلاع على سمات سلسلة طلب البحث، يُرجى الرجوع إلى طريقة users.insert.

POST https://admin.googleapis.com/admin/directory/v1/users

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

طلب JSON

يعرض ملف JSON التالي نموذج طلب لإنشاء مستخدم. للاطّلاع على القائمة الكاملة بسمات الطلب والاستجابة، يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات.

{
"primaryEmail": "liz@example.com",
"name": {
 "givenName": "Elizabeth",
 "familyName": "Smith"
},
"suspended": false,
"password": "NEW_USER_PASSWORD",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
 {
  "type": "work",
  "protocol": "gtalk",
  "im": "liz_im@talk.example.com",
  "primary": true
 }
],
"emails": [
 {
  "address": "liz@example.com",
  "type": "home",
  "customType": "",
  "primary": true
 }
],
"addresses": [
 {
  "type": "work",
  "customType": "",
  "streetAddress": "1600 Amphitheatre Parkway",
  "locality": "Mountain View",
  "region": "CA",
  "postalCode": "94043"
 }
],
"externalIds": [
 {
  "value": "12345",
  "type": "custom",
  "customType": "employee"
 }
],
"organizations": [
 {
  "name": "Google Inc.",
  "title": "SWE",
  "primary": true,
  "type": "work",
  "description": "Software engineer"
 }
],
"phones": [
 {
  "value": "+1 nnn nnn nnnn",
  "type": "work"
 }
],
"orgUnitPath": "/corp/engineering",
"includeInGlobalAddressList": true
}

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

عند إنشاء حساب جديد، يُرجى مراعاة ما يلي:

  • إذا كان حساب Google قد اشترى تراخيص بريد، سيتم تلقائيًا منح حساب المستخدم الجديد صندوق بريد. قد يستغرق إكمال عملية الربط وتفعيلها بضع دقائق.
  • عند تعديل حقل للقراءة فقط في طلب، مثل isAdmin، تتجاهل خدمة واجهة برمجة التطبيقات هذا التعديل بدون إعلامك.
  • الحدّ الأقصى لعدد النطاقات المسموح بها في الحساب هو 600 نطاق (نطاق أساسي واحد + 599 نطاقًا إضافيًا).
  • إذا لم يتم تعيين مستخدم إلى وحدة تنظيمية معيّنة عند إنشاء حساب المستخدم، يكون الحساب في الوحدة التنظيمية ذات المستوى الأعلى. تحدِّد الوحدة التنظيمية للمستخدم خدمات Google Workspace التي يمكن للمستخدم الوصول إليها. في حال نقل المستخدم إلى مؤسسة جديدة، تتغير أذونات الوصول الخاصة به. لمزيد من المعلومات حول بنى المؤسسات، يُرجى الاطّلاع على مركز مساعدة المشرفين. لمزيد من المعلومات حول نقل مستخدم إلى مؤسسة مختلفة، يُرجى الاطّلاع على تعديل مستخدم.
  • يجب توفير password لحسابات المستخدمين الجدد. إذا تم تحديد hashFunction، يجب أن تكون كلمة المرور مفتاح تجزئة صالحًا. في حال عدم تحديدها، يجب أن تكون كلمة المرور نصًا غير مرمّز وأن تتراوح بين 8 و100 حرف من أحرف ASCII. لمزيد من المعلومات، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.
  • بالنسبة إلى المستخدمين الذين لديهم خطة مرنة في Google Workspace، سيؤدي إنشاء مستخدمين باستخدام واجهة برمجة التطبيقات هذه إلى تأثير مالي وسيؤدي إلى فرض رسوم على حساب الفوترة الخاص بالعميل. لمزيد من المعلومات، يُرجى الاطّلاع على معلومات فوترة واجهة برمجة التطبيقات.
  • يمكن أن يتضمّن حساب Google Workspace أيًا من نطاقاتك. في حساب يتضمّن عدة نطاقات، يمكن للمستخدمين في أحد النطاقات مشاركة الخدمات مع المستخدمين في نطاقات الحساب الأخرى. لمزيد من المعلومات حول المستخدمين في نطاقات متعددة، يُرجى الاطّلاع على معلومات النطاقات المتعددة في واجهة برمجة التطبيقات.
  • قد تكون هناك حسابات متضاربة. تحقَّق مما إذا كان أي شخص تخطط لإضافته لديه حساب Google أم لا. وبعد ذلك، اتّبِع الخطوات لتجنُّب التعارض مع هذه الحسابات. راجِع مقالة العثور على الحسابات المتضاربة وحلّها.
  • قد تكون هناك حسابات زائرين. إذا دعا المستخدمون أشخاصًا خارج مؤسستك لا يملكون حسابات Google للتعاون في Drive، سيتلقّون حسابات زائرين بالتنسيق visitor's_username@your_domain.com. في حال إضافة مستخدم لديه اسم المستخدم نفسه الخاص بحساب زائر، يتم تحويل الحساب إلى حساب Google Workspace كامل. سيحتفظ الحساب بأذوناته الحالية لملفات Drive. راجِع مشاركة المستندات مع الزوّار.

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

تعديل حساب مستخدم

لتعديل حساب مستخدم، استخدِم طلب PUT التالي وأضِف التفويض الموضّح في طلبات التفويض. يمكن أن يكون userKey عنوان البريد الإلكتروني الرئيسي للمستخدم أو id الفريد للمستخدم أو أحد عناوين البريد الإلكتروني البديلة للمستخدم.

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey

يحتوي كل من نص الطلب ونص الاستجابة على مثال User. ومع ذلك، تتيح Directory API دلالات التصحيح، لذا عليك فقط إرسال الحقول المعدَّلة في طلبك.

عيّنة طلب

في المثال أدناه، كان givenName الخاص بالمستخدم هو "إليزابيث" عند إنشاء حساب المستخدم، وتم تقديم عنوان بريد إلكتروني خاص بالعمل فقط.

{
  "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith"
   },
  "emails": [
    {
      "address": "liz@example.com",
      "type": "work",
      "primary": true
    }
  ]
}

يعدّل الطلب التالي اسم givenName من "إليزابيث" إلى "ليز"، ويضيف أيضًا عنوان بريد إلكتروني منزلي. يُرجى العِلم أنّه يتم تقديم كلا عنوانَي البريد الإلكتروني بشكل كامل لأنّ الحقل عبارة عن مصفوفة.

PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

{
  "name": {
    "givenName": "Liz",
   },
  "emails": [
    {
      "address": "liz@example.com",
      "type": "work",
      "primary": true
    },
    {
      "address": "liz@home.com",
      "type": "home"
    }
  ]
}

تعرض الاستجابة الناجحة رمز الحالة HTTP 200 ومورد User يتضمّن الحقول المعدَّلة.

يُرجى الانتباه إلى ما يلي عند تعديل اسم حساب أحد المستخدمين:

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

منح مستخدم دور المشرف

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

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdmin

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

طلب JSON

في هذا المثال، أصبح المستخدم الذي يحمل المعرّف userKey بالقيمة liz@example.com مشرفًا متميّزًا:

POST https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/makeAdmin

{
 "status": true
}

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

إدارة علاقات المستخدمين

تستخدم Directory API الحقل relations لتحديد أنواع مختلفة من العلاقات بين المستخدمين. في بيئة العمل، يستخدم الأشخاص عادةً هذا الحقل لتحديد علاقات المدير بالموظف والمساعد، ولكن يمكن استخدام الحقل لتحديد أنواع أخرى من العلاقات أيضًا. تظهر العلاقة في بطاقة "الأشخاص المرتبطون" الخاصة بالمستخدم في أي تطبيق من تطبيقات Google Workspace يتوافق مع البطاقة. للاطّلاع على أمثلة على الأماكن التي تظهر فيها البطاقة، يُرجى الاطّلاع على إضافة معلومات إلى الملف الشخصي للمستخدم في الدليل.

إنشاء علاقة بين المستخدمين

يمكنك تحديد علاقة في اتجاه واحد فقط، بدءًا من المستخدم "المالك" الذي يتضمّن سجله الحقل relations. يصف type علاقة الشخص الآخر بالمستخدم المالك. على سبيل المثال، في علاقة بين مدير وموظف، يكون الموظف هو المستخدم المالك، ويمكنك إضافة حقل relations إلى حسابه من النوع manager. بالنسبة إلى الأنواع المسموح بها، راجِع مرجع عنصر User.

يمكنك إعداد العلاقة من خلال إنشاء أو تعديل المستخدم المالك باستخدام نص طلب JSON يتضمّن الحقل relations. يمكنك إنشاء علاقات متعددة في طلب واحد.

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_1",
      "type": "manager"
    },
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "dotted_line_manager"
    }
  ]
}

تعديل علاقة أو حذفها

يمكنك تعديل الحقل relations ككل فقط، ولا يمكنك مخاطبة الأشخاص الفرديين المدرَجين لتغيير نوع العلاقة أو إزالتهم. في المثال السابق، لإزالة علاقة الحساب الإداري الحالية وجعل الحساب الإداري ذي الخط المتقطّع هو الحساب الإداري للمستخدم المالك، عدِّل حساب المستخدم المالك باستخدام جميع قيم الحقول كما تريدها الآن.

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "manager"
    }
  ]
}

لإزالة جميع علاقات المستخدم المالك، اضبط قيمة relations على فارغة:

{
  "relations": []
}

استرداد مستخدم

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

GET https://admin.googleapis.com/admin/directory/v1/users/userKey

يعرض هذا المثال خصائص حساب المستخدم الذي يكون عنوان بريده الإلكتروني الرئيسي أو البديل هو liz@example.com:

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

استجابة JSON

تعرض الاستجابة الناجحة رمز الحالة HTTP 200. بالإضافة إلى رمز الحالة، تعرض الاستجابة خصائص حساب المستخدم.

{
 "kind": "directory#user",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "name": {
  "givenName": "Liz",
  "familyName": "Smith",
  "fullName": "Liz Smith"
 },
 "isAdmin": true,
 "isDelegatedAdmin": false,
 "lastLoginTime": "2013-02-05T10:30:03.325Z",
 "creationTime": "2010-04-05T17:30:04.325Z",
 "agreedToTerms": true,
 "hashFunction": "SHA-1",
 "suspended": false,
 "changePasswordAtNextLogin": false,
 "ipWhitelisted": false,
 "ims": [
  {
   "type": "work",
   "protocol": "gtalk",
   "im": "lizim@talk.example.com",
   "primary": true
  }
 ],
 "emails": [
  {
   "address": "liz@example.com",
   "type": "home",
   "customType": "",
   "primary": true
  }
 ],
 "addresses": [
  {
   "type": "work",
   "customType": "",
   "streetAddress": "1600 Amphitheatre Parkway",
   "locality": "Mountain View",
   "region": "CA",
   "postalCode": "94043"
  }
 ],
 "externalIds": [
  {
   "value": "employee number",
   "type": "custom",
   "customType": "office"
  }
 ],
 "organizations": [
  {
   "name": "Google Inc.",
   "title": "SWE",
   "primary": true,
   "customType": "",
   "description": "Software engineer"
  }
 ],
 "phones": [
  {
   "value": "+1 nnn nnn nnnn",
   "type": "work"
  }
 ],
 "aliases": [
  "lizsmith@example.com",
  "lsmith@example.com"
 ],
 "nonEditableAliases": [
  "liz@test.com"
 ],
 "customerId": "C03az79cb",
 "orgUnitPath": "corp/engineering",
 "isMailboxSetup": true,
 "includeInGlobalAddressList": true
}

استرداد جميع المستخدمين في نطاق

لاسترداد جميع المستخدمين في النطاق نفسه، استخدِم طلب GET التالي وأضِف التفويض الموضّح في طلبات التفويض. ولسهولة القراءة، يستخدم هذا المثال أحرف الرجوع إلى أول السطر:

GET https://admin.googleapis.com/admin/directory/v1/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=email, givenName, or familyName:the query's value*

للاطّلاع على سمات الطلب والاستجابة، يُرجى مراجعة مرجع واجهة برمجة التطبيقات.

استجابة JSON

في هذا المثال، يتم عرض جميع المستخدمين في النطاق example.com مع حد أقصى يبلغ نطاقَي مستخدمَين لكل صفحة رد. هناك nextPageToken للقائمة التالية من المستخدمين في هذه الاستجابة. يعرض النظام تلقائيًا قائمة تضم 100 مستخدم مرتّبين أبجديًا حسب عنوان البريد الإلكتروني للمستخدم:

GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2

تعرض الاستجابة الناجحة رمز الحالة HTTP 200. إلى جانب رمز الحالة، تعرض الاستجابة حسابَي مستخدمَين في النطاق example.com (maxResults=2):

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "liz@example.com",
   "name": {
    "givenName": "Liz",
    "familyName": "Smith",
    "fullName": "Liz Smith"
   },
   "isAdmin": true,
   "isDelegatedAdmin": false,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "ims": [
    {
     "type": "work",
     "protocol": "gtalk",
     "im": "lizim@talk.example.com",
     "primary": true
    }
   ],
   "emails": [
    {
     "address": "liz@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "addresses": [
    {
     "type": "work",
     "customType": "",
     "streetAddress": "1600 Amphitheatre Parkway",
     "locality": "Mountain View",
     "region": "CA",
     "postalCode": "94043"
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "organizations": [
    {
     "name": "Google Inc.",
     "title": "SWE",
     "primary": true,
     "customType": "",
     "description": "Software engineer"
    }
   ],
   "phones": [
    {
     "value": "+1 nnn nnn nnnn",
     "type": "work"
    }
   ],
   "aliases": [
    "lizsmith@example.com",
    "lsmith@example.com"
   ],
   "nonEditableAliases": [
    "liz@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "user unique ID",
   "primaryEmail": "admin2@example.com",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": true,
   "suspensionReason": "ADMIN",
   "suspensionTime": "2013-02-05T10:30:03.325Z",
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "admin2@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "contractor license number",
     "type": "custom",
     "customType": "work"
    }
   ],
   "aliases": [
    "second_admin@example.com"
   ],
   "nonEditableAliases": [
    "admin@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "next page token"
}

استرداد جميع مستخدمي الحساب

لاسترداد جميع المستخدمين في حساب يمكن أن يتألف من نطاقات متعددة، استخدِم طلب GET التالي وأضِف التفويض الموضّح في طلبات التفويض. ولسهولة القراءة، يستخدم هذا المثال أحرف الرجوع إلى أول السطر:

GET https://admin.googleapis.com/admin/directory/v1/users
?customer=my_customer or customerId&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=user attributes
  • سلسلة طلب البحث customer هي القيمة my_customer أو القيمة customerId.
  • استخدِم السلسلة my_customer لتمثيل customerId حسابك.
  • بصفتك مشرفًا لدى مورِّد، استخدِم customerId الخاص بالعميل الذي تمّت إعادة بيع النطاق له. بالنسبة إلى customerId، استخدِم اسم النطاق الأساسي للحساب في طلب عملية استرداد جميع المستخدمين ضمن أحد النطاقات. تحتوي الاستجابة الناتجة على القيمة customerId.
  • يحدّد سلسلة طلب البحث الاختيارية orderBy ما إذا كان سيتم ترتيب القائمة حسب عنوان البريد الإلكتروني الأساسي للمستخدم أو اسم العائلة أو الاسم الأول. عند استخدام orderBy، يمكنك أيضًا استخدام سلسلة طلب البحث sortOrder لعرض النتائج بالترتيب التصاعدي أو التنازلي.
  • تسمح سلسلة طلب البحث الاختيارية query بالبحث في العديد من الحقول في الملف الشخصي للمستخدم، بما في ذلك الحقول الأساسية والمخصّصة. راجِع مقالة البحث عن المستخدمين للاطّلاع على أمثلة.

للاطّلاع على سمات الطلب والاستجابة، يُرجى مراجعة مرجع واجهة برمجة التطبيقات.

في هذا المثال، يطلب مشرف حساب عرض جميع المستخدمين في الحساب مع إدخال مستخدم واحد في كل صفحة رد. يتم الانتقال إلى صفحة النتائج التالية عند النقر على nextPageToken:

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&maxResults=1

في هذا المثال، يطلب مشرف مورِّد جميع المستخدمين في حساب تمت إعادة بيعه، ويحمل القيمة customerId من C03az79cb.

GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1

استجابة JSON

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

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "admin2@example.com",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "admin2@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
     "second_admin@example.com"
   ],
   "nonEditableAliases": [
     "another_admin@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "liz@example.com",
   "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith",
    "fullName": "Elizabeth Smith"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": false,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "liz@example.com",
     "type": "home",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "bank"
    }
   ],
   "relations": [
    {
     "value": "liz",
     "type": "friend",
     "customType": ""
    }
   ],
   "aliases": [
    "lizsmith@example.com",
    "lsmith@example.com"
   ],
   "nonEditableAliases": [
    "liz@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "test3@example.com",
   "name": {
    "givenName": "Tester",
    "familyName": "Three",
    "fullName": "Tester Three"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "test@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "tester3@example.com"
   ],
   "nonEditableAliases": [
    "third@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "work_admin@example.com",
   "name": {
    "givenName": "Admin",
    "familyName": "Work",
    "fullName": "Admin Work"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "work_admin@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "my_alias@example.com"
   ],
   "nonEditableAliases": [
    "other_alias@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "NNNNN"
}

استرداد المستخدمين الذين تم حذفهم مؤخرًا

لاسترداد جميع المستخدمين الذين تم حذفهم خلال آخر 20 يومًا من حساب أو من أحد نطاقات الحساب، استخدِم طلبات GET التالية وأضِف التفويض الموضّح في طلبات التفويض. لاستعادة مستخدم تم حذفه، يُرجى الاطّلاع على استعادة مستخدم تم حذفه.

لاسترداد المستخدمين الذين تم حذفهم خلال آخر 20 يومًا من النطاق الأساسي للحساب أو نطاق فرعي، استخدِم طلب GET التالي. domain سلسلة طلب البحث هي اسم النطاق الأساسي للنطاق. للاطّلاع على سمات طلبات المستخدمين والاستجابات، يُرجى مراجعة مرجع واجهة برمجة التطبيقات. ولسهولة القراءة، يستخدم هذا المثال أحرف الرجوع إلى أول السطر:

GET https://admin.googleapis.com/admin/directory/v1/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&showDeleted=true

إذا كان الحساب يتضمّن نطاقات متعدّدة، يمكنك استرداد المستخدمين الذين تم حذفهم خلال آخر 20 يومًا من الحساب بأكمله، وذلك باستخدام الطلب التالي GET. لسهولة القراءة، يستخدم هذا المثال أحرف الرجوع إلى أول السطر:

GET https://admin.googleapis.com/admin/directory/v1/users
?customer=my_customer or customerId&pageToken=token for next results page
&maxResults=max number of results per page&showDeleted=true
  • سلسلة طلب البحث customer هي القيمة my_customer أو القيمة customerId.
  • بصفتك مشرف حساب، استخدِم السلسلة my_customer لتمثيل customerId لحسابك.
  • بصفتك مشرفًا لدى مورِّد، استخدِم customerId الخاص بالعميل الذي تمّت إعادة بيع النطاق له. بالنسبة إلى customerId، استخدِم اسم النطاق الأساسي للحساب في طلب عملية استرداد جميع المستخدمين ضمن أحد النطاقات. تحتوي الاستجابة الناتجة على القيمة customerId.

للاطّلاع على سمات الطلب والاستجابة، يُرجى مراجعة مرجع واجهة برمجة التطبيقات.

في هذا المثال، يطلب مشرف حساب جميع المستخدمين المحذوفين في الحساب:

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&showDeleted=true

استجابة JSON

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

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "user1@example.com"
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "user3@example.com"
  }
 ],
 "nextPageToken": "token for next page of deleted users"
}

استرداد صورة مستخدم

تسترد واجهة برمجة التطبيقات صورة مصغّرة واحدة، وهي أحدث صورة للملف الشخصي في حساب Google. لاسترداد أحدث صورة للمستخدم، استخدِم طلب GET التالي وأضِف التفويض الموضّح في تفويض الطلبات. يمكن أن يكون userKey هو عنوان البريد الإلكتروني الرئيسي للمستخدم أو id أو أي من عناوين البريد الإلكتروني البديلة للمستخدم. للاطّلاع على سمات الطلب والاستجابة، يُرجى مراجعة مرجع واجهة برمجة التطبيقات.

GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

في هذا المثال، يتم عرض أحدث صورة لـ liz@example.com:

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail

استجابة JSON

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

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

إنّ ترميز base64 الآمن على الويب الذي تستخدمه واجهة برمجة التطبيقات لصورك يشبه RFC 4648‏ "base64url". ويعني ذلك ما يلي:

  • يتم استبدال الشرطة المائلة (/) بشرطة سفلية (_).
  • يتم استبدال علامة الجمع (+) بعلامة الطرح (-).
  • يتم استبدال علامة المساواة (=) بعلامة النجمة (*).
  • بالنسبة إلى المساحة المتروكة، يتم استخدام النقطة (.) بدلاً من تعريف RFC-4648 baseURL الذي يستخدم علامة المساواة (=) للمساحة المتروكة. ويتم ذلك لتبسيط عملية تحليل عناوين URL.
  • بغض النظر عن حجم الصورة التي يتم تحميلها، تقلّل واجهة برمجة التطبيقات حجمها بشكل متناسب إلى 96 × 96 بكسل.

إذا كنت بحاجة إلى إنشاء روابط متوافقة من JavaScript، تتضمّن مكتبة Google Closure وظائف ترميز وفك ترميز Base64 التي يتم إصدارها بموجب ترخيص Apache.

استرداد مستخدم كغير مشرف

مع أنّ المشرفين فقط يمكنهم تعديل حسابات المستخدمين، يمكن لأي مستخدم على النطاق قراءة الملفات الشخصية للمستخدمين. يمكن للمستخدم غير المشرف تقديم طلب users.get أو users.list مع ضبط المَعلمة viewType على القيمة domain_public لاسترداد الملف الشخصي العلني للمستخدم. يُعد النطاق https://www.googleapis.com/auth/admin.directory.user.readonly مثاليًا لحالة الاستخدام هذه.

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

تعديل صورة مستخدم

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

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

في هذا المثال، يتم تعديل صورة liz@example.com:

PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail

{
"photoData": "web safe base64 encoded photo data"
}

عند تعديل صورة، تتجاهل واجهة برمجة التطبيقات سياستَي height وwidth.

استجابة JSON

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

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

حذف صورة مستخدم

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

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

بعد حذف صورة المستخدم، لن تظهر. في أي مكان يُطلب فيه صورة المستخدم، سيتم عرض صورة ظلية بدلاً منها.

حذف حساب مستخدم

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

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey

في هذا المثال، تم حذف حساب المستخدم liz@example.com:

DELETE https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

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

قبل حذف مستخدم، يجب مراعاة ما يلي:

  • لن يتمكّن المستخدم المحذوف من تسجيل الدخول بعد الآن.
  • لمزيد من المعلومات حول حذف حسابات المستخدمين، يُرجى الرجوع إلى مركز مساعدة المشرفين.

إلغاء حذف حساب مستخدم

يجب أن يستوفي المستخدم الذي تم حذفه في آخر 20 يومًا شروطًا معيّنة قبل أن يتم استعادة حسابه.

لاستعادة حساب مستخدم تم حذفه، استخدِم طلب POST التالي وأضِف التفويض الموضّح في طلبات التفويض. ‫userKey هو معرّف المستخدم الفريد id الذي تم العثور عليه في رد عملية استرداد المستخدمين الذين تم حذفهم خلال آخر 20 يومًا. لا يمكن استخدام عنوان البريد الإلكتروني الرئيسي للمستخدم أو أحد عناوين البريد الإلكتروني البديلة الخاصة به في userKey لهذه العملية. للاطّلاع على سمات الطلب والاستجابة، يُرجى مراجعة مرجع واجهة برمجة التطبيقات.

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undelete

في هذا المثال، تم استعادة المستخدم liz@example.com. تتم استعادة جميع خصائص الحساب السابقة لهذا المستخدم، بما في ذلك:

POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete

تعرض الاستجابة الناجحة رمز الحالة HTTP 204. للاطّلاع على حساب المستخدم الذي تم إلغاء حذفه، استخدِم عملية استرداد مستخدم.