Agregar miembros

Espacio de nombres: microsoft.graph

Agregue un miembro a un grupo de seguridad o de Microsoft 365. Al usar la API para agregar varios miembros en una solicitud, solo puede agregar hasta 20 miembros.

En la tabla siguiente se muestran los tipos de miembros que se pueden agregar a grupos de seguridad o grupos de Microsoft 365.

Tipo de objeto	Miembro de grupo de seguridad	Miembro del grupo Microsoft 365
User
Grupo de seguridad
Grupo de Microsoft 365
Dispositivo
Servicio principal
Contacto organizacional

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global	Gobierno de EE. UU. L4	Us Government L5 (DOD)	China operada por 21Vianet
✅	✅	✅	✅

Permissions

En la tabla siguiente se muestra el permiso con privilegios mínimos que requiere cada tipo de recurso al llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.

Recurso admitido	Delegado (cuenta profesional o educativa)	Delegado (cuenta de Microsoft personal)	Aplicación
dispositivo	GroupMember.ReadWrite.All y Device.Read.All	No admitida.	GroupMember.ReadWrite.All y Device.ReadWrite.All
group	GroupMember.ReadWrite.All	No admitida.	GroupMember.ReadWrite.All
orgContact	GroupMember.ReadWrite.All y OrgContact.Read.All	No admitida.	GroupMember.ReadWrite.All y OrgContact.Read.All
servicePrincipal	GroupMember.ReadWrite.All y Application.ReadWrite.All	No admitida.	GroupMember.ReadWrite.All y Application.ReadWrite.All
user	GroupMember.ReadWrite.All	No admitida.	GroupMember.ReadWrite.All

Importante

En escenarios delegados, al usuario que ha iniciado sesión también se le debe asignar un rol de Microsoft Entra compatible o un rol personalizado con el permiso de microsoft.directory/groups/members/update rol. Los siguientes roles son los roles con privilegios mínimos que se admiten para esta operación, excepto para los grupos asignables por roles:

Propietarios de grupos
Escritores de directorios
Administrador de grupos
Administrador de gobernanza de identidades
Administrador de usuarios
Administrador de Exchange: solo para grupos de Microsoft 365
Administrador de SharePoint: solo para grupos de Microsoft 365
Administrador de Teams: solo para grupos de Microsoft 365
Administrador de Yammer: solo para grupos de Microsoft 365
administrador de Intune: solo para grupos de seguridad

Para agregar miembros a un grupo asignable a roles, a la aplicación también se le debe asignar el permiso RoleManagement.ReadWrite.Directory y al usuario que realiza la llamada se le debe asignar un rol de Microsoft Entra compatible. Privileged Role Administrator es el rol con privilegios mínimos que se admite para esta operación.

Solicitud HTTP

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

Encabezados de solicitud

Encabezado	Valor
Authorization	{token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
Tipo de contenido	application/json. Obligatorio.

Cuerpo de la solicitud

Al usar la POST /groups/{group-id}/members/$ref sintaxis, proporcione un objeto JSON que contenga una propiedad @odata.id con una referencia por identificador a un tipo de objeto miembro de grupo compatible.

Al usar la PATCH /groups/{group-id} sintaxis, proporcione un objeto JSON que contenga una members@odata.bind propiedad con una o varias referencias por identificadores a un tipo de objeto miembro de grupo compatible. Es decir:

En el caso de los grupos de Microsoft 365, solo https://graph.microsoft.com/v1.0/directoryObjects/{id} se permite y https://graph.microsoft.com/v1.0/groups/{id} donde {id} debe ser un usuario, ya que solo los usuarios pueden pertenecer a grupos de Microsoft 365.
En el caso de los grupos de seguridad, se permiten las siguientes referencias de identificador:
- https://graph.microsoft.com/v1.0/directoryObjects/{id} donde {id} debe pertenecer a un usuario, grupo de seguridad, dispositivo, entidad de servicio o contacto organizativo.
- https://graph.microsoft.com/v1.0/groups/{id} donde {id} debe pertenecer a otro grupo de seguridad. Los grupos de Microsoft 365 no pueden ser miembros de grupos de seguridad.
- https://graph.microsoft.com/v1.0/devices/{id} donde {id} pertenece a un dispositivo.
- https://graph.microsoft.com/v1.0/servicePrincipal/{id} donde {id} pertenece a una entidad de servicio.
- https://graph.microsoft.com/v1.0/orgContact/{id} donde {id} pertenece a un contacto de la organización.

Respuesta

Si se ejecuta correctamente, este método devuelve un código de respuesta 204 No Content. Devuelve un código de 400 Bad Request respuesta cuando el objeto ya es miembro del grupo o no es compatible como miembro del grupo. Devuelve un código de 404 Not Found respuesta cuando el objeto que se agrega no existe. 403 Unauthorized Devuelve en uno de los siguientes escenarios:

Está intentando agregar un miembro a un grupo que no se puede administrar a través de Microsoft Graph. Esta API solo admite grupos de seguridad y microsoft 365.
Está intentando agregar un miembro que no tiene permisos para agregar. Consulte la sección Permisos anterior para obtener los permisos necesarios para agregar diferentes tipos de miembros.
Está intentando agregar un miembro a un grupo asignable a roles y no tiene los permisos necesarios.

Ejemplos

Ejemplo 1: Agregar un miembro a un grupo

Solicitud

En el ejemplo siguiente se muestra una solicitud que usa la referencia directoryObjects para agregar un miembro a un 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)

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 204 No Content

Ejemplo 2: agregar varios miembros a un grupo en una sola solicitud

Este ejemplo muestra cómo agregar varios miembros a un grupo compatible con BIND de OData en una operación PATCH. Se pueden agregar hasta 20 miembros en una sola solicitud. Si existe una condición de error en el cuerpo de la solicitud, no se agregarán miembros y se devolverá el código de respuesta apropiado.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

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)

En el cuerpo de la solicitud, proporcione una representación JSON del Id. de directoryObject, del usuario o del objeto de grupo que quiera agregar.

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 204 No Content

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-09-09

Compartir a través de

Agregar miembros

Permissions

Solicitud HTTP

Encabezados de solicitud

Cuerpo de la solicitud

Respuesta

Ejemplos

Ejemplo 1: Agregar un miembro a un grupo

Solicitud

Respuesta

Ejemplo 2: agregar varios miembros a un grupo en una sola solicitud

Solicitud

Respuesta

Contenido relacionado

Comentarios

Recursos adicionales