Adicionar um membro

Namespace: microsoft.graph

Utilize esta API para adicionar um membro (utilizador, grupo ou dispositivo) a uma unidade administrativa. Atualmente, só é possível adicionar um membro de cada vez a uma unidade administrativa.

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

Uma das seguintes permissões é necessária para chamar esta API. Para saber mais, incluindo como escolher permissões, confira Permissões.

Permissões para adicionar um utilizador, grupo ou dispositivo existente

Tipo de permissão	Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante)	AdministrativeUnit.ReadWrite.All
Delegado (conta pessoal da Microsoft)	Sem suporte.
Application	AdministrativeUnit.ReadWrite.All

Importante

Em cenários delegados com contas escolares ou profissionais, o utilizador com sessão iniciada tem de ser um utilizador membro ou ser-lhe atribuída uma função de Microsoft Entra suportada ou uma função personalizada com uma permissão de função suportada. O Administrador de Funções Com Privilégios é a função com menos privilégios suportada para esta operação.

Permissões para criar um novo grupo

Tipo de permissão	Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante)	Group.ReadWrite.All e AdministrativeUnit.Read.All, Directory.ReadWrite.All
Delegado (conta pessoal da Microsoft)	Sem suporte.
Application	Group.Create e AdministrativeUnit.Read.All, Group.ReadWrite.All e AdministrativeUnit.Read.All, Directory.ReadWrite.All

Importante

Para criar um novo grupo numa unidade administrativa, o principal de chamada tem de ter, pelo menos, uma das seguintes funções Microsoft Entra no âmbito da unidade administrativa:

• Administrador do Grupos
• Administrador do usuário

Para cenários apenas de aplicação – para além destas funções, o principal de serviço requer permissões adicionais para ler o diretório. Estas permissões podem ser concedidas através da atribuição de funções de Microsoft Entra suportadas, como a função Leitores de Diretórios; ou podem ser concedidas através de permissões de aplicação do Microsoft Graph que permitem ler o diretório, como Directory.Read.All.

Solicitação HTTP

O pedido seguinte adiciona um utilizador, grupo ou dispositivo existente à unidade administrativa.

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

O pedido seguinte cria um novo grupo na unidade administrativa.

POST /directory/administrativeUnits/{id}/members

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

Adicionar um utilizador, grupo ou dispositivo existente

No corpo do pedido, forneça o id de um utilizador, grupo, dispositivo ou diretórioObjeto a adicionar.

Criar um novo grupo

A tabela seguinte mostra as propriedades do recurso de grupo a especificar quando cria um grupo na unidade administrativa.

Propriedade	Tipo	Descrição
displayName	string	O nome para exibição no catálogo de endereços do grupo. Obrigatório.
description	string	Uma descrição para o grupo. Opcional.
isAssignableToRole	Booliano	Defina como verdadeiro para permitir que o grupo seja atribuído a uma função de Microsoft Entra. O Administrador de Função Privilegiada é a função com menos privilégios para definir o valor desta propriedade. Opcional.
mailEnabled	Boolean	Defina como true para grupos habilitados para email. Obrigatório.
mailNickname	string	O alias de email do grupo. Esses caracteres não podem ser usados no mailNickName: @()\[]";:.<>,SPACE. Obrigatório.
securityEnabled	Boolean	Defina como true para grupos habilitados para segurança, incluindo grupos do Microsoft 365. Obrigatório.
owners	Coleção directoryObject	Esta propriedade representa os proprietários do grupo na hora de criação. Opcional.
membros	Coleção directoryObject	Esta propriedade representa os membros do grupo na hora de criação. Opcional.
visibility	Cadeia de caracteres	Especifica a visibilidade de um grupo do Microsoft 365. Os valores possíveis são: Private, Public, HiddenMembership ou vazio (que é interpretado como Public).

Resposta

Se for bem-sucedido, adicionar um objeto existente (com $ref) devolve 204 No Content o código de resposta. Não devolve nada no corpo da resposta.

Ao criar um novo grupo (sem $ref), este método devolve um 201 Created código de resposta e um objeto de grupo no corpo da resposta. A resposta inclui somente as propriedades padrão do grupo. Tem de fornecer a "@odata.type" : "#microsoft.graph.group" linha no corpo do pedido para identificar explicitamente o novo membro como um grupo. Um corpo do pedido sem o correto @odata.type devolve uma mensagem de 400 Bad Request erro.

Exemplos

Exemplo 1: Adicionar um utilizador ou grupo existente

O pedido seguinte adiciona um utilizador ou grupo existente a uma unidade administrativa.

Solicitação

O exemplo a seguir mostra uma solicitação.

HTTP

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

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

C#

// 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/groups/{id}",
};

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

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

CLI

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

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

Ir

// 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/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.Directory().AdministrativeUnits().ByAdministrativeUnitId("administrativeUnit-id").Members().Ref().Post(context.Background(), requestBody, nil)

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

Java

// 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/groups/{id}");
graphClient.directory().administrativeUnits().byAdministrativeUnitId("{administrativeUnit-id}").members().ref().post(referenceCreate);

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

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

await client.api('/directory/administrativeUnits/{id}/members/$ref')
	.post(directoryObject);

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

PHP

<?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/groups/{id}');

$graphServiceClient->directory()->administrativeUnits()->byAdministrativeUnitId('administrativeUnit-id')->members()->ref()->post($requestBody)->wait();

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

PowerShell

Import-Module Microsoft.Graph.Identity.DirectoryManagement

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

New-MgDirectoryAdministrativeUnitMemberByRef -AdministrativeUnitId $administrativeUnitId -BodyParameter $params

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

Python

# 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/groups/{id}",
)

await graph_client.directory.administrative_units.by_administrative_unit_id('administrativeUnit-id').members.ref.post(request_body)

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

No corpo do pedido, indique o id do objeto de utilizador ou grupo que pretende adicionar.

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 204 No Content

Exemplo 2: Criar um novo grupo

O exemplo seguinte cria um novo grupo na unidade administrativa. Tem de fornecer a "@odata.type" : "#microsoft.graph.group" linha no corpo do pedido para identificar explicitamente o novo membro como um grupo. Um corpo do pedido sem o correto @odata.type devolve uma mensagem de 400 Bad Request erro.

Solicitação

O exemplo a seguir mostra uma solicitação.

HTTP

POST https://graph.microsoft.com/v1.0/directory/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
}

C#

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

// Dependencies
using Microsoft.Graph.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.Directory.AdministrativeUnits["{administrativeUnit-id}"].Members.PostAsync(requestBody);

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

CLI

mgc directory 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\
}\
'

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

Ir

// 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.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.Directory().AdministrativeUnits().ByAdministrativeUnitId("administrativeUnit-id").Members().Post(context.Background(), requestBody, nil)

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

Java

// 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.directory().administrativeUnits().byAdministrativeUnitId("{administrativeUnit-id}").members().post(directoryObject);

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

JavaScript

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('/directory/administrativeUnits/{id}/members')
	.post(directoryObject);

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

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\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->directory()->administrativeUnits()->byAdministrativeUnitId('administrativeUnit-id')->members()->post($requestBody)->wait();

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

PowerShell

Import-Module Microsoft.Graph.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-MgDirectoryAdministrativeUnitMember -AdministrativeUnitId $administrativeUnitId -BodyParameter $params

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

Python

# 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(
	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.directory.administrative_units.by_administrative_unit_id('administrativeUnit-id').members.post(request_body)

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

No corpo do pedido, forneça as propriedades do objeto de grupo que pretende adicionar.

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

{
   "@odata.context": "https://graph.microsoft.com/v1.0/$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": []
}