Adicionar membros

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.

Adicionar um membro a um grupo de segurança ou do Microsoft 365. Ao utilizar a API para adicionar vários membros num único pedido, pode somar apenas 20 membros.

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

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global	US Government L4	US Government L5 (DOD)	China operada pela 21Vianet
✅	✅	✅	✅

Permissões

A tabela seguinte mostra a permissão com menos privilégios necessária para cada tipo de recurso ao chamar esta 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 utilizador com sessão iniciada também tem de ter uma função de Microsoft Entra suportada ou uma função personalizada com a permissão de microsoft.directory/groups/members/update função. As seguintes funções são as funções com menos privilégios que são suportadas para esta operação, exceto para grupos atribuíveis a funções:

Proprietários de grupos
Escritores de diretório
Administrador de Grupos
Administrador de Governação de Identidades
Administrador do usuário
Administrador do Exchange - apenas para grupos do Microsoft 365
Administrador do SharePoint - apenas para grupos do Microsoft 365
Administrador do Teams - apenas para grupos do Microsoft 365
Administrador do Yammer - apenas para grupos do Microsoft 365
Administrador do Intune - apenas para grupos de segurança

Para adicionar membros a um grupo atribuível a funções, também tem de ser atribuída à aplicação a permissão RoleManagement.ReadWrite.Directory e tem de ser atribuída ao utilizador de chamada uma função de Microsoft Entra suportada. O Administrador de Funções Com Privilégios é a função com menos privilégios suportada para esta operação.

Solicitação HTTP

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

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.

Corpo da solicitação

Ao utilizar 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 para um tipo de objeto membro de grupo suportado.

Ao utilizar 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 para um tipo de objeto membro de grupo suportado. Isso é:

Para grupos do Microsoft 365, apenas https://graph.microsoft.com/v1.0/directoryObjects/{id} e https://graph.microsoft.com/v1.0/groups/{id} é permitido onde {id} deve ser um utilizador, porque apenas os utilizadores podem ser membros de grupos do Microsoft 365.
Para grupos de segurança, são permitidas as seguintes referências de ID:
- https://graph.microsoft.com/v1.0/directoryObjects/{id} onde {id} tem de pertencer a um utilizador, grupo de segurança, dispositivo, principal de serviço ou contacto organizacional.
- https://graph.microsoft.com/v1.0/groups/{id} onde {id} tem de 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 um principal de serviço.
- https://graph.microsoft.com/v1.0/orgContact/{id} onde {id} pertence a um contacto organizacional.

Resposta

Se tiver êxito, este método retornará um código de resposta 204 No Content. Devolve um 400 Bad Request código de resposta quando o objeto já é membro do grupo ou não é suportado como membro do grupo. Devolve um 404 Not Found código de resposta quando o objeto que está a ser adicionado não existe. 403 Unauthorized Devolve num dos seguintes cenários:

Está a tentar adicionar um membro a um grupo que não pode ser gerido através do Microsoft Graph. Esta API suporta apenas segurança e grupos do Microsoft 365.
Está a tentar adicionar um membro que não tem permissões para adicionar. Veja a secção Permissões anterior para obter as permissões necessárias para adicionar diferentes tipos de membros.
Está a tentar adicionar um membro a um grupo atribuível a funções e não tem as permissões necessárias.

Exemplo

Exemplo 1: adicionar um membro a um grupo

Solicitação

O exemplo seguinte mostra um pedido que utiliza a referência directoryObjects para adicionar um membro a um grupo.

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

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


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

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = new ReferenceCreate
{
	OdataId = "https://graph.microsoft.com/beta/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);

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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



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

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

requestBody := graphmodels.NewReferenceCreate()
odataId := "https://graph.microsoft.com/beta/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)

Importante

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


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

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

Importante

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


const options = {
	authProvider,
};

const client = Client.init(options);

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

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

Importante

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


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


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

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

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

Importante

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


Import-Module Microsoft.Graph.Beta.Groups

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

New-MgBetaGroupMemberByRef -GroupId $groupId -BodyParameter $params

Importante

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


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.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/beta/directoryObjects/{id}",
)

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

Importante

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

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. Pode adicionar até 20 membros num único pedido. 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/beta/groups/{group-id}
Content-type: application/json

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


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

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = new Group
{
	AdditionalData = new Dictionary<string, object>
	{
		{
			"members@odata.bind" , new List<string>
			{
				"https://graph.microsoft.com/beta/directoryObjects/{id}",
				"https://graph.microsoft.com/beta/directoryObjects/{id}",
				"https://graph.microsoft.com/beta/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);

Importante

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



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

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

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

Importante

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


// 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/beta/directoryObjects/{id}");
membersOdataBind.add("https://graph.microsoft.com/beta/directoryObjects/{id}");
membersOdataBind.add("https://graph.microsoft.com/beta/directoryObjects/{id}");
additionalData.put("members@odata.bind", membersOdataBind);
group.setAdditionalData(additionalData);
Group result = graphClient.groups().byGroupId("{group-id}").patch(group);

Importante

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


const options = {
	authProvider,
};

const client = Client.init(options);

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

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

Importante

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


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


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

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

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

Importante

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


Import-Module Microsoft.Graph.Beta.Groups

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

Update-MgBetaGroup -GroupId $groupId -BodyParameter $params

Importante

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


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.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/beta/directoryObjects/{id}",
				"https://graph.microsoft.com/beta/directoryObjects/{id}",
				"https://graph.microsoft.com/beta/directoryObjects/{id}",
			],
	}
)

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

Importante

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

Feedback

Esta página foi útil?

Last updated on 2025-09-09

Partilhar via

Adicionar membros

Permissões

Solicitação HTTP

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplo

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

Feedback

Recursos adicionais