Directory API: יחידות ארגוניות

ניהול יחידות ארגוניות

מבנה העץ הארגוני של חשבון Google Workspace מורכב מיחידות ארגוניות שמאפשרות לכם לנהל את המשתמשים במבנה הגיוני והיררכי. הפונקציונליות הזו דומה לזו שמופיעה בכרטיסייה 'ארגונים ומשתמשים' במסוף Google Admin. ההיררכיה של היחידות הארגוניות של הלקוח מוגבלת ל-35 רמות עומק. מידע נוסף זמין במרכז העזרה לאדמינים.

  • לכל חשבון Google Workspace יש רק עץ ארגוני אחד. כשמגדירים את החשבון הזה בפעם הראשונה, יש בו יחידה ארגונית ברמת החשבון. הארגון שמשויך לדומיין הראשי. מידע נוסף על הדומיין הראשי מופיע במאמר מידע על מגבלות ה-API.
  • נתיב שם של יחידה ארגונית הוא ייחודי. השם של היחידה הארגונית לא חייב להיות ייחודי בהיררכיה של הארגון, אבל הוא צריך להיות ייחודי בין היחידות הארגוניות באותה רמה. השם של יחידה ארגונית לא תלוי באותיות רישיות (case-insensitive).
  • יחידה ארגונית יורשת את כללי המדיניות מההיררכיה הארגונית. כל יחידה ארגונית יכולה לחסום את שרשרת הירושה הזו של ההגדרות ברמה העליונה על ידי שינוי המדיניות שהועברה בירושה. העדיפות של מדיניות אחת על פני מדיניות אחרת נקבעת לפי היחידה הארגונית הקרובה ביותר. כלומר, למדיניות של יחידה ארגונית ברמה נמוכה יותר יכולה להיות עדיפות על פני המדיניות של יחידות הורה ברמה גבוהה יותר. מידע נוסף על ירושה ועל משתמשים במבנה ארגוני זמין במרכז העזרה למנהלי מערכת.
  • אפשר להעביר יחידה ארגונית למעלה או למטה בעץ ההיררכי. בנוסף, אפשר להעביר את המשתמשים שמשויכים לארגון בנפרד או בקבוצות, כשמאכלסים ארגון חדש או כשמעבירים קבוצת משנה של משתמשים מיחידה ארגונית אחת ליחידה ארגונית אחרת.
  • הנתונים ששמורים במאפיינים של יחידה ארגונית יכולים להשתנות כל הזמן. כשמבצעים בקשה, מובטח שהמאפיינים שמוחזרים עבור ישות יהיו עקביים בזמן שליפת הישות.כלומר, לא יופיעו עדכונים חלקיים. אם פעולת אחזור מחזירה יותר מישות אחת, אין עקביות בין הישויות.זה נכון במיוחד אם התשובה מתפרסת על כמה דפים בעימוד.

יצירת יחידה ארגונית

כדי ליצור יחידה ארגונית, משתמשים בבקשת POST הבאה וכוללים את ההרשאה שמתוארת במאמר אישור בקשות.

אם אתם אדמינים שיוצרים יחידה ארגונית, השתמשו ב-my_customer.

POST https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits

אם אתם מפיצים שיוצרים יחידה ארגונית עבור לקוח שרכשתם ממנו מוצרים למכירה חוזרת, השתמשו ב-customerId. כדי לאחזר את customerId, משתמשים בפעולה Retrieve a user.

POST https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits

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

בקשת JSON

בדוגמה הבאה של JSON למפיץ מוצג גוף בקשה לדוגמה שיוצר את היחידה הארגונית sales_support. חובה לציין את name ואת parentOrgUnitPath: 

POST https://admin.googleapis.com/admin/directory/v1/customer/C03az79cb/orgunits

{
    "name": "sales_support",
    "description": "The sales support team",
    "parentOrgUnitPath": "/corp/support",
}

תגובת JSON

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

{
    "kind": "directory#orgUnit",
    "name": "sales_support",
    "description": "The sales support team",
    "orgUnitPath": "/corp/support/sales_support",
    "parentOrgUnitPath": "/corp/support"
  }

עדכון של יחידה ארגונית

כדי לעדכן יחידה ארגונית, משתמשים בבקשת PUT הבאה וכוללים את ההרשאה שמתוארת במאמר אישור בקשות. מאפייני הבקשה והתגובה מפורטים בהפניית ה-API:

אם אתם אדמינים ומעדכנים יחידה ארגונית, אתם יכולים להשתמש ב-my_customer.

 PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/orgUnitPath

אם אתם מפיצים ומעדכנים יחידה ארגונית של לקוח שקנה מכם, אתם צריכים להשתמש ב-customerId. כדי לקבל את customerId, משתמשים בפעולה Retrieve a user.

PUT https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath

בקשת JSON

בדוגמה שלמטה, תיאור היחידה הארגונית עודכן: 

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/corp/support/sales_support

{
    "description": "The BEST sales support team"
}

הערות לבקשה לעדכון:

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

תגובת JSON

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

{
    "kind": "directory#orgUnit",
    "name": "sales_support",
    "description": "The BEST sales support team",
    "orgUnitPath": "/corp/support/sales_support",
    "parentOrgUnitPath": "/corp/support"
}

אם משתמש לא הוקצה ליחידה ארגונית ספציפית כשחשבון המשתמש נוצר, החשבון נמצא ביחידה הארגונית ברמה העליונה. היחידה הארגונית של המשתמש קובעת לאילו שירותים של Google Workspace תהיה לו גישה. אם המשתמש מועבר לארגון חדש, הגישה שלו משתנה. מידע נוסף על מבנים ארגוניים זמין במרכז העזרה למנהלים. מידע נוסף על העברת משתמש לארגון אחר זמין במאמר עדכון משתמש.

