ניהול חשבונות משתמשים

ב-Directory API יש שיטות פרוגרמטיות ליצירה, לעדכון ולמחיקה של משתמשים. אפשר גם לקבל מידע על משתמשים ספציפיים או על רשימות של משתמשים שעומדים בקריטריונים מסוימים. בהמשך מפורטות דוגמאות לפעולות בסיסיות של משתמשים.

יצירה של חשבון משתמש

אפשר להוסיף חשבון משתמש לכל אחד מהדומיינים של חשבון Google Workspace. לפני שמוסיפים חשבון משתמש, צריך לאמת את הבעלות על הדומיין.

אם שדרגתם את חשבון Gmail האישי לחשבון אימייל עסקי עם שם הדומיין שלכם, לא תוכלו ליצור חשבונות משתמשים חדשים עד שתפתחו את הנעילה של הגדרות Google Workspace נוספות. לפרטים, אפשר לעיין במאמר חשבונות אימייל עסקיים ב-G Suite ששודרגו ל-G Suite Basic.

כדי ליצור חשבון משתמש באמצעות אחד מהדומיינים שלכם, צריך להשתמש בבקשה הבאה של POST ולכלול את ההרשאה שמתוארת במאמר מידע על אימות והרשאה. אפשר לראות את ההיקפים הזמינים ל-Directory API ברשימת ההיקפים של OAuth 2.0. למאפיינים של מחרוזת השאילתה של הבקשה, ראו את השיטה users.insert(). 

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

בכל בקשת יצירה צריך לשלוח את המידע הנדרש כדי לעבד את הבקשה. אם אתם משתמשים בספריות לקוח, הן ממירות את אובייקטי הנתונים מהשפה שבחרתם באובייקטים בפורמט נתוני JSON.

בקשת JSON

ב-JSON הבא מוצגת בקשה לדוגמה ליצירת משתמש. רשימה מלאה של מאפייני הבקשות והתגובות מופיעה בחומר העזר בנושא API. 

