API de Directory: Unidades organizativas

Administrar unidades organizativas

El árbol organizativo de una cuenta de Google Workspace se compone de unidades organizativas que te permiten administrar a los usuarios en una estructura lógica y jerárquica. Esta funcionalidad es similar a la que se encuentra en la pestaña “Organizaciones y usuarios” de la Consola del administrador. La jerarquía de la unidad organizativa del cliente está limitada a 35 niveles de profundidad. Si desea obtener más información, consulte el Centro de ayuda para administradores.

  • Cada cuenta de Google Workspace solo tiene un árbol de organización. Cuando esta cuenta se configura inicialmente, tiene una unidad organizativa a nivel de la cuenta. Es la organización asociada con el dominio principal. Para obtener más información sobre el dominio principal, consulta la información sobre los límites de la API.
  • El nombre de ruta de una unidad organizativa es único. Es posible que el nombre de la unidad organizativa no sea único dentro de la jerarquía de la organización, pero su nombre sea único entre las unidades organizativas del mismo nivel. Además, el nombre de una unidad organizativa no distingue mayúsculas de minúsculas.
  • Una unidad organizativa hereda políticas de la jerarquía organizativa. Cualquier unidad organizativa puede bloquear esta cadena de herencia parental anulando la política heredada. La unidad organizativa más cercana determina la prioridad de una política sobre otra. Esto significa que las políticas de una unidad organizativa inferior pueden tener prioridad sobre las de las unidades parentales superiores. El parámetro de configuración blockInheritance permite bloquear la herencia de parámetros de configuración a una unidad organizativa y su suborganización. blockInheritance ya no está disponible. Ya no se admite configurarlo como "true" y puede tener consecuencias no deseadas. Para obtener más información sobre la herencia y los usuarios en una estructura de organización, consulta el Centro de ayuda de administración.
  • Una unidad organizativa se puede mover hacia arriba o hacia abajo en un árbol jerárquico. Además, los usuarios asociados de la organización se pueden mover de forma individual o por lotes cuando se propaga una organización nueva o se traslada un subconjunto de usuarios de una unidad organizativa a otra.
  • Los datos que se mantienen en las propiedades de las unidades organizativas pueden cambiar constantemente. Cuando se realiza una solicitud, se garantiza que las propiedades que se muestran para una entidad sean coherentes en el momento en que se recuperó la entidad.Es decir, no verás actualizaciones "parciales". Si una operación de recuperación muestra más de una entidad, no hay garantía de coherencia entre las entidades.Esto es especialmente cierto cuando una respuesta abarca varias páginas en paginación.

Crea una unidad organizativa

Para crear una unidad organizativa, usa la siguiente solicitud POST y agrega la autorización que se describe en Autoriza solicitudes.

Si eres administrador y estás creando una unidad organizativa, usa my_customer.

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

Si eres un revendedor que crea una unidad organizativa para un cliente de reventa, usa customerId. Para recuperar el customerId, usa la operación Recuperar un usuario.

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

A fin de comprender la estructura organizativa de su cuenta, consulte el Centro de ayuda para administradores. Para ver las propiedades de solicitud y respuesta, consulta la referencia de la API.

Solicitud JSON

El siguiente ejemplo de revendedor de JSON muestra un cuerpo de solicitud de muestra que crea la unidad organizativa sales_support. name y parentOrgUnitPath son obligatorios:

POST https://admin.googleapis.com/admin/directory/v1/customer/C03az79cb/orgunits
{
    "name": "sales_support",
    "description": "The sales support team",
    "parentOrgUnitPath": "/corp/support",
    "blockInheritance": false
}

Respuesta JSON

Si la respuesta es correcta, se mostrará un código de estado HTTP 201. Junto con el código de estado, la respuesta muestra las propiedades del nuevo grupo:

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

Actualizar una unidad organizativa

Para actualizar una unidad organizativa, usa la siguiente solicitud PUT y, además, incluye la autorización que se describe en Autoriza solicitudes. Para ver las propiedades de solicitud y respuesta, consulta la Referencia de la API:

Si eres administrador y estás actualizando una unidad organizativa, usa my_customer.

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

Si eres revendedor y estás actualizando una unidad organizativa para un cliente de reventa, usa customerId. Para obtener el customerId, usa la operación Recuperar un usuario.

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

Solicitud JSON

En el siguiente ejemplo, se actualizó la descripción de la unidad organizativa:

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/corp/support/sales_support
{
    "description": "The BEST sales support team"
}

