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

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

כמה דברים שחשוב לדעת לגבי חשבון חדש:

  • אם חשבון Google רכש רישיונות דואר, תוקצה תיבת דואר באופן אוטומטי לחשבון המשתמש החדש. יכול להיות שייקח כמה דקות להשלים את המטלה הזו ולהפעיל אותה.
  • שירות ה-API מתעלם מעריכה של שדה לקריאה בלבד בבקשה, כמו isAdmin.
  • מספר הדומיינים המקסימלי המותר בחשבון הוא 600 (דומיין ראשי אחד + 599 דומיינים נוספים)
  • אם משתמש לא הוקצה ליחידה ארגונית מסוימת כשיצרתם את חשבון המשתמש, סימן שהחשבון נמצא ביחידה הארגונית ברמה העליונה. היחידה הארגונית של המשתמש קובעת לאילו שירותי Google Workspace יש למשתמש גישה. אם המשתמש מועבר לארגון חדש, הגישה שלו משתנה. למידע נוסף על מבנים ארגוניים ניתן לעיין במרכז העזרה לאדמינים. מידע נוסף על העברת משתמש לארגון אחר זמין במאמר עדכון משתמש.
  • יש צורך ב-password לחשבונות משתמשים חדשים. אם צוין hashFunction, הסיסמה חייבת להיות מפתח גיבוב (hash) חוקי. אם לא מציינים זאת, הסיסמה צריכה להיות בטקסט ברור ובאורך של 8-100 תווי ASCII. מידע נוסף זמין בחומר העזר בנושא API.
  • עבור משתמשים בתוכנית גמישה ב-Google Workspace, ליצירת משתמשים באמצעות ה-API הזה תהיה השפעה כספית, וליצירת חיובים בחשבון לחיוב של הלקוח. מידע נוסף זמין במאמר נתוני החיוב של ה-API.
  • חשבון Google Workspace יכול לכלול כל אחד מהדומיינים שלכם. בחשבון עם מספר דומיינים, משתמשים בדומיין אחד יכולים לשתף שירותים עם משתמשים בדומיינים אחרים של החשבון. למידע נוסף על משתמשים בכמה דומיינים, אפשר לעיין במאמר מידע על דומיינים מרובים ב-API.
  • ייתכן שיש חשבונות מתנגשים. לבדוק אם למישהו שאתם מתכוונים להוסיף כבר יש חשבון Google. לאחר מכן יש לבצע את הפעולות הנדרשות כדי למנוע התנגשויות עם החשבונות האלה. אפשר לעיין במאמר חיפוש ופתרון של חשבונות בעלי מאפיינים זהים לחשבון פעיל
  • עשויים להיות חשבונות של מבקרים. אם משתמשים יזמיןו אנשים מחוץ לארגון שאין להם חשבון Google לשתף פעולה ב-Drive, הם יקבלו את חשבונות המבקרים בפורמט 's_username@your_domain.com'. אם מוסיפים משתמש עם שם משתמש זהה לזה של חשבון מבקר, החשבון יומר לחשבון Google Workspace מלא. ההרשאות הנוכחיות של הקבצים ב-Drive יישמרו בחשבון. ראו שיתוף מסמכים עם מבקרים.

תגובה מוצלחת מחזירה קוד סטטוס HTTP 200. יחד עם קוד הסטטוס, התגובה תחזיר את המאפיינים של חשבון המשתמש החדש.

עדכון חשבון משתמש

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

בדוגמה הזו, מוחזרת התמונה האחרונה של dana@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"
}

קידוד הבסיס הבטוח של התמונות שלכם באינטרנט ב-API דומה ל-RFC 4648 'base64url'. מה זה אומר?

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

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

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

בדוגמה זו, מחיקת המשתמש dana@example.com בוטלה. כל נכסי החשבון הקודמים של המשתמש הזה שוחזרו: 

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

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