Agregar un miembro

Artículo
10/25/2024

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.

Use esta API para agregar un miembro (usuario, grupo o dispositivo) a una unidad administrativa o para crear un nuevo grupo dentro de una unidad administrativa. Todos los tipos de grupo se pueden crear dentro de una unidad administrativa.

Nota: Actualmente, solo es posible agregar un miembro a la vez a una unidad administrativa."

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

Permisos

Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.

Permisos para agregar un usuario, grupo o dispositivo existente

Tipo de permiso	Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa)	AdministrativeUnit.ReadWrite.All
Delegado (cuenta personal de Microsoft)	No admitida.
Aplicación	AdministrativeUnit.ReadWrite.All

Importante

En escenarios delegados con cuentas profesionales o educativas, el usuario que ha iniciado sesión debe ser un usuario miembro o tener asignado un rol de Microsoft Entra compatible o un rol personalizado con un permiso de rol admitido. Privileged Role Administrator es el rol con privilegios mínimos admitido para esta operación.

Permisos para crear un nuevo grupo

Tipo de permiso	Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa)	Group.ReadWrite.All y AdministrativeUnit.Read.All, Directory.ReadWrite.All
Delegado (cuenta personal de Microsoft)	No admitida.
Aplicación	Group.Create y AdministrativeUnit.Read.All, Group.ReadWrite.All y AdministrativeUnit.Read.All, Directory.ReadWrite.All

Importante

Para crear un nuevo grupo en una unidad administrativa, la entidad de seguridad que realiza la llamada debe tener asignado al menos uno de los siguientes roles de Microsoft Entra en el ámbito de la unidad administrativa:

Administrador de Grupos
Administrador de usuarios

Para escenarios de solo aplicación: aparte de estos roles, la entidad de servicio requiere permisos adicionales para leer el directorio. Estos permisos se pueden conceder mediante la asignación de roles de Microsoft Entra admitidos, como el rol Lectores de directorio; o bien se pueden conceder a través de permisos de aplicación de Microsoft Graph que permiten leer el directorio, como Directory.Read.All.

Solicitud HTTP

La siguiente solicitud agrega un usuario, grupo o dispositivo existente a la unidad administrativa.

POST /administrativeUnits/{id}/members/$ref

La siguiente solicitud crea un nuevo grupo dentro de la unidad administrativa.

POST /administrativeUnits/{id}/members

Encabezados de solicitud

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

Adición de un usuario o grupo existente

En el cuerpo de la solicitud, proporcione el id elemento de un usuario, grupo, dispositivo o directoryObject que se va a agregar. Si la unidad administrativa es una unidad administrativa de administración restringida (isMemberManagementRestricted=true), el tipo de grupo debe ser un grupo de seguridad Microsoft Entra. Solo se admiten los grupos no unificados que están habilitados para la seguridad, no el correo habilitado y no la sincronización local habilitada.

Creación de un nuevo grupo

En la tabla siguiente se muestran las propiedades del recurso de grupo que se deben especificar al crear un grupo en la unidad administrativa.

Propiedad	Tipo	Descripción
displayName	string	El nombre para mostrar en la lista de direcciones del grupo. Obligatorio.
description	cadena	Una descripción para el grupo. Opcional.
isAssignableToRole	Booleano	Establézcalo en true para permitir que el grupo se asigne a un rol de Microsoft Entra. Privileged Role Administrator es el rol con privilegios mínimos para establecer el valor de esta propiedad. Opcional.
mailEnabled	Booleano	Establézcalo a true para grupos habilitados para correo electrónico. Obligatorio.
mailNickname	string	El alias de correo del grupo. Estos caracteres no se pueden usar en mailNickName: `@()\[]";:.<>,SPACE`. Necesario.
securityEnabled	Booleano	Establecer en true para grupos con seguridad habilitada, incluyendo los grupos de Microsoft 365. Necesario.
owners	Colección directoryObject	Esta propiedad representa los propietarios del grupo a la hora de creación. Opcional.
members	Colección directoryObject	Esta propiedad representa los miembros del grupo a la hora de creación. Opcional.
visibility	Cadena	Especifica la visibilidad de un grupo de Microsoft 365. Los valores posibles son: `Private`, `Public`, `HiddenMembership` o vacío (que se interpreta como `Public`).