Notas sobre una solicitud de actualización:

  • Solo debes enviar la información actualizada en tu solicitud. No es necesario que ingreses todas las propiedades del grupo en la solicitud.
  • Si un usuario no estaba asignado a una unidad organizativa específica cuando se creó la cuenta de usuario, la cuenta estará en la unidad organizativa de nivel superior.
  • Para mover una unidad organizativa a otra parte de la estructura organizativa de tu cuenta, debes configurar la propiedad parentOrgUnitPath en la solicitud. Es importante tener en cuenta que mover una unidad organizativa puede cambiar los servicios y la configuración de los usuarios de la unidad organizativa que se está moviendo.

Respuesta JSON

Si la respuesta es correcta, se mostrará un código de estado HTTP 201. Junto con el código de estado, la respuesta muestra las propiedades de la unidad organizativa actualizada.

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

Si un usuario no estaba asignado a una unidad organizativa específica cuando se creó la cuenta de usuario, la cuenta estará en la unidad organizativa de nivel superior. La unidad organizativa de un usuario determina a qué servicios de Google Workspace tiene acceso el usuario. Si el usuario se traslada a una organización nueva, su acceso cambia. Si deseas obtener más información sobre las estructuras de las organizaciones, consulta el Centro de ayuda para la administración. Si quieres obtener más información para mover un usuario a otra organización, consulta Actualiza un usuario.

Recupera una unidad organizativa

Para recuperar una unidad organizativa, usa la siguiente solicitud GET e incluye la autorización que se describe en Autoriza solicitudes. La cadena de consulta orgUnitPath es la ruta completa para esta unidad organizativa. Para ver las propiedades de solicitud y respuesta, consulta la Referencia de la API:

Si eres administrador y recuperas una unidad organizativa, usa my_customer.

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

Si eres revendedor y quieres recuperar una unidad organizativa de un cliente de reventa, usa el customerId. Para obtener el customerId, usa la operación Recuperar un usuario.

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

Respuesta JSON

En el siguiente ejemplo, se recupera la unidad organizativa “ventas de primera línea”. Observa la codificación HTTP “frontline+sales” en el URI de la solicitud:

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

Si la respuesta es correcta, se mostrará un código de estado HTTP 200. Junto con el código de estado, la respuesta muestra la configuración de la unidad organizativa:

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

Recuperar las unidades organizativas

Para recuperar todas las subunidades organizativas de una unidad organizativa, las secundarias inmediatas de una unidad organizativa o todas las subunidades organizativas más la unidad organizativa especificada, usa la siguiente solicitud GET y, luego, incluye la autorización que se describe en Autoriza solicitudes. Para ver las propiedades de solicitud y respuesta, consulta la referencia de la API.

Si eres administrador de cuentas y recuperas todas las unidades organizativas, usa my_customer. Para facilitar la lectura, en este ejemplo se usan los resultados de línea:

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

Si eres revendedor y quieres recuperar unidades organizativas para un cliente de reventa, usa el customerId. Para obtener el customerId, usa la operación Recuperar un usuario:

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

La cadena de consulta get muestra all unidades organizativas secundarias en orgUnitPath, el children inmediato de orgUnitPath o todas las unidades organizativas secundarias y la orgUnitPath especificada para all_including_parent. El valor predeterminado es type=children.

Respuesta JSON

Por ejemplo, esta solicitud muestra todas las unidades organizativas que comienzan en la unidad organizativa /corp:

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

Si la respuesta es correcta, se mostrará un código de estado HTTP 200. Junto con el código de estado, la respuesta muestra las unidades organizativas de la cuenta:

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

Borrar una unidad organizativa

Para borrar una unidad organizativa, usa la siguiente solicitud DELETE y, además, incluye la autorización que se describe en Autoriza solicitudes. Para recuperar el customerId, usa la operación Recuperar un usuario. Para ver las propiedades de solicitud y respuesta, consulta la Referencia de la API:

Si eres administrador de la cuenta y borras una unidad organizativa, usa my_customer.

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

Si eres revendedor y borras una unidad organizativa para un cliente de reventa, usa el customerId. Para obtener el customerId, usa la operación Recuperar un usuario.

DELETE https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath
Por ejemplo, la solicitud DELETE del administrador del revendedor borra la unidad organizativa “backend_tests”:
DELETE https://admin.googleapis.com/admin/directory/v1/customer/C03az79cb/orgunits/corp/sales/backend_tests

Si la respuesta es correcta, se mostrará un código de estado HTTP 200.

Solo puedes borrar unidades organizativas que no tengan unidades organizativas secundarias ni usuarios asignados. Antes de borrarla, debes reasignar los usuarios a otras unidades organizativas y quitar las unidades secundarias.