Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Namespace: microsoft.graph
Importante
As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.
Use essa API para adicionar um membro (usuário, grupo ou dispositivo) a uma unidade administrativa ou para criar um novo grupo em uma unidade administrativa. Todos os tipos de grupo podem ser criados em uma unidade administrativa.
Observação: Atualmente, só é possível adicionar um membro por vez a uma unidade administrativa.'
Essa API está disponível nas seguintes implantações de nuvem nacional.
| Serviço global | Governo dos EUA L4 | US Government L5 (DOD) | China operada pela 21Vianet |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
Permissões
Uma das seguintes permissões é necessária para chamar esta API. Para saber mais, incluindo como escolher permissões, confira Permissões.
Permissões para adicionar um usuário, grupo ou dispositivo existente
| Tipo de permissão | Permissões (da com menos para a com mais privilégios) |
|---|---|
| Delegado (conta corporativa ou de estudante) | AdministrativeUnit.ReadWrite.All |
| Delegado (conta pessoal da Microsoft) | Sem suporte. |
| Application | AdministrativeUnit.ReadWrite.All |
Importante
Para acesso delegado usando contas corporativas ou de estudante, o usuário conectado deve ser um usuário membro ou receber uma função do Microsoft Entra com suporte ou uma função personalizada que conceda as permissões necessárias para esta operação. OAdministrador de Função Privilegiada é a função menos privilegiada com suporte para esta operação.
Permissões para criar um novo grupo
| Tipo de permissão | Permissões (da com menos para a com mais privilégios) |
|---|---|
| Delegado (conta corporativa ou de estudante) | Group.ReadWrite.All and AdministrativeUnit.Read.All, Directory.ReadWrite.All |
| Delegado (conta pessoal da Microsoft) | Sem suporte. |
| Application | Group.Create and AdministrativeUnit.Read.All, Group.ReadWrite.All and AdministrativeUnit.Read.All, Directory.ReadWrite.All |
Importante
Para criar um novo grupo em uma unidade administrativa, a entidade principal de chamada deve receber pelo menos uma das seguintes funções do Microsoft Entra no escopo da unidade administrativa:
- Administrador de grupos
- Administrador do usuário
Para cenários somente de aplicativo: além dessas funções, a entidade de serviço requer permissões adicionais para ler o diretório. Essas permissões podem ser concedidas por meio da atribuição de funções do Microsoft Entra com suporte, como a função de Leitores de Diretório; ou podem ser concedidas por meio de permissões do aplicativo Microsoft Graph que permitem a leitura do diretório, como Directory.Read.All.
Solicitação HTTP
A solicitação a seguir adiciona um usuário, grupo ou dispositivo existente à unidade administrativa.
POST /administrativeUnits/{id}/members/$ref
A solicitação a seguir cria um novo grupo na unidade administrativa.
POST /administrativeUnits/{id}/members
Cabeçalhos de solicitação
| Nome | Descrição |
|---|---|
| Autorização | {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização. |
| Content-type | application/json. Obrigatório. |
Adicionando um usuário ou grupo existente
No corpo da solicitação, forneça a ID de um usuário, grupo, dispositivo ou directoryObject a ser adicionado. Se a unidade administrativa for uma unidade administrativa de gerenciamento restrito ("isMemberManagementRestricted": true), o tipo de grupo deverá ser um grupo de segurança do Microsoft Entra. Há suporte apenas para grupos não unificados que são habilitados para segurança, não para email e não para sincronização local.
Criar um novo grupo
A tabela a seguir mostra as propriedades do recurso de grupo a serem especificadas quando você cria um grupo na unidade administrativa.
| Propriedade | Tipo | Descrição |
|---|---|---|
| displayName | string | O nome para exibição no catálogo de endereços do grupo. Obrigatório. |
| description | string | Uma descrição para o grupo. Opcional. |
| isAssignableToRole | Booliano | Defina como true para permitir que o grupo seja atribuído a uma função do Microsoft Entra. Administrador de função privilegiada é a função menos privilegiada para definir o valor dessa propriedade. Opcional. |
| mailEnabled | Boolean | Defina como true para grupos habilitados para email. Obrigatório. |
| mailNickname | string | O alias de email do grupo. Esses caracteres não podem ser usados no mailNickName: @()\[]";:.<>,SPACE. Obrigatório. |
| securityEnabled | Boolean | Defina como true para grupos habilitados para segurança, incluindo grupos do Microsoft 365. Obrigatório. |
| owners | Coleção directoryObject | Esta propriedade representa os proprietários do grupo na hora de criação. Opcional. |
| membros | Coleção directoryObject | Esta propriedade representa os membros do grupo na hora de criação. Opcional. |
| visibility | Cadeia de caracteres | Especifica a visibilidade de um grupo do Microsoft 365. Os valores possíveis são: Private, Public, HiddenMembershipou vazio (que é interpretado como Public). |
Resposta
Se for bem-sucedido, adicionar um objeto existente (usando $ref) retornará 204 No Content o código de resposta. Ele não retorna nada no corpo da resposta.
Ao criar um novo grupo (sem $ref), esse método retorna um código de 201 Created resposta e um objeto de grupo no corpo da resposta. A resposta inclui somente as propriedades padrão do grupo. Você deve fornecer a "@odata.type" : "#microsoft.graph.group" linha no corpo da solicitação para identificar explicitamente o novo membro como um grupo. Um corpo da solicitação sem o correto @odata.type retorna uma mensagem de 400 Bad Request erro.
Exemplos
Exemplo 1: adicionar um usuário ou grupo existente
A seguir, um usuário ou grupo existente será adicionado à unidade administrativa.
Solicitação
O exemplo a seguir mostra uma solicitação.
POST https://graph.microsoft.com/beta/administrativeUnits/{id}/members/$ref
Content-type: application/json
{
"@odata.id":"https://graph.microsoft.com/beta/groups/{id}"
}
No corpo da solicitação, forneça o id objeto de usuário, grupo ou dispositivo que você deseja adicionar.
Resposta
O exemplo a seguir mostra a resposta.
HTTP/1.1 204 No Content
Exemplo 2: Criar um novo grupo
O exemplo a seguir cria um novo grupo na unidade administrativa. Você deve fornecer a "@odata.type" : "#microsoft.graph.group" linha no corpo da solicitação para identificar explicitamente o novo membro como um grupo. Um corpo da solicitação sem o correto @odata.type retorna uma mensagem de 400 Bad Request erro.
Solicitação
O exemplo a seguir mostra uma solicitação.
POST https://graph.microsoft.com/beta/administrativeUnits/{id}/members
Content-type: application/json
{
"@odata.type": "#microsoft.graph.group",
"description": "Self help community for golf",
"displayName": "Golf Assist",
"groupTypes": [
"Unified"
],
"mailEnabled": true,
"mailNickname": "golfassist",
"securityEnabled": false
}
No corpo da solicitação, forneça as propriedades do objeto de grupo que você deseja adicionar.
Resposta
O exemplo a seguir mostra a resposta.
Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#groups/$entity",
"id": "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4",
"deletedDateTime": null,
"classification": null,
"createdDateTime": "2018-12-22T02:21:05Z",
"description": "Self help community for golf",
"displayName": "Golf Assist",
"expirationDateTime": null,
"groupTypes": [
"Unified"
],
"isAssignableToRole": null,
"mail": "golfassist@contoso.com",
"mailEnabled": true,
"mailNickname": "golfassist",
"membershipRule": null,
"membershipRuleProcessingState": null,
"onPremisesLastSyncDateTime": null,
"onPremisesSecurityIdentifier": null,
"onPremisesSyncEnabled": null,
"preferredDataLocation": "CAN",
"preferredLanguage": null,
"proxyAddresses": [
"SMTP:golfassist@contoso.com"
],
"renewedDateTime": "2018-12-22T02:21:05Z",
"resourceBehaviorOptions": [],
"resourceProvisioningOptions": [],
"securityEnabled": false,
"securityIdentifier": "S-1-12-1-1753967289-1089268234-832641959-555555555",
"theme": null,
"visibility": "Public",
"onPremisesProvisioningErrors": []
}