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 tus usuarios en una estructura lógica y jerárquica. Esta función es similar a la que se encuentra en la sección “Organizaciones y usuarios” de la Consola del administrador . La jerarquía de las unidades organizativas del cliente tiene un límite de 35 niveles de profundidad. Si desea obtener más información, consulte el Centro de ayuda para administradores.

  • Las cuentas de Google Workspace tienen un solo árbol de organización. Cuando esta cuenta se configura 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.
  • 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 sí entre sus 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 organización puede bloquear esta cadena de herencia parental anulando la política heredada. El la prioridad de una política sobre otra está determinada por la unidad organizativa más cercana. Esto significa que las políticas de una unidad organizativa inferior pueden tener prioridad sobre las de la más unidades parentales. 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 establecerlo en "true" y puede tener consecuencias no deseadas. Para para obtener más información sobre la herencia y los usuarios en una estructura organizativa, consulta el Centro de ayuda de la administración.
  • Una unidad organizativa puede moverse hacia arriba o hacia abajo en un árbol jerárquico. Además, los usuarios asociados a 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 conservan 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 serán coherentes en el momento en que se recuperó la entidad.Es decir, no verás “parcial” actualizaciones. 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 e incluye la autorización que se describe en Autorizar 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 revendedor y estás creando una unidad organizativa para un cliente de reventa, usa customerId. Para recuperar el customerId, usa la operación Recupera 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 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 e incluye la autorización que se describe en Autorizar solicitudes. Para conocer las propiedades de solicitud y respuesta, consulta la Referencia de 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 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 migrar una unidad organizativa puede cambiar los servicios y la configuración de los usuarios incluidos en ella.

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, 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. 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 Autorizar solicitudes. La cadena de consulta orgUnitPath es la ruta completa de esta unidad organizativa. Para conocer las propiedades de solicitud y respuesta, consulta la Referencia de API:

Si eres administrador y estás recuperando 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 Retrieve a user.

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

Respuesta JSON

En el siguiente ejemplo, las "ventas de primera línea" unidad organizativa. Ten en cuenta la «primera línea+ventas» Codificación HTTP 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 unidades organizativas

Para recuperar todas las subunidades organizativas de una unidad organizativa, los elementos secundarios inmediatos de una unidad organizativa o todas las subunidades organizativas más la unidad organizativa especificada, usa la siguiente solicitud GET y agrega la autorización que se describe en Autorizar solicitudes. Para ver las propiedades de solicitud y respuesta, consulta la Referencia de API.

Si eres un administrador de cuenta que recupera todas las unidades organizativas secundarias, utiliza my_customer. Para facilitar la lectura, en este ejemplo se usan resultados de líneas: 

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 las subunidades organizativas all en orgUnitPath, el children inmediato de orgUnitPath, o todas las unidades suborganizacionales 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 a partir de 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
     }
  ]
  }

Borra 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 Recupera 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 revendedor y borras la unidad organizativa de un cliente de reventa, usa customerId. Para obtener el customerId, usa la operación Retrieve a user. 

DELETE https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath
 Por ejemplo, la solicitud DELETE de este administrador revendedor borra las pruebas “backend_tests”. unidad organizativa: 
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 usuarios a otras unidades organizativas y quitar las unidades organizativas secundarias antes de borrarlas.