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

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

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

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

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

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

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

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

ניהול חשבונות משתמשים קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

בקשת JSON

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

דוגמה לבקשה

הגדרת משתמש כאדמין

בקשת JSON

ניהול קשרי משתמשים

יצירת קשר בין משתמשים

עדכון או מחיקה של קשר

אחזור משתמש

תגובת JSON

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

תגובת JSON

אחזור של כל המשתמשים בחשבון

תגובת JSON

אחזור משתמשים שנמחקו לאחרונה

תגובת JSON

איך מאחזרים תמונה של משתמש

תגובת JSON

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

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

תגובת JSON

מחיקת תמונה של משתמש

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

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

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