{
"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, תינתן באופן אוטומטי תיבת דואר לחשבון המשתמש החדש. יכול להיות שיחלפו כמה דקות עד שהמטלה תושלם ותופעל.
  • שירות ה-API מתעלם בשקט מעריכה של שדה לקריאה בלבד בבקשה, כמו isAdmin.
  • מספר הדומיינים המקסימלי שאפשר להוסיף לחשבון הוא 600 (דומיין ראשי אחד + 599 דומיינים נוספים)
  • אם משתמש לא הוקצה ליחידה ארגונית ספציפית כשחשבון המשתמש נוצר, החשבון נמצא ביחידה הארגונית ברמה העליונה. היחידה הארגונית של המשתמש קובעת לאילו שירותי Google Workspace תהיה לו גישה. אם המשתמש מועבר לארגון חדש, הגישה שלו משתנה. מידע נוסף על מבני ארגון זמין במרכז העזרה לניהול. מידע נוסף על העברת משתמשים לארגון אחר זמין במאמר עדכון משתמש.
  • password נדרש לחשבונות משתמש חדשים. אם צוין hashFunction, הסיסמה חייבת להיות מפתח גיבוב חוקי. אם לא צוין, הסיסמה צריכה להיות בטקסט ללא הצפנה ולהכיל בין 8 ל-100 תווים מסוג ASCII. מידע נוסף זמין בחומר העזרה של ה-API.
  • למשתמשים בתוכנית גמישה של Google Workspace, יצירת משתמשים באמצעות ה-API הזה תהיה בעלת השפעה כספית ותגרום לחיוב בחשבון לחיוב של הלקוח. מידע נוסף זמין במאמר פרטי החיוב ב-API.
  • חשבון Google Workspace יכול לכלול כל אחד מהדומיינים שלכם. בחשבון עם כמה דומיינים, משתמשים בדומיין אחד יכולים לשתף שירותים עם משתמשים בדומיינים אחרים בחשבון. מידע נוסף על משתמשים בכמה דומיינים זמין במאמר מידע על API בכמה דומיינים.
  • יכול להיות שיש חשבונות בעלי מאפיינים זהים לחשבון פעיל. בודקים אם למישהו שאתם מתכננים להוסיף כבר יש חשבון 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 של המשתמש היה 'Elizabeth' כשחשבון המשתמש נוצר, וסופק רק כתובת אימייל לצורכי עבודה.

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

הבקשה הבאה מעדכנת את givenName מ-'Elizabeth' ל-'Liz', ומוסיפה גם כתובת אימייל ביתית. שימו לב ששתי כתובות האימייל מוצגות במלואן כי השדה הוא מערך.

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 או אחת מכתובות האימייל החלופיות של המשתמש. למאפייני הבקשה והתגובה, ראו חומר העזר בנושא API. מידע נוסף על סופר-אדמינים זמין במרכז העזרה לניהול. 

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.

ניהול מערכות יחסים עם משתמשים

ב-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 או אחת מכתובות האימייל החלופיות של המשתמש. למאפייני הבקשה והתגובה, ראו חומר העזר בנושא API. 

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*

למאפייני הבקשה והתגובה, ראו חומר העזר בנושא API.

תגובת JSON

בדוגמה הזו, כל המשתמשים בדומיין example.com מוחזר עם מקסימום 2 דומיינים של משתמשים בכל דף תגובה. ברשימה הבאה של המשתמשים בתשובה הזו מופיע הערך nextPageToken. כברירת מחדל, המערכת מחזירה רשימה של 100 משתמשים בסדר אלפביתי לפי כתובת האימייל של המשתמש: 

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

תגובה מוצלחת מחזירה קוד סטטוס HTTP 200. יחד עם קוד הסטטוס, התגובה מחזירה 2 חשבונות משתמשים בדומיין 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, צריך להשתמש בשם הדומיין הראשי של החשבון בבקשה של הפעולה Retrieve all users in a domain. התשובה שמתקבלת מכילה את הערך customerId.
  • מחרוזת השאילתה האופציונלית orderBy קובעת אם הרשימה תמוין לפי כתובת האימייל הראשית של המשתמש, שם המשפחה או השם הפרטי שלו. כשמשתמשים ב-orderBy, אפשר גם להשתמש במחרוזת השאילתה sortOrder כדי לרשום את התוצאות בסדר עולה או יורד.
  • מחרוזת השאילתה האופציונלית query מאפשרת לחפש בשדות רבים בפרופיל המשתמש, כולל שדות ליבה ושדות מותאמים אישית. דוגמאות מפורטות זמינות במאמר חיפוש משתמשים.

למאפייני הבקשה והתגובה, ראו חומר העזר בנושא API.

בדוגמה הזו, אדמין של חשבון מבקש להציג את כל המשתמשים בחשבון עם רשומת משתמש אחת בכל דף תגובה. ה-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 היא שם הדומיין הראשי של הדומיין. למאפייני הבקשה והתגובה של המשתמש, ראו חומר העזר בנושא API. כדי שקל יהיה לקרוא את הדוגמה, השתמשנו בהפסקות שורה: 

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, צריך להשתמש בשם הדומיין הראשי של החשבון בבקשה של הפעולה Retrieve all users in a domain. התשובה שמתקבלת מכילה את הערך customerId.

למאפייני הבקשה והתגובה, ראו חומר העזר בנושא API.

בדוגמה הזו, אדמין בחשבון מבקש את כל המשתמשים שנמחקו בחשבון: 

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

אחזור של תמונה של משתמש

ה-API מאחזר תמונה ממוזערת אחת, תמונת הפרופיל האחרונה ב-Google. כדי לאחזר את התמונה האחרונה של המשתמש, משתמשים בבקשה הבאה של GET וכוללים את ההרשאה שמתוארת בקטע אישור בקשות. השדה userKey יכול להיות כתובת האימייל הראשית של המשתמש, המשתמש id או כל אחת מכתובות האימייל החלופיות של המשתמש. למאפייני הבקשה והתגובה, ראו חומר העזר בנושא API. 

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 של התמונות ב-API, שמתאים לאינטרנט, דומה ל-RFC 4648 'base64url'. כלומר:

  • התו / (קו נטוי) מוחלף בתו הקו התחתון (_).
  • התו 'פלוס' (+) מוחלף בתו המקף (-).
  • התו של סימן השוויון (=) מוחלף בכוכבית (*).
  • כדי למלא את המקום, נעשה שימוש בתו הנקודה (.) במקום בהגדרה של baseURL ב-RFC-4648, שבה נעשה שימוש בסמל השוויון (=) למטרה הזו. המטרה היא לפשט את ניתוח כתובות ה-URL.
  • לא משנה מה הגודל של התמונה שמעלים, ה-API מקטין אותה באופן יחסי ל-96x96 פיקסלים.

אם אתם צריכים ליצור קישורים תואמים מ-JavaScript, Google Closure Library כוללת פונקציות קידוד ופענוח של Base64, שמתפרסמות ברישיון Apache.

אחזור משתמש ללא הרשאת אדמין

רק אדמינים יכולים לשנות את חשבונות המשתמשים, אבל כל משתמש בדומיין יכול לקרוא את פרופילי המשתמשים. משתמשים שאינם אדמינים יכולים לשלוח בקשה מסוג users.get או users.list עם הערך domain_public לפרמטר viewType כדי לאחזר את הפרופיל הציבורי של משתמש. ההיקף https://www.googleapis.com/auth/admin.directory.user.readonly מתאים במיוחד לתרחיש לדוגמה הזה.

התצוגה domain_public מאפשרת למשתמש שאינו אדמין לגשת לקבוצה רגילה של שדות ליבה. כשמגדירים שדה מותאם אישית, אפשר לבחור אם הוא יהיה ציבורי או פרטי.

עדכון התמונה של משתמש

כדי לעדכן את התמונה של משתמש, משתמשים בבקשה הבאה מסוג PUT וכוללים את ההרשאה שמתוארת בקטע בקשות לאישור. השדה userKey יכול להיות כתובת האימייל הראשית של המשתמש, המשתמש id או כל אחד מהאימיילים של כתובות האימייל החלופיות של המשתמש. למאפייני הבקשה והתגובה, ראו חומר העזר בנושא API. 

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

כשמעדכנים תמונה, ה-API מתעלם מהמדיניות 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 או כל אחד מהאימיילים של כתובות האימייל החלופיות של המשתמש. למאפייני הבקשה והתגובה, ראו חומר העזר בנושא API. 

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

אחרי המחיקה, התמונה של המשתמש לא תוצג. בכל מקום שבו נדרשת תמונה של משתמש, יוצג צללית במקום זאת.

מחיקה של חשבון משתמש

כדי למחוק חשבון משתמש, משתמשים בבקשה הבאה של DELETE וכוללים את ההרשאה שמתוארת בקטע אישור בקשות. השדה userKey יכול להיות כתובת האימייל הראשית של המשתמש, המשתמש הייחודי id או אחת מכתובות האימייל החלופיות של המשתמש. למאפייני הבקשה והתגובה, ראו חומר העזר בנושא API. 

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 שנמצא בתגובה של הפעולה Retrieve users deleted within the past 20 days. אסור להשתמש בכתובת האימייל הראשית של המשתמש או באחת מכתובות האימייל החלופיות שלו בשדה userKey של הפעולה הזו. למאפייני הבקשה והתגובה, ראו חומר העזר בנושא API. 

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. כדי לראות את החשבון של המשתמש שלא נמחק, משתמשים בפעולה אחזור משתמש.