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 de Google. La jerarquía de la unidad organizativa 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 inicialmente esta cuenta, tiene una unidad organizativa a nivel de la cuenta. Es la organización asociada al 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. El nombre de la unidad organizativa puede no ser único dentro de la jerarquía de la organización, pero sí entre sus unidades organizativas secundarias. 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 precedencia 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 políticas de las unidades organizativas superiores. Para obtener más información sobre la herencia y los usuarios en una estructura de organización, consulta el Centro de ayuda para administradores.
  • 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 en lote cuando se completa 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 devuelve 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 Autoriza 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 revendedor que crea una unidad organizativa para un cliente revendido, 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 de organización de tu cuenta, consulta 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 en formato JSON, se muestra un cuerpo de solicitud de muestra que crea la unidad organizativa sales_support. Se requieren name y parentOrgUnitPath: 

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 devuelve 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"
  }

Actualiza una unidad organizativa

Para actualizar una unidad organizativa, utiliza la siguiente solicitud PUT e incluye la autorización descrita 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 no se asignó un usuario a una unidad organizativa específica cuando se creó la cuenta de usuario, la cuenta se encuentra en la unidad organizativa de nivel superior.
  • Puedes mover una unidad organizativa a otra parte de la estructura de la organización de tu cuenta configurando 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 mueve.

Respuesta JSON

Una respuesta correcta devuelve 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 no se asignó un usuario a una unidad organizativa específica cuando se creó la cuenta de usuario, la cuenta se encuentra en la unidad organizativa de nivel superior. La unidad organizativa de un usuario determina a qué servicios de Google Workspace tiene acceso. Si se muda al usuario a una organización nueva, cambiará su acceso. Para obtener más información sobre las estructuras organizativas, consulta el Centro de ayuda para administradores. Para obtener más información sobre cómo trasladar a un usuario a otra organización, consulta Actualiza un usuario.

Recupera una unidad organizativa

Para recuperar una unidad organizativa, utiliza la siguiente solicitud GET e incluye la autorización descrita 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 un distribuidor que recupera una unidad organizativa para un cliente revendido, 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 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

Una respuesta correcta devuelve 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"
}

Recupera unidades organizativas

Para recuperar todas las unidades organizativas secundarias de una unidad organizativa, las unidades organizativas secundarias inmediatas de una unidad organizativa o todas las unidades organizativas secundarias más la unidad organizativa especificada, usa la siguiente solicitud GET 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 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 un distribuidor que recupera unidades organizativas para un cliente revendido, 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=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 subunidades organizativas y el orgUnitPath especificado para all_including_parent. El valor predeterminado es type=children.

Respuesta JSON

Por ejemplo, esta solicitud devuelve 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

Una respuesta correcta devuelve 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"
     }
  ]
  }

Borra una unidad organizativa

Para borrar una unidad organizativa, usa la siguiente solicitud DELETE e incluye la autorización descrita 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 la API:

Si eres administrador de la cuenta y borras una unidad organizacional, 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 para 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

Una respuesta correcta devuelve un código de estado HTTP 200.

Solo puedes borrar las 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 organizativas secundarias.