Atualizar grupo

Namespace: microsoft.graph

Atualizar as propriedades de um objeto de grupo .

Observação

Quando você usa members@odata.bind para adicionar membros via PATCH, essa solicitação pode ter atrasos de replicação para grupos que foram criados recentemente. Pode levar um curto período de tempo para que o objeto do grupo seja totalmente replicado nas réplicas de diretório do Microsoft Entra ID. Durante essa janela, as solicitações para adicionar membros ao grupo podem retornar um 400 Bad Request erro com a mensagem: "O objeto de recurso de origem ou um dos objetos que estão sendo referenciados não existe".

Para atenuar esse comportamento:

• Tente novamente após um breve intervalo — aguarde alguns segundos e repita a solicitação. O atraso normalmente é breve.

Para obter mais informações, consulte Projetando para consistência eventual para o Microsoft Entra.

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

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão	Permissões menos privilegiadas	Permissões com privilégios mais elevados
Delegado (conta corporativa ou de estudante)	Group-NestingSupport.ReadWrite.All	Directory.ReadWrite.All, Group-PreferredDataLocation.ReadWrite.All, Group.ManageProtection.All, Group.ReadWrite.All
Delegado (conta pessoal da Microsoft)	Sem suporte.	Sem suporte.
Application	Group-NestingSupport.ReadWrite.All	Directory.ReadWrite.All, Group-PreferredDataLocation.ReadWrite.All, Group.ManageProtection.All, Group.ReadWrite.All

Permissões para cenários específicos

• Group-NestingSupport.ReadWrite.All é a permissão menos privilegiada para atualizar a propriedade disableNesting .

• A permissão delegada Group.ManageProtection.All é a permissão menos privilegiada para atualizar a propriedade assignedLabels para grupos de segurança de nuvem. Não há suporte para cenários somente de aplicativo.

Solicitação HTTP

PATCH /groups/{id}

Cabeçalhos de solicitação

