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

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

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

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

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

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

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

تتطلب منك جميع طلبات الإنشاء إرسال المعلومات اللازمة لتنفيذ الطلب. إذا كنت تستخدم مكتبات العملاء، فإنها تحوّل كائنات البيانات من اللغة التي اخترتها إلى كائنات JSON بتنسيق البيانات 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 من خادم واجهة برمجة التطبيقات (API) مما يشير إلى تجاوز حصتك. إذا تلقّيت هذه الردود، استخدِم خوارزمية التراجع الأسي لإعادة محاولة تقديم الطلبات.

في ما يلي بعض الملاحظات حول الحساب الجديد:

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

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

تحديث حساب مستخدم

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

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

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

نموذج طلب

في المثال أدناه، كان 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

طلب 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 المتوافقة مع البطاقة. للحصول على أمثلة حول الأماكن التي تظهر فيها البطاقة، راجع إضافة معلومات إلى الملف الشخصي للمستخدم في الدليل.

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

يمكنك تعريف العلاقة في اتجاه واحد فقط، بدءًا من المستخدم "المالك" الذي يتضمن سجله الحقل 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 وظائف الترميز وفك الترميز 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. للاطلاع على حساب المستخدم الذي لم يتم حذفه، استخدم عملية استرداد مستخدم.