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

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

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

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

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

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

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

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

طلب JSON

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

{
"primaryEmail": "[email protected]",
"name": {
 "givenName": "Elizabeth",
 "familyName": "Smith"
},
"suspended": false,
"password": "new user password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
 {
  "type": "work",
  "protocol": "gtalk",
  "im": "[email protected]",
  "primary": true
 }
],
"emails": [
 {
  "address": "[email protected]",
  "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": "[email protected]",
      "type": "work",
      "primary": true
    }
}

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

PUT https://admin.googleapis.com/admin/directory/v1/users/[email protected]

{
  "name": {
    "givenName": "Liz",
   },
  "emails": [
    {
      "address": "[email protected]",
      "type": "work",
      "primary": true
    },
    {
      "address": "[email protected]",
      "type": "home"
    }
  ]
}

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

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

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

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

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

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

طلب JSON

في هذا المثال، أصبح المستخدم الذي يحمل userKey‏ [email protected] مشرفًا متميزًا: 

POST https://admin.googleapis.com/admin/directory/v1/users/[email protected]/makeAdmin

{
 "status": true
}

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

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

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

يعرض هذا المثال سمات حساب المستخدم الذي يكون عنوان بريده الإلكتروني الأساسي أو البديل هو [email protected]: 

GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]

استجابة JSON

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

{
 "kind": "directory#user",
 "id": "the unique user id",
 "primaryEmail": "[email protected]",
 "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": "[email protected]",
   "primary": true
  }
 ],
 "emails": [
  {
   "address": "[email protected]",
   "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": [
  "[email protected]",
  "[email protected]"
 ],
 "nonEditableAliases": [
  "[email protected]"
 ],
 "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": "[email protected]",
   "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": "[email protected]",
     "primary": true
    }
   ],
   "emails": [
    {
     "address": "[email protected]",
     "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": [
    "[email protected]",
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "user unique ID",
   "primaryEmail": "[email protected]",
   "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",
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "contractor license number",
     "type": "custom",
     "customType": "work"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "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": "[email protected]",
   "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": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
     "[email protected]"
   ],
   "nonEditableAliases": [
     "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "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": "[email protected]",
     "type": "home",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "bank"
    }
   ],
   "relations": [
    {
     "value": "liz",
     "type": "friend",
     "customType": ""
    }
   ],
   "aliases": [
    "[email protected]",
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "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": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "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": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "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": "[email protected]"
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "[email protected]"
  }
 ],
 "nextPageToken": "token for next page of deleted users"
}

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

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

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

في هذا المثال، يتم عرض أحدث صورة لـ [email protected]:

GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]/photos/thumbnail

استجابة JSON

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

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "[email protected]",
 "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

في هذا المثال، تم تعديل صورة [email protected]: 

PUT https://admin.googleapis.com/admin/directory/v1/users/[email protected]/photos/thumbnail
 
{
"photoData": "web safe base64 encoded photo data"
}

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

استجابة JSON

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

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "[email protected]",
 "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

في هذا المثال، تم حذف حساب المستخدم [email protected]: 

DELETE https://admin.googleapis.com/admin/directory/v1/users/[email protected]

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

أمور مهمة يجب أخذها بعين الاعتبار قبل حذف مستخدم:

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

استعادة حساب مستخدم

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

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

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

في هذا المثال، تم إلغاء حذف المستخدم [email protected]. تتم استعادة جميع مواقع الحساب السابقة لهذا المستخدم: 

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

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