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 de organização 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 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 é 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 unidade organizacional pode bloquear essa cadeia de herança de pais substituindo a política herdada. 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 de nível inferior podem ter precedência sobre as políticas das unidades mãe de nível superior. Para mais informações sobre herança e usuários em uma estrutura de organização, 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 consistência no momento em que a entidade foi recuperada.Ou seja, você não vai encontrar 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 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ê for um administrador 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 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 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 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",
}

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 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 solicitação PUT abaixo 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ê é 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 uma unidade organizacional para um cliente revendido, 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 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, a conta está 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 a movimentação de uma unidade organizacional pode mudar os serviços e as configurações dos usuários na unidade organizacional que está sendo movida.

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, a conta está na unidade organizacional de nível superior. A unidade organizacional de um usuário determina 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 de administração. Para mais informações sobre como mover um usuário para uma organização diferente, consulte Atualizar um usuário.

Extrair 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 dessa unidade organizacional. Para as propriedades de solicitação e resposta, consulte a Referência da API:

Se você for um administrador que está 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 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 de primeira linha" é 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"
}

Extrair unidades organizacionais

Para recuperar todas as unidades suborganizacionais de uma unidade organizacional, as unidades filhas imediatas de uma unidade organizacional ou todas as unidades suborganizacionais e 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 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ê é um revendedor que recupera 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 unidades suborganizacionais all no orgUnitPath, o children imediato do orgUnitPath ou todas as unidades suborganizacionais 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 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. Além do 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 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 as propriedades de solicitação e resposta, consulte a Referência da API:

Se você for um administrador de contas que está excluindo uma unidade organizacional, use my_customer.

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

Se você é um revendedor que está 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 do administrador do 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 tenham unidades organizacionais filhas ou usuários atribuídos a elas. Você precisa atribuir os usuários a outras unidades organizacionais e remover as unidades organizacionais filhas antes de excluir.