API Directory: unidades organizacionais

Gerenciar unidades organizacionais

A árvore organizacional de uma conta do Google Workspace é composta por unidades organizacionais que permitem gerenciar os usuários em uma estrutura lógica e hierárquica. Essa funcionalidade é semelhante à encontrada na guia "Organizações e usuários" do Google Admin Console. A hierarquia da unidade organizacional do cliente é limitada a 35 níveis de profundidade. Para mais informações, consulte a Central de Ajuda do administrador.

Há apenas uma árvore organizacional para uma conta do Google Workspace. Quando essa conta é configurada inicialmente, ela tem uma unidade organizacional no nível da conta. É a organização associada ao domínio principal. Para mais informações sobre o domínio principal, consulte as informações sobre limites da API.
O nome do caminho de uma unidade organizacional é exclusivo. O nome da unidade organizacional pode não ser exclusivo na hierarquia da organização, mas é exclusivo entre as unidades organizacionais semelhantes. O nome de uma unidade organizacional não diferencia maiúsculas de minúsculas.
Uma unidade organizacional herda políticas da hierarquia organizacional. Qualquer unidade organizacional pode bloquear essa cadeia de herança parental substituindo a política herdada. A precedência de uma política sobre outra é determinada pela unidade organizacional mais próxima. Isso significa que as políticas de uma unidade organizacional de nível inferior podem ter precedência sobre as políticas das unidades parentais de nível superior. Para mais informações sobre herança e usuários em uma estrutura organizacional, consulte a Central de Ajuda para administradores.
Uma unidade organizacional pode ser movida para cima ou para baixo em uma árvore hierárquica. Além disso, os usuários associados à organização podem ser movidos individualmente ou em lote ao preencher uma nova organização ou mover um subconjunto de usuários de uma unidade organizacional para outra.
Os dados mantidos nas propriedades da unidade organizacional podem mudar constantemente. Ao fazer uma solicitação, as propriedades retornadas para uma entidade têm consistência garantida no momento em que a entidade foi recuperada.Ou seja, você não vai ver atualizações "parciais". Se uma operação de recuperação retornar mais de uma entidade, não haverá garantia de consistência entre elas, principalmente quando uma resposta abrange várias páginas na paginação.

Criar uma unidade organizacional

Para criar uma unidade organizacional, use a seguinte solicitação POST e inclua a autorização descrita em Autorizar solicitações.

Se você for um administrador criando uma unidade organizacional, use my_customer.

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

Se você for um revendedor criando uma unidade organizacional para um cliente revendido, use customerId. Para recuperar o customerId, use a operação Recuperar um usuário.

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

Para entender a estrutura organizacional da sua conta, consulte a Central de Ajuda para administradores. Para propriedades de solicitação e resposta, consulte a referência da API.

Solicitação JSON

O exemplo de revendedor JSON a seguir mostra um corpo de solicitação de amostra que cria a unidade organizacional sales_support. Os campos name e parentOrgUnitPath são obrigatórios:

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

{
    "name": "sales_support",
    "description": "The sales support team",
    "parentOrgUnitPath": "/corp/support",
}

Resposta JSON

Uma resposta bem-sucedida retorna um código de status HTTP 201. Junto com o código de status, a resposta retorna as propriedades do novo grupo:

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

Atualizar uma unidade organizacional

Para atualizar uma unidade organizacional, use a seguinte solicitação PUT e inclua a autorização descrita em Autorizar solicitações. Para as propriedades de solicitação e resposta, consulte a referência da API:

Se você for um administrador atualizando uma unidade organizacional, use my_customer.

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

Se você for um revendedor atualizando uma unidade organizacional para um cliente revendido, use customerId. Para receber o customerId, use a operação Recuperar um usuário.

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

Solicitação JSON

No exemplo abaixo, a descrição da unidade organizacional foi atualizada:

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/corp/support/sales_support

{
    "description": "The BEST sales support team"
}

Observações para um pedido de atualização:

Basta enviar as informações atualizadas na sua solicitação. Não é necessário inserir todas as propriedades do grupo na solicitação.
Se um usuário não foi atribuído a uma unidade organizacional específica quando a conta foi criada, ela fica na unidade organizacional de nível superior.
Para mover uma unidade organizacional para outra parte da estrutura da conta, defina a propriedade parentOrgUnitPath na solicitação. É importante observar que a movimentação de uma unidade organizacional pode mudar os serviços e as configurações dos usuários nela.

