Crie um novo objeto de grupo se não existir ou atualize as propriedades de um objeto de grupo existente.
Pode criar ou atualizar os seguintes tipos de grupo:
Grupo do Microsoft 365 (grupo unificado)
Grupo de segurança
Por predefinição, esta operação devolve apenas um subconjunto das propriedades de cada grupo. Para obter uma lista das propriedades devolvidas por predefinição, veja a secção Propriedades do recurso de grupo . Para obter propriedades não retornadas por padrão, execute uma operação GET e especifique as propriedades em uma opção de consulta $select do OData.
Nota: para criar uma equipa, crie primeiro um grupo e, em seguida, adicione uma equipa à mesma. Para obter mais informações, consulte Criar equipa.
Permissões
Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.
Tipo de permissão
Permissões com menos privilégios
Permissões com privilégios superiores
Delegado (conta corporativa ou de estudante)
Group.ReadWrite.All
Directory.ReadWrite.All
Delegado (conta pessoal da Microsoft)
Sem suporte.
Sem suporte.
Aplicativo
Group.ReadWrite.All
Directory.ReadWrite.All
Para uma aplicação com permissão Group.Create para criar um grupo com proprietários ou membros, tem de ter os privilégios para ler o tipo de objeto que pretende atribuir como proprietário ou membro do grupo. Por conseguinte:
A aplicação pode atribuir-se a si própria como proprietário ou membro do grupo.
Para criar o grupo com utilizadores como proprietários ou membros, a aplicação tem de ter, pelo menos, a permissão User.Read.All .
Para criar o grupo com outros principais de serviço como proprietários ou membros, a aplicação tem de ter, pelo menos, a permissão Application.Read.All .
Para criar o grupo com utilizadores ou principais de serviço como proprietários ou membros, a aplicação tem de ter, pelo menos, a permissão Directory.Read.All .
create-if-missing. Necessário para o comportamento de upsert, caso contrário, o pedido é tratado como uma operação de atualização.
Corpo da solicitação
No corpo da solicitação, forneça uma representação JSON do objeto de grupo.
A tabela seguinte lista as propriedades necessárias quando cria o grupo. Especifique outras propriedades graváveis conforme necessário para o seu grupo durante a criação ou atualização.
Propriedade
Tipo
Descrição
displayName
Cadeia de caracteres
O nome para exibição no catálogo de endereços do grupo. O comprimento máximo é de 256 caracteres. Obrigatório.
mailEnabled
Boolean
Definir como true para grupos habilitados para email. Obrigatório.
mailNickname
String
O alias de email do grupo, exclusivo para grupos do Microsoft 365 na organização. O comprimento máximo é de 64 caracteres. Essa propriedade pode conter apenas caracteres no conjunto de caracteres ASCII de 0 a 127, exceto o seguinte: @ () \ [] " ; : <> , SPACE. Obrigatório.
securityEnabled
Boolean
Definido como true para grupos habilitados para segurança, incluindo Microsoft 365 grupos. Obrigatório.
Nota: Os grupos criados com o centro de administração do Microsoft Entra ou o portal do Azure têm sempre securityEnabled inicialmente definido como true.
Importante
Criar um grupo usando a permissão de aplicativo Group.Create sem especificar proprietários criará o grupo anonimamente e o grupo não será modificável. Adicione proprietários ao grupo ao criá-lo para especificar os proprietários que podem modificar o grupo.
Ao criar um grupo do Microsoft 365 programaticamente com um contexto somente de aplicativo e sem especificar os proprietários, o grupo será criado anonimamente. Se assim o fizer, o site associado do SharePoint Online só será criado automaticamente, após a execução de outras ações manuais.
As seguintes propriedades não podem ser definidas no pedido POST inicial e têm de ser definidas num pedido PATCH subsequente: allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isSubscribedByMail, unseenCount.
Como o recurso de grupo dá suporte a extensões, você pode adicionar propriedades personalizadas com seus próprios dados para o grupo ao criá-lo.
Opções de groupTypes
Use a propriedade groupTypes para controlar o tipo de grupo e sua associação, conforme mostrad.
Tipo de grupo
Associação atribuída
Associação dinâmica
Microsoft 365 (também conhecido como grupo unificado)
["Unified"]
["Unified","DynamicMembership"]
Dinâmica
[] (null)
["DynamicMembership"]
Resposta
Se não existir um objeto com o uniqueName , este método devolve um 201 Created código de resposta e um novo objeto de grupo no corpo da resposta.
Se um objeto com uniqueName não existir e o Prefer: create-if-missing cabeçalho não for especificado, este método devolve um 404 Not Found código de erro.
Se já existir um objeto com o uniqueName , este método atualiza o objeto de grupo e devolve um 204 No Content código de resposta.
Exemplos
Exemplo 1: Criar um grupo do Microsoft 365 se este não existir
O exemplo seguinte cria um grupo do Microsoft 365 porque não existe um grupo com o valor uniqueName especificado. Como os proprietários não foram especificados, o usuário que fez a chamada é adicionado automaticamente como proprietário do grupo.
PATCH https://graph.microsoft.com/v1.0/groups(uniqueName='uniqueName')
Content-type: application/json
Prefer: create-if-missing
{
"description": "Self help community for golf",
"displayName": "Golf Assist",
"groupTypes": [
"Unified"
],
"mailEnabled": true,
"mailNickname": "golfassist",
"securityEnabled": false
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Group
{
Description = "Self help community for golf",
DisplayName = "Golf Assist",
GroupTypes = new List<string>
{
"Unified",
},
MailEnabled = true,
MailNickname = "golfassist",
SecurityEnabled = false,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.GroupsWithUniqueName("{uniqueName}").PatchAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("Prefer", "create-if-missing");
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Group group = new Group();
group.setDescription("Self help community for golf");
group.setDisplayName("Golf Assist");
LinkedList<String> groupTypes = new LinkedList<String>();
groupTypes.add("Unified");
group.setGroupTypes(groupTypes);
group.setMailEnabled(true);
group.setMailNickname("golfassist");
group.setSecurityEnabled(false);
Group result = graphClient.groupsWithUniqueName("{uniqueName}").patch(group, requestConfiguration -> {
requestConfiguration.headers.add("Prefer", "create-if-missing");
});
O exemplo a seguir mostra a resposta. O valor da propriedade preferredDataLocation foi herdado da localização de dados preferencial do criador do grupo.
Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
Exemplo 2: criar um grupo de segurança com um proprietário e membros se este não existir
O exemplo seguinte cria um grupo de segurança com um proprietário e membros especificados porque não existe um grupo com o valor uniqueName especificado. Observe que, no máximo, 20 relações, como proprietários e membros, podem ser adicionadas como parte da criação do grupo. Posteriormente, pode adicionar vários membros adicionais com a API de membro de adição ou criação de batches JSON.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Group
{
Description = "Group with designated owner and members",
DisplayName = "Operations group",
GroupTypes = new List<string>
{
},
MailEnabled = false,
MailNickname = "operations2019",
SecurityEnabled = true,
AdditionalData = new Dictionary<string, object>
{
{
"owners@odata.bind" , new List<string>
{
"https://graph.microsoft.com/v1.0/users/26be1845-4119-4801-a799-aea79d09f1a2",
}
},
{
"members@odata.bind" , new List<string>
{
"https://graph.microsoft.com/v1.0/users/ff7cb387-6688-423c-8188-3da9532a73cc",
"https://graph.microsoft.com/v1.0/users/69456242-0067-49d3-ba96-9de6f2728e14",
}
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.GroupsWithUniqueName("{uniqueName}").PatchAsync(requestBody);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Group group = new Group();
group.setDescription("Group with designated owner and members");
group.setDisplayName("Operations group");
LinkedList<String> groupTypes = new LinkedList<String>();
group.setGroupTypes(groupTypes);
group.setMailEnabled(false);
group.setMailNickname("operations2019");
group.setSecurityEnabled(true);
HashMap<String, Object> additionalData = new HashMap<String, Object>();
LinkedList<String> ownersOdataBind = new LinkedList<String>();
ownersOdataBind.add("https://graph.microsoft.com/v1.0/users/26be1845-4119-4801-a799-aea79d09f1a2");
additionalData.put("owners@odata.bind", ownersOdataBind);
LinkedList<String> membersOdataBind = new LinkedList<String>();
membersOdataBind.add("https://graph.microsoft.com/v1.0/users/ff7cb387-6688-423c-8188-3da9532a73cc");
membersOdataBind.add("https://graph.microsoft.com/v1.0/users/69456242-0067-49d3-ba96-9de6f2728e14");
additionalData.put("members@odata.bind", membersOdataBind);
group.setAdditionalData(additionalData);
Group result = graphClient.groupsWithUniqueName("{uniqueName}").patch(group);
Veja a seguir o exemplo de uma resposta bem-sucedida. Ele inclui apenas propriedades padrão. Posteriormente, você pode acessar as propriedades de navegação de grupo proprietários ou membros para verificar o proprietário ou membros. O valor da propriedade preferredDataLocation foi herdado da localização de dados preferencial do criador do grupo.
Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Group
{
Description = "Group assignable to a role",
DisplayName = "Role assignable group",
GroupTypes = new List<string>
{
"Unified",
},
IsAssignableToRole = true,
MailEnabled = true,
SecurityEnabled = true,
MailNickname = "contosohelpdeskadministrators",
AdditionalData = new Dictionary<string, object>
{
{
"owners@odata.bind" , new List<string>
{
"https://graph.microsoft.com/v1.0/users/99e44b05-c10b-4e95-a523-e2732bbaba1e",
}
},
{
"members@odata.bind" , new List<string>
{
"https://graph.microsoft.com/v1.0/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0",
"https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e",
}
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.PostAsync(requestBody);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Group group = new Group();
group.setDescription("Group assignable to a role");
group.setDisplayName("Role assignable group");
LinkedList<String> groupTypes = new LinkedList<String>();
groupTypes.add("Unified");
group.setGroupTypes(groupTypes);
group.setIsAssignableToRole(true);
group.setMailEnabled(true);
group.setSecurityEnabled(true);
group.setMailNickname("contosohelpdeskadministrators");
HashMap<String, Object> additionalData = new HashMap<String, Object>();
LinkedList<String> ownersOdataBind = new LinkedList<String>();
ownersOdataBind.add("https://graph.microsoft.com/v1.0/users/99e44b05-c10b-4e95-a523-e2732bbaba1e");
additionalData.put("owners@odata.bind", ownersOdataBind);
LinkedList<String> membersOdataBind = new LinkedList<String>();
membersOdataBind.add("https://graph.microsoft.com/v1.0/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0");
membersOdataBind.add("https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e");
additionalData.put("members@odata.bind", membersOdataBind);
group.setAdditionalData(additionalData);
Group result = graphClient.groups().post(group);
O exemplo a seguir mostra a resposta. O valor da propriedade preferredDataLocation foi herdado da localização de dados preferencial do criador do grupo.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.