ניהול קבוצות

בדף הזה נסביר איך לנהל קבוצות Google באמצעות Directory API:

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

איך יוצרים קבוצה

כדי ליצור קבוצה, צריך להשתמש בבקשת POST הבאה ולכלול את ההרשאה מתואר ב: אישור בקשות. אפשר ליצור קבוצה לכל דומיין שמשויך לחשבון. למחרוזות השאילתה, מבקשים, ומאפייני תגובה, השיטה groups.insert. 

POST https://admin.googleapis.com/admin/directory/v1/groups

בבקשת ה-JSON הבאה מוצג גוף בקשה לדוגמה שיוצר קבוצה. כתובת האימייל של הקבוצה הכתובת היא [email protected]: 

{
   "email": "[email protected]",
   "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": "[email protected]",
    "name": "APAC Sales Group"
}

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

תשובה מוצלחת תחזיר קוד הסטטוס 201 של HTTP והמאפיינים של הקבוצה החדשה: 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "[email protected]",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "[email protected]"
     }
    ],
    "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": "[email protected]"
}

תשובה מוצלחת תחזיר קוד הסטטוס 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": "[email protected]",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "[email protected]"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "liz@test.com"
     }
    ]
}

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

כדי לאחזר את כל הקבוצות של דומיין ספציפי או של החשבון, צריך להשתמש בפקודת GET הבאה הבקשה ותכלול את ההרשאה המתוארת אישור בקשות. לגבי השאילתה מחרוזות, בקשות ומאפייני תגובה, השיטה 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": "[email protected]",
      "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": "[email protected]",
      "name": "Sales travel",
      "directMembersCount": "2",
      "description": "The travel group supporting sales",
      "adminCreated": false,
      "aliases": [
       {
         "alias": "[email protected]"
       }
      ],
      "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 מחזיר שגיאה. צריך לשלוח שתי בקשות נפרדות עם ארגומנטים.

למאפיינים של הבקשה והתגובה עיינו בקטע השיטה groups.list.

תשובה מוצלחת תחזיר קוד הסטטוס HTTP 200 ואת רשימת פרטי החברים:

  • כל הקבוצות שלחבר יש מינוי אליהן, כולל קבוצות מחוץ לקבוצה של המשתמש פשוט מוחזרים.
  • הקבוצות מוחזרות לפי סדר אלפביתי של כתובת האימייל של כל קבוצה.
  • בגוף התשובה, id הוא המזהה הייחודי של הקבוצה.
  • בתשובה, הדף של קבוצה מחוץ לדומיין של המשתמש לא כולל את מחוץ לכינויים של הקבוצה. 
{
    "kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "[email protected]",
      "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 הבאה ולכלול את הרשאה המתוארת ב אישור בקשות. groupKey יכול להיות כתובת האימייל הראשית של הקבוצה, כתובת האימייל הייחודית של הקבוצה id, או כל אחד מהכינויים של הקבוצות הודעות אימייל. למאפיינים של הבקשה והתגובה: מקור המידע groups. 

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

תשובה מוצלחת תחזיר קוד הסטטוס 201 של HTTP ורשימה של הכינויים של הקבוצה.

מחיקת כינוי קבוצה

כדי למחוק את הכינוי של קבוצה, צריך להשתמש בבקשת DELETE הבאה ולכלול את הרשאה המתוארת ב אישור בקשות. groupKey יכול להיות כתובת האימייל הראשית של הקבוצה, כתובת האימייל הייחודית של הקבוצה id, או כל אחד מהכינויים של הקבוצות הודעות אימייל. aliasId הוא הכינוי נמחק. למאפיינים של הבקשה והתשובה יש לעיין במשאב groups: 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases/aliasId

תשובה מוצלחת תחזיר קוד הסטטוס 201 של HTTP.

איך מוחקים קבוצה

כדי למחוק קבוצה, צריך להשתמש בבקשת DELETE הבאה ולכלול את ההרשאה מתואר ב: אישור בקשות. 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.

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

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