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

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

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

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

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

لإنشاء حساب مستخدم باستخدام أحد نطاقاتك، استخدِم طلب POST التالي وأدرِج التفويض الموضّح في مزيد من المعلومات عن المصادقة والترخيص. يمكنك عرض النطاقات المتاحة لواجهة برمجة التطبيقات للدليل في قائمة نطاقات 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، ستظهر لهم حسابات الزوّار بالتنسيق user's_username@your_domain.com. وفي حال إضافة مستخدم يحمل اسم المستخدم نفسه كحساب زائر، سيتم تحويل الحساب إلى حساب Google Workspace كامل. سيحتفظ الحساب بأذوناته الحالية لملفات Drive. يُرجى الاطّلاع على مشاركة المستندات مع الزائرين.

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

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

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

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

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

نموذج طلب

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

{
  "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

طلب JSON

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

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

{
 "status": true
}

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

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

تستخدم واجهة برمجة تطبيقات الدليل الحقل 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

يعرض هذا المثال خصائص حساب المستخدم للمستخدم الذي يكون عنوان بريده الإلكتروني الأساسي أو البديل هو 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",
   "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". وهذا يعني ما يلي:

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

إذا كنت بحاجة إلى إنشاء روابط متوافقة من JavaScript، ستتضمّن Google Closure Library دوال الترميز وفك الترميز 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. للاطّلاع على حساب المستخدم الذي تم إلغاء حذفه، استخدِم عملية استرداد حساب مستخدم.