ניהול קבוצות

בדף הזה נסביר איך לנהל קבוצות 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.

כשמוחקים קבוצה:

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