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

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

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

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

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

כדי ליצור יחידה ארגונית, משתמשים בבקשת 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, משתמשים בפעולה אחזור משתמש.

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, משתמשים בפעולה אחזור משתמש: 

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, משתמשים בפעולה אחזור משתמש. למאפיינים של הבקשה והתגובה, עיינו בהפניה ל-API:

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

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

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

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.

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