בדף הזה נסביר איך לנהל קבוצות Google באמצעות ה-Directory API:
- איך יוצרים קבוצה
- עדכון קבוצה
- הוספת כינוי לקבוצה
- אחזור קבוצה
- אחזור כל הקבוצות של דומיין או של החשבון
- אחזור כל הקבוצות של חבר
- אחזור כל כתובות האימייל החלופיות של הקבוצות
- מחיקת כינוי לקבוצה
- מחיקת קבוצה
איך יוצרים קבוצה
כדי ליצור קבוצה, משתמשים בבקשת POST
הבאה וכוללים את ההרשאה שמתוארת במאמר בקשות הרשאה.
אפשר ליצור קבוצה לכל דומיין שמשויך לחשבון. למידע על מחרוזות השאילתה, מאפייני הבקשה והתגובה, ראו שיטת groups.insert
.
POST https://admin.googleapis.com/admin/directory/v1/groups
בבקשת ה-JSON הבאה מוצג גוף בקשה לדוגמה שיוצר קבוצה. כתובת האימייל של הקבוצה היא sales_group@example.com:
{ "email": "sales_group@example.com", "name": "Sales Group", "description": "This is the Sales group." }
תגובה מוצלחת מחזירה
קוד הסטטוס 201
של HTTP
ואת המאפיינים של הקבוצה החדשה.
עדכון קבוצה
כדי לעדכן את ההגדרות של קבוצה, משתמשים בבקשת PUT
הבאה וכוללים את ההרשאה שמתוארת במאמר בקשות הרשאה.
השדה groupKey
הוא כתובת האימייל של הקבוצה, כל אחת מכתובות האימייל החלופיות של הקבוצה,
או ה-id
הייחודי של הקבוצה. למידע על מחרוזות השאילתה, מאפייני הבקשה והתגובה, אפשר לעיין
בשיטה groups.update
.
PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey
באופן כללי, Google ממליצה לא להשתמש בכתובת האימייל של הקבוצה כמפתח להצגת נתונים קבועים, כי כתובת האימייל הזו עשויה להשתנות.
בדוגמה הבאה, groupKey
הייחודי הוא nnn
ושם הקבוצה הוא קבוצת המכירות של אסיה-פסיפיק (APAC):
PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn
{ "email": "sales_group@example.com", "name": "APAC Sales Group" }
לבקשת עדכון, צריך לשלוח רק את הפרטים המעודכנים בבקשה. אין צורך להזין בבקשה את כל מאפייני הקבוצה.
תגובה מוצלחת מחזירה
קוד הסטטוס 201
של HTTP
ואת המאפיינים של הקבוצה החדשה:
{ "kind": "directory#groups", "id": "group's unique ID", "etag": "group's unique ETag", "email": "sales_group@example.com", "name": "APAC Sales Group", "directMembersCount": "5", "description": "This is the APAC sales group.", "adminCreated": true, "aliases": [ { "alias": "best_sales_group@example.com" } ], "nonEditableAliases: [ { "alias": "liz@test.com" } ] }
הוספת כינוי לקבוצה
כדי להוסיף כתובת אימייל חלופית לקבוצה, צריך להשתמש בבקשת POST
הבאה ולכלול את ההרשאה
שמתוארת בקטע בקשות הרשאה.
השדה groupKey
הוא כתובת האימייל של הקבוצה, כל אחת מכתובות האימייל החלופיות של הקבוצה, או
ה-id
הייחודי של הקבוצה. למידע על מחרוזות השאילתה, מאפייני הבקשה והתגובה, ראו משאב groups
.
POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases
באופן כללי, Google ממליצה לא להשתמש בכתובת האימייל של הקבוצה כמפתח להצגת נתונים קבועים, כי כתובת האימייל הזו עשויה להשתנות.
בבקשת ה-JSON הבאה מוצגת בקשה לדוגמה ליצירת כינוי לקבוצה. הערך
groupKey
הוא id
הייחודי של הקבוצה, שמיוצג על ידי NNNN
POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases
{ "alias": "best_sales_group@example.com" }
תגובה מוצלחת תחזיר
קוד סטטוס 201
של HTTP
ואת המאפיינים של כתובת האימייל החלופית החדשה.
אחזור קבוצה
כדי לאחזר קבוצה, משתמשים בבקשתGET
הבאה וכוללים את ההרשאה שמתוארת בבקשות הרשאה.
השדה groupKey
הוא כתובת האימייל של הקבוצה, כל אחת מכתובות האימייל החלופיות של הקבוצה, או
ה-id
הייחודי של הקבוצה. למידע על מחרוזות השאילתה, מאפייני הבקשה והתגובה, אפשר לעיין בשיטה groups.get
.
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey
באופן כללי, Google ממליצה לא להשתמש בכתובת האימייל של הקבוצה כמפתח להצגת נתונים קבועים, כי כתובת האימייל הזו עשויה להשתנות.
בדוגמה הבאה, המזהה הייחודי של groupKey
הוא nnnn
:
GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn
תגובה מוצלחת מחזירה
קוד הסטטוס 200
של HTTP
ואת הגדרות הקבוצה:
{ "kind": "directory#groups", "id": "group's unique ID", "etag": "group's unique ETag", "email": "sales_group@example.com", "name": "APAC Sales Group", "directMembersCount": "5", "description": "This is the APAC sales group.", "adminCreated": true, "aliases": [ { "alias": "best_sales_group@example.com" } ], "nonEditableAliases: [ { "alias": "liz@test.com" } ] }
אחזור כל הקבוצות של דומיין או של החשבון
כדי לאחזר את כל הקבוצות של דומיין ספציפי או של החשבון, משתמשים בבקשת GET
הבאה וכוללים את ההרשאה שמתוארת בקטע Authorize requests. למידע על מחרוזות השאילתה, מאפייני הבקשה והתגובה, אפשר לעיין בשיטה groups.list
.
לצורך הקריאות, הדוגמה הזו משתמשת בהחזרות שורה:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name &customer=my_customer or customerId&pageToken=pagination token &maxResults=max results
באחזור כל הקבוצות של דומיין או של החשבון, כדאי להביא בחשבון את הנקודות הבאות:
- כל הקבוצות עבור תת-דומיין: משתמשים בארגומנט
domain
עם שם הדומיין. - כל הקבוצות של החשבון: משתמשים בארגומנט
customer
עם הערךmy_customer
או עם הערךcustomerId
של החשבון. כאדמינים של חשבון, השתמשו במחרוזתmy_customer
כדי לייצג אתcustomerId
של החשבון. אם את/ה מפיץ/ה ניגש/ת לחשבון של לקוח שקנה דרך מפיץ, יש להשתמש בcustomerId
של החשבון שקנה דרך מפיץ. עבור הערךcustomerId
, משתמשים בשם הדומיין הראשי של החשבון בבקשה של הפעולה אחזור כל המשתמשים בדומיין. התשובה שמתקבלת כוללת את הערךcustomerId
. - באמצעות הארגומנטים
domain
ו-customer
: ה-Directory API מחזיר את כל הקבוצות שלdomain
. - לא נעשה שימוש בארגומנטים
domain
ו-customer
: ה-Directory API מחזיר את כל הקבוצות של החשבון שמשויך אלmy_customer
. זהו החשבוןcustomerId
של האדמין שהגיש את הבקשה. - באמצעות הארגומנטים
customer
ו-userKey
: ה-Directory API מחזיר שגיאה. צריך לשלוח שתי בקשות נפרדות עם הארגומנטים האלה.
בדוגמה הבאה, מנהל חשבון משתמש ב-my_customer
כדי לבקש רשימה של כל הקבוצות בחשבון:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=my_customer&maxResults=2
בדוגמה הבאה, בקשה של מנהל מפיץ מחזירה את כל הקבוצות של החשבון שקנה דרך מפיץ עם customerId C03az79cb
. המספר המקסימלי של תוצאות מוחזרות לכל דף תגובה הוא 2.
יש nextPageToken
לרשימת המשתמשים למעקב בתשובה הזו:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2
תשובה מוצלחת תחזיר
קוד סטטוס 200
של HTTP
ואת הקבוצות לפי סדר האלף-בית של הודעת האימייל של הקבוצה:
{ "kind": "directory#groups", "groups": [ { "kind": "directory#groups", "id": "group's unique ID", "etag": "group's unique ETag", "email": "support@sales.com", "name": "Sales support", "directMembersCount": "6", "description": "The sales support group", "adminCreated": true }, { "kind": "directory#groups", "id": "group's unique ID", "etag": "group's unique ETag", "email": "travel@sales.com", "name": "Sales travel", "directMembersCount": "2", "description": "The travel group supporting sales", "adminCreated": false, "aliases": [ { "alias": "best_sales_group@example.com" } ], "nonEditableAliases: [ { "alias": "liz@test.com" } ] }, "nextPageToken": "NNNN" }
אחזור כל הקבוצות של חבר
כדי לאחזר את כל הקבוצות שיש להן מינוי, משתמשים בבקשת GET
הבאה וכוללים את ההרשאה שמתוארת
בבקשות הרשאה. לצורך הקריאות, הדוגמה הזו משתמשת בהחזרות שורה:
GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=user key ?pageToken=pagination token &maxResults=maximum results per response page
- החבר יכול להיות משתמש או קבוצה.
userKey
יכול להיות כתובת האימייל הראשית של המשתמש, כתובת האימייל החלופית של המשתמש, כתובת האימייל הראשית של קבוצה, כתובת האימייל החלופית של קבוצה או ה-id
הייחודי של המשתמש. המזהה יכול להופיע על ידי פעולת אחזור המשתמש.- המשתמש או הקבוצה שצוינו ב-
userKey
חייבים להיות שייכים לדומיין שלך. - כדי לקבל תשובות עם מספר גדול של קבוצות, צריך להשתמש במחרוזת השאילתה
pageToken
. במקרה של עימוד, התגובה מחזירה את המאפייןnextPageToken
שמספק אסימון לדף הבא של תוצאות התשובה. בבקשה הבאה שלך ייעשה שימוש באסימון הזה כערך מחרוזת השאילתה ב-pageToken
. - באמצעות הארגומנטים
customer
ו-userKey
: ה-Directory API מחזיר שגיאה. צריך לשלוח שתי בקשות נפרדות עם הארגומנטים האלה.
למידע על מאפייני הבקשה והתגובה, ראו method groups.list
.
תשובה מוצלחת תחזיר קוד סטטוס HTTP 200 ואת רשימת פרטי המנוי:
- מוחזרות כל הקבוצות שלחברות במועדון יש מינוי, כולל קבוצות מחוץ לדומיין של המשתמש.
- הקבוצות מוחזרות לפי הסדר האלפביתי של כתובת האימייל של כל קבוצה.
- בגוף התשובה, השדה
id
הוא המזהה הייחודי של הקבוצה. - בתגובה, רישום הקבוצה מחוץ לדומיין של המשתמש לא כולל את הכינויים של הקבוצה החיצונית.
{ "kind": "directory#groups", "groups": [ { "kind": "directory#group", "id": "group's unique ID", "etag": "group's unique ETag", "email": "sales_group@example.com", "name": "sale group", "directMembersCount": "5", "description": "Sales group" }, { "kind": "directory#group", "id": "group's unique ID", "etag": "group's unique ETag", "email": "support_group.com", "name": "support group", "directMembersCount": "5", "description": "Support group" } ], "nextPakeToken": "NNNNN" }
אחזור כל כתובות האימייל החלופיות של הקבוצות
כדי לאחזר את כל כתובות האימייל החלופיות של הקבוצה, משתמשים בבקשתGET
הבאה וכוללים את ההרשאה שמתוארת בקטע Authorize requests. השדה groupKey
יכול להיות כתובת האימייל הראשית של הקבוצה, כתובת האימייל id
הייחודית של הקבוצה או כל אחת מכתובות האימייל החלופיות של הקבוצה. למידע על מאפייני הבקשה והתגובה, עיינו במשאב groups
.
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases
.
תגובה מוצלחת תחזיר
קוד הסטטוס 201
של HTTP
ורשימה של כתובות האימייל החלופיות של הקבוצה.
מחיקת כינוי לקבוצה
כדי למחוק את הכינוי של הקבוצה, משתמשים בבקשתDELETE
הבאה וכוללים את ההרשאה שמתוארת בקטע Authorize requests.
השדה groupKey
יכול להיות כתובת האימייל הראשית של הקבוצה, כתובת האימייל id
הייחודית של הקבוצה, או כל אחת מכתובות האימייל החלופיות של הקבוצה. מתבצעת מחיקה של aliasId
. למידע על מאפייני הבקשה והתגובה, עיינו במשאב groups
:
DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases/aliasId
תגובה מוצלחת מחזירה
קוד הסטטוס 201
של HTTP.
מחיקת קבוצה
כדי למחוק קבוצה, משתמשים בבקשת DELETE
הבאה וכוללים את ההרשאה שמתוארת בקטע Authorize requests.
ה-groupKey
הוא ה-id
הייחודי של הקבוצה:
DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
לדוגמה, בעקבות הבקשה הזו ב-DELETE
המערכת תמחק את הקבוצה עם הקבוצה nnnn
id
:
DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn
תגובה מוצלחת מחזירה
קוד הסטטוס 200
של HTTP.
כשמוחקים קבוצה:
- כל חברי הקבוצה יימחקו. חשבונות המשתמש של החבר לא נמחקים.
- הארכיון של הקבוצה נמחק.
- הודעות שנשלחות לכתובת של הקבוצה שנמחקה לא נמסרות. במקום זאת, השולח יקבל הודעה חוזרת.