ניהול קבוצות

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

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

יצירת קבוצה

כדי ליצור קבוצה, משתמשים בבקשת POST הבאה וכוללים את ההרשאה שמתוארת בקטע בקשות הרשאה. אפשר ליצור קבוצה לכל דומיין שמשויך לחשבון. מידע על מחרוזות השאילתה, הבקשה והמאפיינים של התגובה זמין במאמר ה-method‏ 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."
}

בתגובה מוצלחת מופיע קוד סטטוס HTTP 201 והמאפיינים של הקבוצה החדשה.

עדכון קבוצה

כדי לעדכן את ההגדרות של קבוצה, משתמשים בבקשה הבאה של PUT וכוללים את ההרשאה שמתוארת בקטע בקשות לאישור. השדה groupKey הוא כתובת האימייל של הקבוצה, כל אחת מכתובות האימייל החלופיות של הקבוצה או השדה id הייחודי של הקבוצה. מידע על מחרוזות השאילתה, הבקשה והתגובה זמין במאמר ה-method‏ groups.update. 

PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey

באופן כללי, Google ממליצה לא להשתמש בכתובת האימייל של הקבוצה כמפתח לנתונים קבועים, כי כתובת האימייל עשויה להשתנות.

בדוגמה הבאה, הערך הייחודי של groupKey הוא nnn והשם של הקבוצה הוא APAC Sales Group: 

PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn

{
    "email": "sales_group@example.com",
    "name": "APAC Sales Group"
}

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

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

{
    "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"
}

בתשובה מוצלחת מופיע קוד סטטוס HTTP‏ 201 והמאפיינים של הכינוי החדש לקבוצה.

אחזור קבוצה

כדי לאחזר קבוצה, משתמשים בבקשה GET הבאה וכוללים את ההרשאה שמתוארת בקטע בקשות לאישור. השדה groupKey הוא כתובת האימייל של הקבוצה, כל אחת מכתובות האימייל החלופיות של הקבוצה או השדה id הייחודי של הקבוצה. מידע על מחרוזות השאילתה, הבקשה והתגובה זמין במאמר ה-method‏ 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

בתגובה מוצלחת מוחזר קוד סטטוס HTTP 200 וההגדרות של הקבוצה: 

{
    "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 ומצרפים את ההרשאה שמתוארת בקטע הרשאת בקשות. מידע על מחרוזות השאילתה, הבקשה והתגובה זמין במאמר ה-method‏ 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, משתמשים בשם הדומיין הראשי של החשבון בבקשה של הפעולה Retrieve all users in a domain. התשובה שמתקבלת מכילה את הערך 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

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

{
"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 וכוללים את ההרשאה שמתוארת בקטע בקשות הרשאה. הערך של groupKey יכול להיות כתובת האימייל הראשית של הקבוצה, הערך הייחודי של id של הקבוצה או כל אחת מכתובות האימייל החלופיות של הקבוצה. למאפייני הבקשה והתגובה, עיינו במידע על משאב groups. 

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

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

מחיקת קבוצה חלופית

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

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

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

מחיקת קבוצה

כדי למחוק קבוצה, משתמשים בבקשה הבאה של 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

בתגובה מוצלחת מוחזר קוד סטטוס HTTP 200.

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

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