Directory API：機構單位

管理機構單位

Google Workspace 帳戶的機構樹狀結構是由機構單位組成，可讓您以邏輯層級結構管理使用者。這項功能類似於管理控制台的「組織和使用者」分頁。客戶的機構單位階層深度上限為 35 層。詳情請參閱管理員說明中心。

  • Google Workspace 帳戶只有一個機構樹狀結構。這個帳戶在初始設定時，會在帳戶層級設有機構單位。這是與主網域相關聯的機構。如要進一步瞭解主要網域，請參閱 API 限制資訊。
  • 機構單位的路徑名稱是唯一的。機構單位的名稱在機構階層中可能不是唯一，但在同層機構單位中是唯一的。機構單位名稱不區分大小寫。
  • 機構單位會沿用機構階層的政策。任何機構單位都可以覆寫沿用政策，阻斷這條父項繼承鏈結。政策的優先順序取決於最接近的機構單位。也就是說，較低層級機構單位的政策會優先於較高層級上層單位的政策。如要進一步瞭解機構結構中的繼承和使用者，請參閱管理說明中心。
  • 機構單位可在階層樹狀圖中向上或向下移動。此外，在填入新機構或將部分使用者從一個機構單位移至另一個機構單位時，您可以個別移動機構的相關使用者，也可以一次移動多位使用者。
  • 機構單位資源中儲存的資料可能會不斷變更。提出要求時，系統會保證為實體傳回的屬性在擷取實體時保持一致，也就是不會顯示「部分」更新。如果擷取作業傳回多個實體，則無法保證實體之間的一致性。這在回應跨越分頁中的多個頁面時尤其明顯。

建立機構單位

如要建立機構單位，請使用下列 POST 要求，並附上「授權要求」一節中所述的授權。

如果您是管理員，並要建立機構單位，請使用 my_customer。

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

如果您是經銷商，並要為轉售客戶建立機構單位，請使用 customerId。如要擷取 customerId，請使用「擷取使用者」作業。

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，請使用「擷取使用者」作業。

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 回應

在下方範例中，系統會擷取「前線銷售」機構單位。請注意要求 URI 中的「frontline+sales」HTTP 編碼：

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 查詢字串會傳回 orgUnitPath 下方的 all 子機構單位、orgUnitPath 的直接 children，或是 all_including_parent 的所有子機構單位和指定 orgUnitPath。預設為 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 狀態碼。

您只能刪除沒有任何子機構單位或指派使用者的機構單位。您必須將使用者重新指派給其他機構單位，並移除所有子機構單位，才能刪除機構單位。