Adicionar membros

Namespace: microsoft.graph

Adicione um membro a um grupo de segurança ou do Microsoft 365. Ao usar a API para adicionar vários membros em uma solicitação, você pode adicionar até 20 membros.

Observação

Essa solicitação pode ter atrasos de replicação para grupos que foram criados recentemente. Quando um grupo é criado, pode levar um curto período de tempo para que o objeto 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.

A tabela a seguir mostra os tipos de membros que podem ser adicionados a grupos de segurança ou grupos do Microsoft 365.

Tipo de objeto	Membro do grupo de segurança	Membro do Microsoft 365 grupo
Usuário
Grupo de segurança
Grupo Microsoft 365
Dispositivo
Entidade de serviço
Contatos organizacionais

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

A tabela a seguir mostra a permissão menos privilegiada exigida por cada tipo de recurso ao chamar essa API. Para saber mais, incluindo como escolher permissões, confira Permissões.

Recurso com suporte	Delegada (conta corporativa ou de estudante)	Delegada (conta pessoal da Microsoft)	Application
device	GroupMember.ReadWrite.All e Device.Read.All	Sem suporte.	GroupMember.ReadWrite.All e Device.ReadWrite.All
group	GroupMember.ReadWrite.All	Sem suporte.	GroupMember.ReadWrite.All
orgContact	GroupMember.ReadWrite.All e OrgContact.Read.All	Sem suporte.	GroupMember.ReadWrite.All e OrgContact.Read.All
servicePrincipal	GroupMember.ReadWrite.All e Application.ReadWrite.All	Sem suporte.	GroupMember.ReadWrite.All e Application.ReadWrite.All
user	GroupMember.ReadWrite.All	Sem suporte.	GroupMember.ReadWrite.All

Importante

Em cenários delegados, o usuário conectado também deve receber uma função do Microsoft Entra com suporte ou uma função personalizada com a permissão de microsoft.directory/groups/members/update função. As funções a seguir são as funções menos privilegiadas com suporte para essa operação, exceto para grupos atribuíveis a funções:

Proprietários de grupo
Escritores de diretório
Administrador de grupos
Administrador de Governança de Identidade
Administrador do usuário
Administrador do Exchange – somente para grupos do Microsoft 365
Administrador do SharePoint – somente para grupos do Microsoft 365
Administrador do Teams – somente para grupos do Microsoft 365
Administrador do Yammer - somente para grupos do Microsoft 365
Administrador do Intune – somente para grupos de segurança

Para adicionar membros a um grupo atribuível à função, o aplicativo também deve receber a permissão RoleManagement.ReadWrite.Directory e o usuário que está chamando deve receber uma função do Microsoft Entra com suporte. O Administrador de Função Privilegiada é a função menos privilegiada com suporte para esta operação.

Solicitação HTTP

