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

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

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

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

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

כדי ליצור חשבון משתמש באמצעות אחד מהדומיינים שלכם, צריך להשתמש בבקשה POST הבאה ולכלול את ההרשאה שמתוארת במאמר מידע על אימות והרשאה. ברשימת היקפי ההרשאות של OAuth 2.0 אפשר לראות את היקפי ההרשאות הזמינים ל-Directory API. פרטים על מאפייני מחרוזת השאילתה של הבקשה מופיעים ב-method‏ 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 היה 'אליזבת' כשנוצר חשבון המשתמש, וסופקה רק כתובת אימייל לצורכי עבודה.

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

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

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