Agregar miembros

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

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

Nota:

Esta solicitud puede tener retrasos de replicación para grupos creados recientemente. Cuando se crea un grupo, el objeto puede tardar un poco en replicarse completamente en las réplicas del directorio de Microsoft Entra ID. Durante esta ventana, las solicitudes para agregar miembros al grupo pueden devolver un 400 Bad Request error con el mensaje: "El objeto de recurso de origen o uno de los objetos a los que se hace referencia no existe".

Para mitigar este comportamiento:

Vuelva a intentarlo después de un breve retraso : espere unos segundos y vuelva a intentar la solicitud. El retraso suele ser breve.

Para obtener más información, consulte Diseño para lograr coherencia eventual para Microsoft Entra.

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 en la nube nacional.

Servicio global	Administración pública de EE. UU.	Gobierno de EE. UU. L5 (DOD)	China operado 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, también se debe asignar al usuario que ha iniciado sesión una función de Microsoft Entra compatible o una función personalizada con el permiso de microsoft.directory/groups/members/update función. Los roles siguientes son los roles con privilegios mínimos admitidos para esta operación, excepto los grupos asignables a 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 de roles, también se debe asignar a la aplicación el permiso RoleManagement.ReadWrite.Directory y se debe asignar al usuario que llama un rol compatible de Microsoft Entra. El administrador de roles con privilegios 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

Nombre	Descripción
Authorization	{token} de portador. Obligatorio. Obtenga más información sobre autenticación y 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 de miembro del grupo compatible.

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

Para los grupos de Microsoft 365, solo https://graph.microsoft.com/v1.0/directoryObjects/{id} y https://graph.microsoft.com/v1.0/groups/{id} está permitido donde {id} debe haber un usuario porque solo los usuarios pueden ser miembros de los grupos de Microsoft 365.
Para 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 de la organización.
- 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} dónde {id} pertenece a un dispositivo.
- https://graph.microsoft.com/v1.0/servicePrincipal/{id} where {id} pertenece a una entidad de servicio.
- https://graph.microsoft.com/v1.0/orgContact/{id} where {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 400 Bad Request código de respuesta cuando el objeto ya es miembro del grupo, no es compatible como miembro del grupo o cuando el grupo se creó recientemente y no se ha replicado completamente (mensaje de error: "El objeto de recurso de origen o uno de los objetos a los que se hace referencia no existe". Devuelve un 404 Not Found código de respuesta cuando el objeto que se agrega no existe. Se devuelve 403 Forbidden 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 de Microsoft 365.
Está intentando agregar un miembro para el que no tiene permisos. Consulte la sección Permisos anterior para conocer los permisos necesarios para agregar diferentes tipos de miembros.
Está intentando agregar un miembro a un grupo a el que se puede asignar un rol y no tiene los permisos necesarios.

Ejemplo

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

Los SDK de Microsoft Graph usan la versión v1.0 de la API de manera predeterminada y no admiten todos los tipos, propiedades y API disponibles en la versión beta. Para obtener más información sobre cómo acceder a la API beta con el SDK, consulte Uso de los SDK de Microsoft Graph con la API beta.

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

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/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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

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 2026-05-15

Agregar miembros

Permissions

Solicitud HTTP

Encabezados de solicitud

Cuerpo de la solicitud

Respuesta

Ejemplo

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