POST /groups/{group-id}/members/$ref
PATCH /groups/{group-id}

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	{token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-type	application/json. Obrigatório.

Corpo da solicitação

Ao usar a POST /groups/{group-id}/members/$ref sintaxe, forneça um objeto JSON que contenha uma propriedade @odata.id com uma referência por ID a um tipo de objeto de membro do grupo com suporte.

Ao usar a PATCH /groups/{group-id} sintaxe, forneça um objeto JSON que contenha uma members@odata.bind propriedade com uma ou mais referências por IDs a um tipo de objeto de membro do grupo com suporte. Ou seja:

Para grupos do Microsoft 365, somente https://graph.microsoft.com/v1.0/directoryObjects/{id} e https://graph.microsoft.com/v1.0/groups/{id} é permitido onde {id} deve estar um usuário, pois somente usuários podem ser membros de grupos do Microsoft 365.
Para grupos de segurança, as seguintes referências de ID são permitidas:
- https://graph.microsoft.com/v1.0/directoryObjects/{id} em que {id} deve pertencer a um usuário, grupo de segurança, dispositivo, entidade de serviço ou contato organizacional.
- https://graph.microsoft.com/v1.0/groups/{id} em que {id} deve pertencer a outro grupo de segurança. Os grupos do Microsoft 365 não podem ser membros de grupos de segurança.
- https://graph.microsoft.com/v1.0/devices/{id} onde {id} pertence a um dispositivo.
- https://graph.microsoft.com/v1.0/servicePrincipal/{id} onde {id} pertence a uma entidade de serviço.
- https://graph.microsoft.com/v1.0/orgContact/{id} onde {id} pertence a um contato organizacional.

Resposta

Se tiver êxito, este método retornará um código de resposta 204 No Content. Ele retorna um 400 Bad Request código de resposta quando o objeto já é membro do grupo, não tem suporte como membro do grupo ou quando o grupo foi criado recentemente e não foi totalmente replicado (mensagem de erro: "O objeto de recurso de origem ou um dos objetos que estão sendo referenciados não existe." — tente novamente após um breve atraso). Ele retorna um código de 404 Not Found resposta quando o objeto que está sendo adicionado não existe. Ele retorna 403 Forbidden em um dos seguintes cenários:

Você está tentando adicionar um membro a um grupo que não pode ser gerenciado por meio do Microsoft Graph. Essa API dá suporte apenas a grupos de segurança e do Microsoft 365.
Você está tentando adicionar um membro que não tem permissão para adicionar. Consulte a seção Permissões anterior para obter as permissões necessárias para adicionar diferentes tipos de membros.
Você está tentando adicionar um membro a um grupo atribuível à função e não tem as permissões necessárias.

Exemplos

Exemplo 1: adicionar um membro a um grupo

Solicitação

O exemplo a seguir mostra uma solicitação que usa a referência directoryObjects para adicionar um membro a um grupo.

POST https://graph.microsoft.com/v1.0/groups/{group-id}/members/$ref
Content-type: application/json

{
  "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/{id}"
}


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

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new ReferenceCreate
{
	OdataId = "https://graph.microsoft.com/v1.0/directoryObjects/{id}",
};

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



// 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.NewReferenceCreate()
odataId := "https://graph.microsoft.com/v1.0/directoryObjects/{id}"
requestBody.SetOdataId(&odataId) 

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


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.models.ReferenceCreate referenceCreate = new com.microsoft.graph.models.ReferenceCreate();
referenceCreate.setOdataId("https://graph.microsoft.com/v1.0/directoryObjects/{id}");
graphClient.groups().byGroupId("{group-id}").members().ref().post(referenceCreate);


const options = {
	authProvider,
};

const client = Client.init(options);

const directoryObject = {
  '@odata.id': 'https://graph.microsoft.com/v1.0/directoryObjects/{id}'
};

await client.api('/groups/{group-id}/members/$ref')
	.post(directoryObject);


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


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

$requestBody = new ReferenceCreate();
$requestBody->setOdataId('https://graph.microsoft.com/v1.0/directoryObjects/{id}');

$graphServiceClient->groups()->byGroupId('group-id')->members()->ref()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Groups

$params = @{
	"@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/{id}"
}

New-MgGroupMemberByRef -GroupId $groupId -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.reference_create import ReferenceCreate
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ReferenceCreate(
	odata_id = "https://graph.microsoft.com/v1.0/directoryObjects/{id}",
)

await graph_client.groups.by_group_id('group-id').members.ref.post(request_body)

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 204 No Content

Exemplo 2: adicionar vários membros a um grupo em uma única solicitação

Esse exemplo mostra como adicionar vários membros a um grupo com suporte vinculado OData em uma operação PATCH. Até 20 membros podem ser adicionados em uma única solicitação. Se houver uma condição de erro no corpo da solicitação, nenhum membro será adicionado e o código de resposta apropriado será retornado.

Solicitação

O exemplo a seguir mostra uma solicitação.

PATCH https://graph.microsoft.com/v1.0/groups/{group-id}
Content-type: application/json

{
  "members@odata.bind": [
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}",
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}",
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}"
    ]
}


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

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Group
{
	AdditionalData = new Dictionary<string, object>
	{
		{
			"members@odata.bind" , new List<string>
			{
				"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
				"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
				"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
			}
		},
	},
};

// 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);



// 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()
additionalData := map[string]interface{}{
	odataBind := []string {
		"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
		"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
		"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
	}
}
requestBody.SetAdditionalData(additionalData)

// 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)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Group group = new Group();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
LinkedList<String> membersOdataBind = new LinkedList<String>();
membersOdataBind.add("https://graph.microsoft.com/v1.0/directoryObjects/{id}");
membersOdataBind.add("https://graph.microsoft.com/v1.0/directoryObjects/{id}");
membersOdataBind.add("https://graph.microsoft.com/v1.0/directoryObjects/{id}");
additionalData.put("members@odata.bind", membersOdataBind);
group.setAdditionalData(additionalData);
Group result = graphClient.groups().byGroupId("{group-id}").patch(group);


const options = {
	authProvider,
};

const client = Client.init(options);

const group = {
  'members@odata.bind': [
    'https://graph.microsoft.com/v1.0/directoryObjects/{id}',
    'https://graph.microsoft.com/v1.0/directoryObjects/{id}',
    'https://graph.microsoft.com/v1.0/directoryObjects/{id}'
    ]
};

await client.api('/groups/{group-id}')
	.update(group);


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


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

$requestBody = new Group();
$additionalData = [
	'members@odata.bind' => [
'https://graph.microsoft.com/v1.0/directoryObjects/{id}', 'https://graph.microsoft.com/v1.0/directoryObjects/{id}', 'https://graph.microsoft.com/v1.0/directoryObjects/{id}', ],
];
$requestBody->setAdditionalData($additionalData);

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


Import-Module Microsoft.Graph.Groups

$params = @{
	"members@odata.bind" = @(
	"https://graph.microsoft.com/v1.0/directoryObjects/{id}"
"https://graph.microsoft.com/v1.0/directoryObjects/{id}"
"https://graph.microsoft.com/v1.0/directoryObjects/{id}"
)
}

Update-MgGroup -GroupId $groupId -BodyParameter $params


# 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(
	additional_data = {
			"members@odata_bind" : [
				"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
				"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
				"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
			],
	}
)

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

No corpo da solicitação, forneça uma representação JSON da ID do objeto directoryObject, usuário ou grupo que deseja adicionar.

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 204 No Content

Comentários

Esta página foi útil?

Last updated on 2026-08-24

Adicionar membros

Permissões

Solicitação HTTP

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplos

Exemplo 1: adicionar um membro a um grupo

Solicitação

Resposta

Exemplo 2: adicionar vários membros a um grupo em uma única solicitação

Solicitação

Resposta

Conteúdo relacionado

Comentários

Recursos adicionais