Respuesta

Si se ejecuta correctamente, agregar un objeto existente (mediante $ref) devuelve 204 No Content código de respuesta. No devuelve nada en el cuerpo de la respuesta.

Al crear un nuevo grupo (sin $ref), este método devuelve un 201 Created código de respuesta y un objeto de grupo en el cuerpo de la respuesta. La respuesta incluye solo las propiedades predeterminadas del grupo. Debe proporcionar la "@odata.type" : "#microsoft.graph.group" línea en el cuerpo de la solicitud para identificar explícitamente al nuevo miembro como un grupo. Un cuerpo de solicitud sin el correcto @odata.type devuelve un mensaje de 400 Bad Request error.

Ejemplos

Ejemplo 1: Agregar un usuario o grupo existente

A continuación se agregará un usuario o grupo existente a la unidad administrativa.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

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

{
  "@odata.id":"https://graph.microsoft.com/beta/groups/{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/groups/{id}",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.AdministrativeUnits["{administrativeUnit-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.



mgc-beta administrative-units members ref post --administrative-unit-id {administrativeUnit-id} --body '{\
  "@odata.id":"https://graph.microsoft.com/beta/groups/{id}"\
}\
'

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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.AdministrativeUnits().ByAdministrativeUnitId("administrativeUnit-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/groups/{id}");
graphClient.administrativeUnits().byAdministrativeUnitId("{administrativeUnit-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/groups/{id}'
};

await client.api('/administrativeUnits/{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/groups/{id}');

$graphServiceClient->administrativeUnits()->byAdministrativeUnitId('administrativeUnit-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.Identity.DirectoryManagement

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

New-MgBetaAdministrativeUnitMemberByRef -AdministrativeUnitId $administrativeUnitId -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/groups/{id}",
)

await graph_client.administrative_units.by_administrative_unit_id('administrativeUnit-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.

En el cuerpo de la solicitud, proporcione el id objeto de usuario, grupo o dispositivo que desea agregar.

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 204 No Content

Ejemplo 2: Creación de un nuevo grupo

En el ejemplo siguiente se crea un nuevo grupo en la unidad administrativa. Debe proporcionar la "@odata.type" : "#microsoft.graph.group" línea en el cuerpo de la solicitud para identificar explícitamente al nuevo miembro como un grupo. Un cuerpo de solicitud sin el correcto @odata.type devuelve un mensaje de 400 Bad Request error.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

POST https://graph.microsoft.com/beta/administrativeUnits/{id}/members
Content-type: application/json

{
  "@odata.type": "#microsoft.graph.group",
  "description": "Self help community for golf",
  "displayName": "Golf Assist",
  "groupTypes": [
    "Unified"
  ],
  "mailEnabled": true,
  "mailNickname": "golfassist",
  "securityEnabled": false
}


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

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

var requestBody = new Group
{
	OdataType = "#microsoft.graph.group",
	Description = "Self help community for golf",
	DisplayName = "Golf Assist",
	GroupTypes = new List<string>
	{
		"Unified",
	},
	MailEnabled = true,
	MailNickname = "golfassist",
	SecurityEnabled = false,
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.AdministrativeUnits["{administrativeUnit-id}"].Members.PostAsync(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.



mgc-beta administrative-units members create --administrative-unit-id {administrativeUnit-id} --body '{\
  "@odata.type": "#microsoft.graph.group",\
  "description": "Self help community for golf",\
  "displayName": "Golf Assist",\
  "groupTypes": [\
    "Unified"\
  ],\
  "mailEnabled": true,\
  "mailNickname": "golfassist",\
  "securityEnabled": false\
}\
'

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.NewDirectoryObject()
description := "Self help community for golf"
requestBody.SetDescription(&description) 
displayName := "Golf Assist"
requestBody.SetDisplayName(&displayName) 
groupTypes := []string {
	"Unified",
}
requestBody.SetGroupTypes(groupTypes)
mailEnabled := true
requestBody.SetMailEnabled(&mailEnabled) 
mailNickname := "golfassist"
requestBody.SetMailNickname(&mailNickname) 
securityEnabled := false
requestBody.SetSecurityEnabled(&securityEnabled) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
members, err := graphClient.AdministrativeUnits().ByAdministrativeUnitId("administrativeUnit-id").Members().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);

Group directoryObject = new Group();
directoryObject.setOdataType("#microsoft.graph.group");
directoryObject.setDescription("Self help community for golf");
directoryObject.setDisplayName("Golf Assist");
LinkedList<String> groupTypes = new LinkedList<String>();
groupTypes.add("Unified");
directoryObject.setGroupTypes(groupTypes);
directoryObject.setMailEnabled(true);
directoryObject.setMailNickname("golfassist");
directoryObject.setSecurityEnabled(false);
DirectoryObject result = graphClient.administrativeUnits().byAdministrativeUnitId("{administrativeUnit-id}").members().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.


const options = {
	authProvider,
};

const client = Client.init(options);

const directoryObject = {
  '@odata.type': '#microsoft.graph.group',
  description: 'Self help community for golf',
  displayName: 'Golf Assist',
  groupTypes: [
    'Unified'
  ],
  mailEnabled: true,
  mailNickname: 'golfassist',
  securityEnabled: false
};

await client.api('/administrativeUnits/{id}/members')
	.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\Group;


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

$requestBody = new Group();
$requestBody->setOdataType('#microsoft.graph.group');
$requestBody->setDescription('Self help community for golf');
$requestBody->setDisplayName('Golf Assist');
$requestBody->setGroupTypes(['Unified', 	]);
$requestBody->setMailEnabled(true);
$requestBody->setMailNickname('golfassist');
$requestBody->setSecurityEnabled(false);

$result = $graphServiceClient->administrativeUnits()->byAdministrativeUnitId('administrativeUnit-id')->members()->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.Identity.DirectoryManagement

$params = @{
	"@odata.type" = "#microsoft.graph.group"
	description = "Self help community for golf"
	displayName = "Golf Assist"
	groupTypes = @(
	"Unified"
)
mailEnabled = $true
mailNickname = "golfassist"
securityEnabled = $false
}

New-MgBetaAdministrativeUnitMember -AdministrativeUnitId $administrativeUnitId -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(
	odata_type = "#microsoft.graph.group",
	description = "Self help community for golf",
	display_name = "Golf Assist",
	group_types = [
		"Unified",
	],
	mail_enabled = True,
	mail_nickname = "golfassist",
	security_enabled = False,
)

result = await graph_client.administrative_units.by_administrative_unit_id('administrativeUnit-id').members.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.

En el cuerpo de la solicitud, proporcione las propiedades del objeto de grupo que desea agregar.

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 201 Created
Content-type: application/json

{
   "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups/$entity",
     "id": "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4",
     "deletedDateTime": null,
     "classification": null,
     "createdDateTime": "2018-12-22T02:21:05Z",
     "description": "Self help community for golf",
     "displayName": "Golf Assist",
     "expirationDateTime": null,
     "groupTypes": [
         "Unified"
     ],
   "isAssignableToRole": null,
     "mail": "golfassist@contoso.com",
     "mailEnabled": true,
     "mailNickname": "golfassist",
     "membershipRule": null,
     "membershipRuleProcessingState": null,
     "onPremisesLastSyncDateTime": null,
     "onPremisesSecurityIdentifier": null,
     "onPremisesSyncEnabled": null,
     "preferredDataLocation": "CAN",
     "preferredLanguage": null,
     "proxyAddresses": [
         "SMTP:golfassist@contoso.com"
     ],
     "renewedDateTime": "2018-12-22T02:21:05Z",
     "resourceBehaviorOptions": [],
     "resourceProvisioningOptions": [],
     "securityEnabled": false,
   "securityIdentifier": "S-1-12-1-1753967289-1089268234-832641959-555555555",
     "theme": null,
     "visibility": "Public",
     "onPremisesProvisioningErrors": []
}

Compartir a través de

Agregar un miembro

Permisos

Permisos para agregar un usuario, grupo o dispositivo existente

Permisos para crear un nuevo grupo

Solicitud HTTP

Encabezados de solicitud

Adición de un usuario o grupo existente

Creación de un nuevo grupo

Respuesta

Ejemplos

Ejemplo 1: Agregar un usuario o grupo existente

Solicitud

Respuesta

Ejemplo 2: Creación de un nuevo grupo

Solicitud

Respuesta

Comentarios

Recursos adicionales