Resposta JSON

Uma resposta bem-sucedida retorna um código de status HTTP 201. Além do código de status, a resposta retorna as propriedades da unidade organizacional atualizada.

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

Se um usuário não foi atribuído a uma unidade organizacional específica quando a conta foi criada, ela fica na unidade organizacional de nível superior. A unidade organizacional de um usuário determina a quais serviços do Google Workspace ele tem acesso. Se o usuário for movido para uma nova organização, o acesso dele vai mudar. Para mais informações sobre estruturas organizacionais, consulte a Central de Ajuda para administradores. Para mais informações sobre como mover um usuário para outra organização, consulte Atualizar um usuário.

Recuperar uma unidade organizacional

Para recuperar uma unidade organizacional, use a seguinte solicitação GET e inclua a autorização descrita em Autorizar solicitações. A string de consulta orgUnitPath é o caminho completo para essa unidade organizacional. Para as propriedades de solicitação e resposta, consulte a referência da API:

Se você for um administrador recuperando uma unidade organizacional, use my_customer.

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

Se você for um revendedor recuperando uma unidade organizacional para um cliente revendido, use customerId. Para conseguir o customerId, use a operação Recuperar um usuário.

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

Resposta JSON

No exemplo abaixo, a unidade organizacional "vendas na linha de frente" é recuperada. Observe a codificação HTTP "frontline+sales" no URI da solicitação:

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

Uma resposta bem-sucedida retorna um código de status HTTP 200. Além do código de status, a resposta retorna as configurações da unidade organizacional:

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

Recuperar unidades organizacionais

Para recuperar todas as subunidades organizacionais de uma unidade organizacional, os filhos imediatos de uma unidade organizacional ou todas as subunidades organizacionais mais a unidade organizacional especificada, use a seguinte solicitação GET e inclua a autorização descrita em Autorizar solicitações. Para as propriedades de solicitação e resposta, consulte a referência da API.

Se você for um administrador de contas que está recuperando todas as subunidades organizacionais, use my_customer. Para facilitar a leitura, este exemplo usa retornos de linha:

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

Se você for um revendedor que está recuperando unidades organizacionais para um cliente revendido, use customerId. Para conseguir o customerId, use a operação Recuperar um usuário:

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

A string de consulta get retorna all subunidades organizacionais em orgUnitPath, o children imediato de orgUnitPath ou todas as subunidades organizacionais e o orgUnitPath especificado para all_including_parent. O padrão é type=children.

Resposta JSON

Por exemplo, esta solicitação retorna todas as unidades organizacionais a partir da /corp:

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

Uma resposta bem-sucedida retorna um código de status HTTP 200. Junto com o código de status, a resposta retorna as unidades organizacionais da conta:

{
"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"
     }
  ]
  }

Excluir uma unidade organizacional

Para excluir uma unidade organizacional, use a seguinte solicitação DELETE e inclua a autorização descrita em Autorizar solicitações. Para recuperar o customerId, use a operação Recuperar um usuário. Para as propriedades de solicitação e resposta, consulte a referência da API:

Se você for um administrador de conta excluindo uma unidade organizacional, use my_customer.

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

Se você for um revendedor e estiver excluindo uma unidade organizacional de um cliente revendido, use customerId. Para conseguir o customerId, use a operação Recuperar um usuário.

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

Por exemplo, a solicitação DELETE deste administrador revendedor exclui a unidade organizacional "backend_tests":

DELETE https://admin.googleapis.com/admin/directory/v1/customer/C03az79cb/orgunits/corp/sales/backend_tests

Uma resposta bem-sucedida retorna um código de status HTTP 200.

Só é possível excluir unidades organizacionais que não têm unidades filhas ou usuários atribuídos a elas. Antes de excluir, reatribua os usuários a outras unidades organizacionais e remova as unidades organizacionais filhas.

API Directory: unidades organizacionais Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Gerenciar unidades organizacionais

Criar uma unidade organizacional

Solicitação JSON

Resposta JSON

Atualizar uma unidade organizacional

Solicitação JSON

Resposta JSON

Recuperar uma unidade organizacional

Resposta JSON

Recuperar unidades organizacionais

Resposta JSON

Excluir uma unidade organizacional

API Directory: unidades organizacionais