Esta página foi traduzida pela API Cloud Translation.

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. Esse recurso é semelhante à funcionalidade encontrada na guia "Organizações e usuários" do 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 para admins.

Há apenas uma árvore da organização para uma conta do Google Workspace. Quando a conta é configurada inicialmente, ela tem uma unidade organizacional no nível da conta. Esta é a organização associada ao domínio principal. Para mais informações sobre o domínio principal, consulte as informações sobre os limites da API.
O nome do caminho de uma unidade organizacional é exclusivo. O nome da unidade organizacional pode não ser exclusivo na hierarquia organizacional, mas é exclusivo entre as unidades organizacionais irmãs. E o nome de uma unidade organizacional não diferencia maiúsculas de minúsculas.
Uma unidade organizacional herda as 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 em relação a outra é determinada pela unidade organizacional mais próxima. Ou seja, as políticas de uma unidade organizacional com nível inferior podem ter precedência sobre as políticas de unidades parentais superiores. Com a configuração blockInheritance, é possível bloquear a herança da configuração para uma unidade organizacional e a suborganização. O uso de blockInheritance foi descontinuado. Não é mais possível definir esse valor como "true" e ele pode ter consequências não intencionais. Para mais informações sobre herança e usuários em uma estrutura organizacional, consulte a Central de Ajuda para administração.
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 a garantia de serem consistentes no momento em que a entidade foi recuperada.Ou seja, você não verá atualizações "parciais". Se uma operação de recuperação retornar mais de uma entidade, não haverá garantia de consistência entre as entidades.Isso é especialmente verdadeiro quando uma resposta abrange várias páginas em 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 e estiver criando uma unidade organizacional, use o my_customer.

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

Se você é um revendedor e está criando uma unidade organizacional para um cliente de revenda, use o 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 admins. 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 exemplo de corpo de solicitação que cria a unidade organizacional sales_support. 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",
    "blockInheritance": false
}

Resposta JSON

Se a resposta for bem-sucedida, o código de status HTTP 201 será retornado. Juntamente com o código de status, a resposta retorna as propriedades para o novo grupo:

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

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 que está atualizando uma unidade organizacional, use my_customer.

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

Se você é um revendedor e está atualizando a unidade organizacional de um cliente de revenda, use o customerId. Para acessar 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 uma solicitação de atualização:

Você só precisa enviar as informações atualizadas na sua solicitação. Você não precisa inserir todas as propriedades do grupo na solicitação.
Se um usuário não tiver sido atribuído a uma unidade organizacional específica quando a conta de usuário foi criada, ela estará na unidade organizacional de nível superior.
Você pode mover uma unidade organizacional para outra parte da estrutura organizacional da sua conta configurando a propriedade parentOrgUnitPath na solicitação. A migração de uma unidade organizacional pode alterar os serviços e as configurações dos usuários dela.

Resposta JSON

Se a resposta for bem-sucedida, o código de status HTTP 201 será retornado. Junto com o 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",
    "blockInheritance": false
}

Se um usuário não tiver sido atribuído a uma unidade organizacional específica quando a conta de usuário foi criada, ela estará 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 administração. Confira como mover um usuário para outra organização em Atualizar um usuário.

Recuperar uma unidade organizacional

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

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

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

Se você é um revendedor que está recuperando uma unidade organizacional para um cliente de revenda, use o customerId. Para acessar 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 de atendimento" é recuperada. Observe a codificação HTTP 'frontline+vendas' no URI da solicitação:

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

Se a resposta for bem-sucedida, o código de status HTTP 200 será retornado. Com o 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",
    "blockInheritance": false
}

Recuperar unidades organizacionais

Para recuperar todas as subunidades organizacionais em uma unidade organizacional, as filhas imediatas em uma unidade organizacional ou todas as subunidades organizacionais e a unidade organizacional especificada, use a solicitação GET a seguir 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 conta e recupera 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ê é um revendedor que recupera unidades organizacionais de um cliente de revenda, use o customerId. Para acessar 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, a children imediata 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 que começam na unidade organizacional /corp:

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

Se a resposta for bem-sucedida, o código de status HTTP 200 será retornado. 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",
    "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
     }
  ]
  }

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ê é o administrador da conta e está excluindo uma unidade organizacional, use o my_customer.

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

Se você é revendedor e está excluindo uma unidade organizacional de um cliente de revenda, use o customerId. Para acessar 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 do administrador deste revendedor exclui a unidade organizacional "backend_tests":

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

Se a resposta for bem-sucedida, o código de status HTTP 200 será retornado.

Só é possível excluir unidades organizacionais que não têm unidades organizacionais filhas nem usuários atribuídos a elas. Você precisa reatribuir os usuários a outras unidades organizacionais e remover as unidades organizacionais filhas antes da exclusão.