Nome	Tipo	Descrição
Autorização	string	{token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.

Corpo da solicitação

No corpo da solicitação, forneça apenas os valores das propriedades que devem ser atualizadas. Propriedades existentes que não estão incluídas no corpo da solicitação terão seus valores anteriores mantidos ou serão recalculadas com base nas alterações a outros valores de propriedade.

A tabela a seguir especifica as propriedades que podem ser atualizadas.

Propriedade	Tipo	Descrição
allowExternalSenders	Boolean	O padrão é false. Indica se as pessoas externas à empresa podem enviar mensagens para o grupo.
assignedLabels	coleção assignedLabel	A lista de pares de rótulos de confidencialidade (ID do rótulo, nome do rótulo) associados a um grupo do Microsoft 365 ou a um grupo de segurança na nuvem. Requer uma licença P1 do Microsoft Entra ID. Essa propriedade pode ser especificada durante a criação ou atualização do grupo. No entanto, para grupos de segurança de nuvem, ele é imutável depois de definido. Para grupos do Microsoft 365, essa propriedade pode ser atualizada somente em cenários delegados em que o chamador requer a permissão do Microsoft Graph e uma função de administrador com suporte. A permissão delegada Group.ManageProtection.All é a permissão menos privilegiada para atualizar essa propriedade para grupos de segurança de nuvem. Não há suporte para cenários somente de aplicativo. Consulte Principais diferenças da rotulagem de grupo do Microsoft 365 para saber mais sobre como gerenciar essa propriedade para o Microsoft 365 versus grupos de segurança na nuvem.
autoSubscribeNewMembers	Boolean	O padrão é false. Indica se novos membros adicionados ao grupo serão automaticamente inscritos para receberem notificações por email. autoSubscribeNewMembers não pode ser true quando subscriptionEnabled é definido como false no grupo.
descrição	String	Uma descrição opcional para o grupo.
displayName	String	O nome de exibição do grupo. Essa propriedade é obrigatória quando um grupo é criado e não pode ser apagado durante atualizações.
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.
preferredDataLocation	String	O local de data preferido para o grupo do Microsoft 365. Para atualizar essa propriedade, o usuário chamador deve receber pelo menos uma das seguintes funções do Microsoft Entra: Administrador de Conta de Usuário Escritor de Diretórios Administrador do Exchange Administrador do SharePoint Para obter mais informações sobre essa propriedade, confira OneDrive Online Multi-Geo.
securityEnabled	Boolean	Especifica se o grupo é um grupo de segurança.
Nome único	Cadeia de caracteres	O identificador exclusivo que pode ser atribuído a um grupo e usado como uma chave alternativa. Pode ser atualizado somente se null e é imutável depois de definido.
visibility	Cadeia de caracteres	Especifica a visibilidade de um grupo do Microsoft 365. Os valores possíveis são: Privado, Público ou vazio (que é interpretado como Público).

Importante

• Para atualizar essas propriedades (accessType, allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isFavorite, isSubscribedByMail, unseenConversationsCount, unseenCount, unseenMessagesCount), você deve:
  • Especifique-as em sua própria solicitação PATCH sem incluir outras propriedades da tabela anterior
  • Ter a permissão Group.ReadWrite.All (não há suporte para Directory.ReadWrite.All nessas propriedades)
• Somente um subconjunto da API de grupo que pertence à administração e ao gerenciamento do grupo principal dá suporte a aplicativos e permissões delegadas. Todos os outros membros da API de grupo, incluindo a atualização de autoSubscribeNewMembers, dão suporte apenas a permissões delegadas.
• As regras para atualizar os grupos de segurança habilitados para email no Microsoft Exchange Server podem ser complexas; Para saber mais, confira Gerenciar grupos de segurança habilitados para email no Exchange Server.
• As permissões de aplicativo não são suportadas ao atualizar assignedLabels. Group.ManageProtection.All é a permissão menos privilegiada para atualizar assignedLabels para grupos de segurança de nuvem.

Gerenciar extensões e dados associados

Use esta API para gerenciar o diretório, o esquema e as extensões abertas e seus dados para grupos, da seguinte maneira:

• Adicione, atualize e armazene dados nas extensões de um grupo existente.
• Para extensões de diretório e esquema, remova todos os dados armazenados definindo o valor da propriedade de extensão personalizada como null. Para extensões abertas, use a API Excluir a extensão aberta.

Resposta

Se for bem-sucedido, esse método retornará um código de 204 No Content resposta, exceto um código de 200 OK resposta ao atualizar as seguintes propriedades: accessType, allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isFavorite, isSubscribedByMail, unseenConversationsCount, unseenCount, unseenMessagesCount.

Erros

Código de status	Código de erro	Mensagem de erro	Descrição
400 Bad Request	Request_BadRequest	"O objeto de recurso de origem ou um dos objetos que estão sendo referenciados não existe."	O grupo foi criado recentemente e não foi totalmente replicado em todas as réplicas de diretório. Esse erro é específico para operações de gravação de link (adicionando membros por meio de members@odata.bind). Repita a solicitação após um breve atraso.

Exemplo

O exemplo a seguir mostra como atualizar um grupo.

Solicitação

O exemplo a seguir mostra uma solicitação.

HTTP

PATCH https://graph.microsoft.com/v1.0/groups/0d09007d-45b2-458c-b180-880dde3a302e
Content-type: application/json

{
  "description": "Library Assist - ADC",
  "displayName": "Library Assist - ADC",
  "mailNickname": "library-help-adc"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Group
{
	Description = "Library Assist - ADC",
	DisplayName = "Library Assist - ADC",
	MailNickname = "library-help-adc",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].PatchAsync(requestBody);

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

Ir

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewGroup()
description := "Library Assist - ADC"
requestBody.SetDescription(&description) 
displayName := "Library Assist - ADC"
requestBody.SetDisplayName(&displayName) 
mailNickname := "library-help-adc"
requestBody.SetMailNickname(&mailNickname) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().ByGroupId("group-id").Patch(context.Background(), requestBody, nil)

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

Java

// 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("Library Assist - ADC");
group.setDisplayName("Library Assist - ADC");
group.setMailNickname("library-help-adc");
Group result = graphClient.groups().byGroupId("{group-id}").patch(group);

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const group = {
  description: 'Library Assist - ADC',
  displayName: 'Library Assist - ADC',
  mailNickname: 'library-help-adc'
};

await client.api('/groups/0d09007d-45b2-458c-b180-880dde3a302e')
	.update(group);

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Group;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Group();
$requestBody->setDescription('Library Assist - ADC');
$requestBody->setDisplayName('Library Assist - ADC');
$requestBody->setMailNickname('library-help-adc');

$result = $graphServiceClient->groups()->byGroupId('group-id')->patch($requestBody)->wait();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

PowerShell

Import-Module Microsoft.Graph.Groups

$params = @{
	description = "Library Assist - ADC"
	displayName = "Library Assist - ADC"
	mailNickname = "library-help-adc"
}

Update-MgGroup -GroupId $groupId -BodyParameter $params

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.group import Group
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Group(
	description = "Library Assist - ADC",
	display_name = "Library Assist - ADC",
	mail_nickname = "library-help-adc",
)

result = await graph_client.groups.by_group_id('group-id').patch(request_body)

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 204 No Content