ניהול קבוצות

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

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

עדכון קבוצה

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

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

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

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

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

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. פרטים על מחרוזות השאילתה, הבקשה ומאפייני התגובה מופיעים ב-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, שאפשר למצוא באמצעות הפעולה Retrieve a user.
  • המשתמש או הקבוצה שצוינו ב-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": "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"
     }
  ],
   "nextPageToken": "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 group id:

DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn

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

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

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