Se usó la API de Cloud Translation para traducir esta página.

API de Directory: Unidades organizativas

Administra unidades organizativas

El árbol organizativo de una cuenta de Google Workspace se compone de unidades organizativas que te permiten administrar a tus usuarios en una estructura lógica y jerárquica. Esta función es similar a la que se encuentra en la pestaña "Organizaciones y usuarios" de la Consola del administrador. La jerarquía de unidades organizativas del cliente se limita a 35 niveles de profundidad. Para obtener más información, consulta el Centro de ayuda para administradores.

Solo hay un árbol de organización para una cuenta de Google Workspace. Cuando se configura esta cuenta inicialmente, tiene una unidad organizativa a nivel de la cuenta. Esta 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.
La ruta de acceso de una unidad organizativa es única. Es posible que el nombre de la unidad organizativa no sea único dentro de la jerarquía de la organización, pero sí lo es entre sus unidades organizativas hermanas. 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 anular la política heredada para bloquear esta cadena de herencia parental. La prioridad de una política sobre otra se determina según la unidad organizativa más cercana. Esto significa que las políticas de una unidad organizativa inferior pueden tener prioridad sobre las de las unidades parentales de nivel superior. Para obtener más información sobre la herencia y los usuarios en la estructura de una 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 mueve un subconjunto de usuarios de una unidad organizativa a otra.
Los datos que se conservan en las propiedades de las unidades organizativas pueden cambiar constantemente. Cuando realizas 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 la paginación.

Crea una unidad organizativa

Para crear una unidad organizativa, usa la siguiente solicitud POST y, luego, incluye la autorización que se describe en Cómo autorizar solicitudes.

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

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

Si eres un distribuidor que crea una unidad organizativa para un cliente al que le vendes productos, usa customerId. Para recuperar el customerId, usa la operación Recuperar un usuario.

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

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

Solicitud JSON

En el siguiente ejemplo de revendedor JSON, se 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",
}

Respuesta JSON

Una respuesta correcta muestra un código de estado HTTP 201. Junto con el código de estado, la respuesta devuelve las propiedades del grupo nuevo:

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

Cómo actualizar una unidad organizativa

Para actualizar una unidad organizativa, usa la siguiente solicitud PUT e incluye la autorización que se describe en Autorizar solicitudes. Para conocer las propiedades de solicitud y respuesta, consulta la referencia de la API:

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

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

Si eres un distribuidor que actualiza una unidad organizativa para un cliente revendido, 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 para 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, esta se encuentra en la unidad organizativa de nivel superior.
Para mover una unidad organizativa a otra parte de la estructura organizativa de tu cuenta, configura 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 que se mueve.

Respuesta JSON

Una respuesta correcta muestra un código de estado HTTP 201. Junto con el código de estado, la respuesta devuelve 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"
}

Si un usuario no estaba asignado a una unidad organizativa específica cuando se creó la cuenta de usuario, esta se encuentra 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 cambiará. Para obtener más información sobre las estructuras de organización, consulta el Centro de ayuda de administración. Para obtener más información sobre cómo trasladar a un usuario a otra organización, consulta Cómo actualizar un usuario.

Cómo recuperar una unidad organizativa

Para recuperar una unidad organizativa, usa la siguiente solicitud GET y, luego, incluye la autorización que se describe en Autorizar solicitudes. La cadena de consulta orgUnitPath es la ruta de acceso completa de esta unidad organizativa. Para conocer 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 recuperas una unidad organizativa para un cliente de reventa, usa 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 directas". 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

Una respuesta correcta muestra un código de estado HTTP 200. Junto con el código de estado, la respuesta devuelve 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"
}

Recuperar unidades organizativas

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

Si eres administrador de la cuenta y recuperas todas las unidades organizativas secundarias, usa my_customer. Para facilitar la lectura, este ejemplo usa saltos 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 recuperas unidades organizativas para un cliente de reventa, usa customerId. Para obtener el customerId, usa la operación 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

La cadena de consulta get muestra all unidades organizativas secundarias en orgUnitPath, el children inmediato de orgUnitPath, o bien 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 devuelve 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"
     },
     {
    "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"
     }
  ]
  }

Cómo borrar una unidad organizativa

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

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

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

Si eres un distribuidor que borra una unidad organizativa de un cliente revendido, usa 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 de este administrador de 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 las unidades organizativas que no tengan unidades organizativas secundarias ni usuarios asignados. Debes reasignar los usuarios a otras unidades organizativas y quitar las unidades organizativas secundarias antes de borrarlas.