API Directory: unidades organizacionais

Gerenciar unidades organizacionais

A árvore organizacional de uma conta do Google Workspace é composta por unidades que permitem gerenciar os usuários de acordo com uma estrutura lógica e hierárquica. Isso é semelhante à funcionalidade encontrada na página "Organizações e usuários" do Admin Console . A hierarquia de unidades organizacionais 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 esta 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 da organização, mas o nome é 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 políticas da hierarquia organizacional. Qualquer organização pode bloquear a cadeia de herança parental substituindo a política herdada. A a precedência de uma política em relação a outra é determinada pela unidade organizacional mais próxima. Isso significa que as políticas de uma unidade organizacional inferior podem ter precedência sobre as políticas da unidades parentais mais altas. A configuração blockInheritance permite bloquear a herança da configuração para uma unidade organizacional e sua suborganização. O uso de blockInheritance foi descontinuado. A definição dele como "true" não é mais compatível e pode ter consequências não intencionais. Para mais informações sobre heranças e usuários em uma estrutura organizacional, consulte a Central de Ajuda de 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á "parcial" atualizações. Se uma operação de recuperação retornar mais de uma entidade, não há garantia de consistência entre as entidades.Isso é especialmente verdadeiro quando uma resposta abrange várias páginas na paginação.

Criar uma unidade organizacional

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

Se você é um administrador que está criando uma unidade organizacional, use my_customer.

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

Se você é um revendedor que está criando uma unidade organizacional para um cliente de revenda, 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 do administrador. 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. O name e o 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

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",
    "blockInheritance": false
  }

Atualizar uma unidade organizacional

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

Se você é 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 que está atualizando a unidade organizacional de um cliente de revenda, use customerId. Para conseguir 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. Não é necessário 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 for criada, ela estará na unidade organizacional de nível superior.
  • Para mover uma unidade organizacional para outra parte da estrutura organizacional da sua conta, defina a propriedade parentOrgUnitPath na solicitação. É importante observar que mover uma unidade organizacional pode alterar os serviços e as configurações dos usuários nessa unidade.

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 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 for 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 será alterado. Para mais informações sobre estruturas organizacionais, consulte a Central de Ajuda de administração. 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 solicitação GET a seguir e inclua a autorização descrita em Autorizar solicitações. A string de consulta orgUnitPath é o caminho completo desta unidade organizacional. Para obter 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 de revenda, use o customerId. Para receber 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, "vendas na linha de frente" unidade organizacional é recuperada. Observe as colunas "frontline+vendas" Codificação HTTP 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. Junto 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 de uma unidade organizacional, as filhas imediatas de 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 obter as propriedades de solicitação e resposta, consulte a Referência da API.

Se você for um administrador de conta 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 recuperando unidades organizacionais 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=full org unit path&type=all or children or all_including_parent

A string de consulta get retorna all subunidades organizacionais na 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 começando na unidade organizacional /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",
    "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 solicitação DELETE a seguir e inclua a autorização descrita em Autorizar solicitações. Para recuperar o customerId, use a operação Recuperar um usuário. Para obter as propriedades de solicitação e resposta, consulte a Referência da API:

Se você é um administrador de conta e está 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 a unidade organizacional de um cliente de revenda, use o customerId. Para receber 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 do revendedor exclui o elemento "backend_tests" unidade organizacional:
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 tenham unidades organizacionais filhas ou usuários atribuídos a elas. É necessário reatribuir os usuários a outras unidades organizacionais e remover as unidades filhas antes da exclusão.