אחזור יחידה ארגונית

כדי לאחזר יחידה ארגונית, משתמשים בבקשת GET הבאה וכוללים את ההרשאה שמתוארת במאמר הרשאת בקשות. מחרוזת השאילתה orgUnitPath היא הנתיב המלא של היחידה הארגונית הזו. מאפייני הבקשה והתגובה מפורטים בהפניית ה-API:

אם אתם אדמינים ומאחזרים יחידה ארגונית, השתמשו ב-my_customer.

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/orgUnitPath

אם אתם מפיצים ומנסים לאחזר יחידה ארגונית של לקוח שרכשתם עבורו מינוי, אתם צריכים להשתמש ב-customerId. כדי לקבל את customerId, משתמשים בפעולה Retrieve a user.

GET https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath

תגובת JSON

בדוגמה שלמטה, מאחזרים את היחידה הארגונית 'מכירות בשטח'. שימו לב לקידוד ה-HTTP של 'frontline+sales' ב-URI של הבקשה: 

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/corp/sales/frontline+sales

תגובה מוצלחת מחזירה קוד סטטוס HTTP 200. בנוסף לקוד הסטטוס, התשובה מחזירה את ההגדרות של היחידה הארגונית: 

{
    "kind": "directory#orgUnit",
    "name": "frontline sales",
    "description": "The frontline sales team",
    "orgUnitPath": "/corp/sales/frontline sales",
    "parentOrgUnitPath": "/corp/sales"
}

אחזור יחידות ארגוניות

כדי לאחזר את כל היחידות הארגוניות המשנה שמתחת ליחידה ארגונית, את כל יחידות הצאצא שמתחת ליחידה ארגונית או את כל היחידות הארגוניות המשנה בתוספת היחידה הארגונית שצוינה, משתמשים בבקשת GET הבאה וכוללים את ההרשאה שמתוארת במאמר הרשאת בקשות. מאפייני הבקשה והתגובה מפורטים בחומר העזר בנושא API.

אם אתם אדמינים של חשבון ומאחזרים את כל היחידות הארגוניות המשניות, השתמשו ב-my_customer. בדוגמה הזו נעשה שימוש בהחזרות שורה כדי לשפר את הקריאות: 

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer
/orgunits?orgUnitPath=full org unit path&type=all or children or all_including_parent

אם אתם מפיצים ומאחזרים יחידות ארגוניות של לקוח שרכשתם עבורו מוצרים, אתם צריכים להשתמש ב-customerId. כדי לקבל את customerId, משתמשים בפעולה Retrieve a user: 

GET https://admin.googleapis.com/admin/directory/v1/customer/customerId
/orgunits?orgUnitPath=full org unit path&type=all or children or all_including_parent

מחרוזת השאילתה get מחזירה את all היחידות הארגוניות המשניות שמתחת ל-orgUnitPath, את children המיידי של orgUnitPath או את כל היחידות הארגוניות המשניות ואת orgUnitPath שצוין עבור all_including_parent. ערך ברירת המחדל הוא type=children.

תגובת JSON

לדוגמה, הבקשה הזו מחזירה את כל היחידות הארגוניות החל מהיחידה הארגונית /corp: 

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits?orgUnitPath=/corp&type=all

תגובה מוצלחת מחזירה קוד סטטוס HTTP 200. בנוסף לקוד הסטטוס, התשובה מחזירה את היחידות הארגוניות של החשבון: 

{
"kind": "directory#orgUnits",
    "organizationUnits": [
     {
    "kind": "directory#orgUnit",
    "name": "sales",
    "description": "The corporate sales team",
    "orgUnitPath": "/corp/sales",
    "parentOrgUnitPath": "/corp"
     },
     {
    "kind": "directory#orgUnit",
    "name": "frontline sales",
    "description": "The frontline sales team",
    "orgUnitPath": "/corp/sales/frontline sales",
    "parentOrgUnitPath": "/corp/sales"
     },
     {
    "kind": "directory#orgUnit",
    "name": "support",
    "description": "The corporate support team",
    "orgUnitPath": "/corp/support",
    "parentOrgUnitPath": "/corp"
     },
     {
    "kind": "directory#orgUnit",
    "name": "sales_support",
    "description": "The BEST support team",
    "orgUnitPath": "/corp/support/sales_support",
    "parentOrgUnitPath": "/corp/support"
     }
  ]
  }

מחיקה של יחידה ארגונית

כדי למחוק יחידה ארגונית, משתמשים בבקשת DELETE הבאה וכוללים את ההרשאה שמתוארת במאמר איך מאשרים בקשות. כדי לאחזר את customerId, משתמשים בפעולה Retrieve a user. מאפייני הבקשה והתגובה מפורטים בהפניית ה-API:

אם אתם אדמינים בחשבון ומחקתם יחידה ארגונית, אתם יכולים להשתמש בmy_customer. 

DELETE https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/orgUnitPath

אם אתם מפיצים שמוחקים יחידה ארגונית של לקוח שקנה מכם, אתם צריכים להשתמש ב-customerId. כדי לקבל את customerId, משתמשים בפעולה Retrieve a user.

‫
DELETE https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath
 לדוגמה, בקשת DELETE של אדמין של משווק מוחקת את היחידה הארגונית backend_tests: 
DELETE https://admin.googleapis.com/admin/directory/v1/customer/C03az79cb/orgunits/corp/sales/backend_tests

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

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