Table of contents

Operações em grupos | Referência da API do Graph

Isha Sahni|Última Atualização: 19/03/2018

Aplica-se a: API do Graph | Azure Active Directory

Este tópico descreve como realizar operações em grupos usando a API do Azure Active Directory (AD) Graph. Com a API do Azure AD Graph, você pode criar, ler, atualizar e excluir grupos. Você também pode consultar os membros de um grupo, adicionar e excluir membros de um grupo, verificar a associação de um grupo em outros grupos, atribuir funções de aplicativo a um grupo e muito mais. Algumas operações de grupo são transitivas e outras estão no escopo somente para membros diretos do grupo. O suporte para algumas operações varia entre grupos de segurança, grupos de distribuição de email e grupos de segurança habilitados por email. Os grupos podem ter usuários, contatos e outros grupos como membros.

A API do Graph é uma API REST compatível com OData 3.0 que fornece acesso programático aos objetos de diretório no Azure Active Directory, como usuários, grupos, contatos organizacionais e aplicativos.

Importante

A funcionalidade da API do Azure AD Graph também está disponível por meio do Microsoft Graph, uma API unificada que também inclui APIs de outros serviços Microsoft, como Outlook, OneDrive, OneNote, Planner e Office Graph, sendo todas elas acessadas por meio de um ponto de extremidade com um token de acesso.

Executar operações REST em grupos

Para executar operações em grupos com a API do Graph, você envia solicitações HTTP com um método com suporte (GET, POST, PATCH, PUT ou DELETE) para um ponto de extremidade visa a coleção de recursos de grupos, um grupo específico, uma propriedade de navegação de um grupo ou uma função ou ação que pode ser chamada em um grupo. As seções a seguir discutem como direcionar e compor operações em grupos.

As solicitações da API do Graph usam a seguinte URL básica:

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}[odata_query_parameters]
Importante

As solicitações enviadas para a API do Graph devem ser bem formadas, visarem um ponto de extremidade e uma versão da API do Graph válidos e apresentarem um token de acesso válido obtido do Azure AD em seu cabeçalho Authorization. Para obter mais informações sobre como criar solicitações e receber respostas com a API do Graph, consulte Operations Overview.

Especifique o {resource_path} de forma diferente dependendo se você está visando a coleção de todos os grupos em seu locatário, um grupo individual ou uma propriedade de navegação de um grupo específico.

  • /groups visa a coleção de recursos do grupo. Você pode usar esse caminho de recurso para ler todos os grupos em seu locatário ou para criar novos grupos de segurança em seu locatário.
  • /groups/{object_id} visa um grupo individual no seu locatário. Especifique o grupo de destino com sua ID (GUID) de objeto. Você pode usar esse caminho de recurso para obter as propriedades declaradas de um grupo, para modificar as propriedades declaradas de um grupo ou para excluir um grupo de segurança.
  • /group/{object_id}/{nav_property} visa a propriedade de navegação especificada de um grupo. Você pode usá-lo para retornar o objeto ou objetos referenciados pela propriedade de navegação de destino do grupo especificado, por exemplo, os membros do grupo. Observação: essa forma de endereçamento está disponível apenas para leituras.
  • /groups/{object_id}/$links/{nav_property} visa a propriedade de navegação especificada de um grupo. Você pode usar essa forma de endereçamento para ler e modificar uma propriedade de navegação. Em leituras, os objetos referenciados pela propriedade são retornados como um ou mais links no corpo da resposta. Em gravações, os objetos são especificados como um ou mais links no corpo da solicitação.

Por exemplo, a solicitação a seguir retorna uma coleção de links para os membros do grupo especificado:

GET https://graph.windows.net/myorganization/groups/ffffffff-ffff-ffff-ffff-ffffffffffff/$links/members?api-version=1.6

Operações básicas em grupos

Você pode executar operações CRUD (criação, leitura, atualização e exclusão) básicas nos grupos e suas propriedades declaradas direcionando a coleção de recursos do grupo ou um grupo específico. Os tópicos a seguir mostram como.

A API do Graph dá suporte a operações em grupos da seguinte maneira:

  • Criação (POST): apenas grupos de segurança.
  • Leitura (GET): todos os grupos.
  • Atualização (PATCH): grupos de segurança e grupos de segurança habilitados por email. Nem todas as propriedades têm suporte.
  • Exclusão (DELETE): somente grupos de segurança.

Obter grupos

Obtém uma coleção de grupos. Você pode adicionar parâmetros de consulta OData para a solicitação para classificar e paginar a resposta. Para obter mais informações, consulte Supported Queries, Filters, and Paging Options.

Em caso de sucesso, retorna uma coleção de objetos Group, caso contrário, o corpo da resposta contém os detalhes do erro. Para obter mais informações sobre erros, consulte Error Codes and Error Handling.

Request

GET https://graph.windows.net/myorganization/groups?api-version

Parameters

ParameterTypeValueNotes
Query
api-versionstringThe version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

Requested URL

GET https://graph.windows.net/myorganization/groups?api-version

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Group",
  "value": [
    {
      "odata.type": "Microsoft.DirectoryServices.Group",
      "objectType": "Group",
      "objectId": "c57cdc98-0dcd-4f90-a82f-c911b288bab9",
      "deletionTimestamp": null,
      "description": "Marketing Group",
      "dirSyncEnabled": null,
      "displayName": "Marketing",
      "lastDirSyncTime": null,
      "mail": null,
      "mailNickname": "cdf76b17-0734-41bc-9c24-9a7af93f3502",
      "mailEnabled": false,
      "onPremisesSecurityIdentifier": null,
      "provisioningErrors": [],
      "proxyAddresses": [],
      "securityEnabled": true
    },
    {
      "odata.type": "Microsoft.DirectoryServices.Group",
      "objectType": "Group",
      "objectId": "cc9869f0-6ac0-4d00-bc24-621a2d949d35",
      "deletionTimestamp": null,
      "description": "Engineering Group",
      "dirSyncEnabled": null,
      "displayName": "Engineering",
      "lastDirSyncTime": null,
      "mail": null,
      "mailNickname": "ef3b8cc1-721b-4452-9e30-9867d1de80ea",
      "mailEnabled": false,
      "onPremisesSecurityIdentifier": null,
      "provisioningErrors": [],
      "proxyAddresses": [],
      "securityEnabled": true
    },
    {
      "odata.type": "Microsoft.DirectoryServices.Group",
      "objectType": "Group",
      "objectId": "fc15e7ef-993f-4865-bf37-317d9b8017b8",
      "deletionTimestamp": null,
      "description": "Test Group",
      "dirSyncEnabled": null,
      "displayName": "Test",
      "lastDirSyncTime": null,
      "mail": null,
      "mailNickname": "fec6273a-20af-49ba-8129-3cbde45a0a16",
      "mailEnabled": false,
      "onPremisesSecurityIdentifier": null,
      "provisioningErrors": [],
      "proxyAddresses": [],
      "securityEnabled": true
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. The results are returned in the response body.

Code Samples


using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
	    static void Main()
        {
            MakeRequest();

            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }

        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            /* OAuth2 is required to access this API. For more information visit:
               https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks */



		   // Specify values for the following required parameters
			queryString["api-version"] = "1.6";
            // Specify values for path parameters (shown as {...})
            var uri = "https://graph.windows.net/myorganization/groups?" + queryString;


            var response = await client.GetAsync(uri);

            if (response.Content != null)
            {
                var responseString = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseString);
            }
        }
    }
}
@ECHO OFF

REM OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
REM Specify values for path parameters (shown as {...}), values for query parameters
curl -v -X GET "https://graph.windows.net/myorganization/groups?api-version=1.6&"^

// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample {

  public static void main(String[] args) {
	HttpClient httpclient = HttpClients.createDefault();

	try
	{
		// OAuth2 is required to access this API. For more information visit:
		// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

		// Specify values for path parameters (shown as {...})
		URIBuilder builder = new URIBuilder("https://graph.windows.net/myorganization/groups");
		// Specify values for the following required parameters
		builder.setParameter("api-version", "1.6");
		URI uri = builder.build();
		HttpGet request = new HttpGet(uri);
		HttpResponse response = httpclient.execute(request);
		HttpEntity entity = response.getEntity();
		if (entity != null) {
			System.out.println(EntityUtils.toString(entity));
		}
	}
	catch (Exception e)
	{
		System.out.println(e.getMessage());
	}
  }
}

<!DOCTYPE html>
<html>
<head>
<title>JSSample</title>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>
<script type="text/javascript">
	$(function() {
		// OAuth2 is required to access this API. For more information visit:
		// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

		var params = {
			// Specify values for the following required parameters
			'api-version': "1.6",
		};
		
		$.ajax({
			// Specify values for path parameters (shown as {...})
			url: 'https://graph.windows.net/myorganization/groups?' + $.param(params),
			type: 'GET',
		})
		.done(function(data) {
			alert("success");
		})
		.fail(function() {
			alert("error");
		});
	});
</script>
</body>
</html>

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
	// OAuth2 is required to access this API. For more information visit:
	// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

	// Specify values for path parameters (shown as {...})
    NSString* path = @"https://graph.windows.net/myorganization/groups";
    NSArray* array = @[
                         @"entities=true",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];
    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"GET"];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];
    if(nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if(nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];
    return 0;
}
<?php

// This sample uses the pecl_http package. (for more information: http://pecl.php.net/package/pecl_http)
require_once 'HTTP/Request2.php';
$headers = array(
);

$query_params = array(
	// Specify values for the following required parameters
	'api-version' => '1.6',
);

$request = new Http_Request2('https://graph.windows.net/myorganization/groups');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setHeader($headers);

// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

$url = $request->getUrl();
$url->setQueryVariables($query_params);

try
{
	$response = $request->send();
	
	echo $response->getBody();
}
catch (HttpException $ex)
{
	echo $ex;
}

?>

########### Python 2.7 #############
import httplib, urllib, base64

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

headers = {
}

params = urllib.urlencode({
	# Specify values for the following required parameters
	'api-version': '1.6',
})

try:
	conn = httplib.HTTPSConnection('graph.windows.net')
	# Specify values for path parameters (shown as {...}) and request body if needed
	conn.request("GET", "/myorganization/groups?%s" % params, "", headers)
	response = conn.getresponse()
	data = response.read()
	print(data)
	conn.close()
except Exception as e:
	print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

headers = {
}

params = urllib.parse.urlencode({
	# Specify values for the following required parameters
	'api-version': '1.6',
})

try:
	conn = http.client.HTTPSConnection('graph.windows.net')
	# Specify values for path parameters (shown as {...}) and request body if needed
	conn.request("GET", "/myorganization/groups?%s" % params, "", headers)
	response = conn.getresponse()
	data = response.read()
	print(data)
	conn.close()
except Exception as e:
	print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################
require 'net/http'

uri = URI('https://graph.windows.net/myorganization/groups')

uri.query = URI.encode_www_form({
	# Specify values for the following required parameters
	'api-version' => '1.6',
})

request = Net::HTTP::Get.new(uri.request_uri)

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks



response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body

###Obter um grupo

Obtém um grupo especificado. Especifique o grupo por sua ID (GUID) de objeto.

Em caso de sucesso, retorna um objeto Group para o grupo especificado, caso contrário, o corpo da resposta contém os detalhes do erro. Para obter mais informações sobre erros, consulte Error Codes and Error Handling.

Request

GET https://graph.windows.net/myorganization/groups/{object_id}?api-version

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target group.
Query
api-versionstringThe version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

Requested URL

GET https://graph.windows.net/myorganization/groups/{object_id}?api-version

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Group/@Element",
  "odata.type": "Microsoft.DirectoryServices.Group",
  "objectType": "Group",
  "objectId": "b4bda672-1fba-4711-8fb1-5383c40b2c14",
  "deletionTimestamp": null,
  "description": "Marketing Department",
  "dirSyncEnabled": null,
  "displayName": "Marketing",
  "lastDirSyncTime": null,
  "mail": null,
  "mailNickname": "BposMailNickName",
  "mailEnabled": false,
  "onPremisesSecurityIdentifier": null,
  "provisioningErrors": [],
  "proxyAddresses": [],
  "securityEnabled": true
}

Response List

Status CodeDescription
200OK. Indicates success. The group is returned in the response body.

Code Samples


using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
	    static void Main()
        {
            MakeRequest();

            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }

        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            /* OAuth2 is required to access this API. For more information visit:
               https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks */



		   // Specify values for the following required parameters
			queryString["api-version"] = "1.6";
            // Specify values for path parameters (shown as {...})
            var uri = "https://graph.windows.net/myorganization/groups/{object_id}?" + queryString;


            var response = await client.GetAsync(uri);

            if (response.Content != null)
            {
                var responseString = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseString);
            }
        }
    }
}
@ECHO OFF

REM OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
REM Specify values for path parameters (shown as {...}), values for query parameters
curl -v -X GET "https://graph.windows.net/myorganization/groups/{object_id}?api-version=1.6&amp;"^

// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample {

  public static void main(String[] args) {
	HttpClient httpclient = HttpClients.createDefault();

	try
	{
		// OAuth2 is required to access this API. For more information visit:
		// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

		// Specify values for path parameters (shown as {...})
		URIBuilder builder = new URIBuilder("https://graph.windows.net/myorganization/groups/{object_id}");
		// Specify values for the following required parameters
		builder.setParameter("api-version", "1.6");
		URI uri = builder.build();
		HttpGet request = new HttpGet(uri);
		HttpResponse response = httpclient.execute(request);
		HttpEntity entity = response.getEntity();
		if (entity != null) {
			System.out.println(EntityUtils.toString(entity));
		}
	}
	catch (Exception e)
	{
		System.out.println(e.getMessage());
	}
  }
}

<!DOCTYPE html>
<html>
<head>
<title>JSSample</title>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>
<script type="text/javascript">
	$(function() {
		// OAuth2 is required to access this API. For more information visit:
		// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

		var params = {
			// Specify values for the following required parameters
			'api-version': "1.6",
		};
		
		$.ajax({
			// Specify values for path parameters (shown as {...})
			url: 'https://graph.windows.net/myorganization/groups/{object_id}?' + $.param(params),
			type: 'GET',
		})
		.done(function(data) {
			alert("success");
		})
		.fail(function() {
			alert("error");
		});
	});
</script>
</body>
</html>

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
	// OAuth2 is required to access this API. For more information visit:
	// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

	// Specify values for path parameters (shown as {...})
    NSString* path = @"https://graph.windows.net/myorganization/groups/{object_id}";
    NSArray* array = @[
                         @"entities=true",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];
    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"GET"];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];
    if(nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if(nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];
    return 0;
}
<?php

// This sample uses the pecl_http package. (for more information: http://pecl.php.net/package/pecl_http)
require_once 'HTTP/Request2.php';
$headers = array(
);

$query_params = array(
	// Specify values for the following required parameters
	'api-version' => '1.6',
);

$request = new Http_Request2('https://graph.windows.net/myorganization/groups/{object_id}');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setHeader($headers);

// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

$url = $request->getUrl();
$url->setQueryVariables($query_params);

try
{
	$response = $request->send();
	
	echo $response->getBody();
}
catch (HttpException $ex)
{
	echo $ex;
}

?>

########### Python 2.7 #############
import httplib, urllib, base64

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

headers = {
}

params = urllib.urlencode({
	# Specify values for the following required parameters
	'api-version': '1.6',
})

try:
	conn = httplib.HTTPSConnection('graph.windows.net')
	# Specify values for path parameters (shown as {...}) and request body if needed
	conn.request("GET", "/myorganization/groups/{object_id}?%s" % params, "", headers)
	response = conn.getresponse()
	data = response.read()
	print(data)
	conn.close()
except Exception as e:
	print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

headers = {
}

params = urllib.parse.urlencode({
	# Specify values for the following required parameters
	'api-version': '1.6',
})

try:
	conn = http.client.HTTPSConnection('graph.windows.net')
	# Specify values for path parameters (shown as {...}) and request body if needed
	conn.request("GET", "/myorganization/groups/{object_id}?%s" % params, "", headers)
	response = conn.getresponse()
	data = response.read()
	print(data)
	conn.close()
except Exception as e:
	print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################
require 'net/http'

uri = URI('https://graph.windows.net/myorganization/groups/{object_id}')

uri.query = URI.encode_www_form({
	# Specify values for the following required parameters
	'api-version' => '1.6',
})

request = Net::HTTP::Get.new(uri.request_uri)

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks



response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body

Criar um grupo

Adiciona um grupo de segurança ao locatário. O corpo da solicitação contém as propriedades do grupo a ser criado. Você deve especificar as propriedades obrigatórias para o grupo. Opcionalmente, você pode especificar quaisquer outras propriedades graváveis.

Importante: você pode criar somente grupos de segurança com a API do Graph. Você não pode criar grupos de segurança habilitados por email ou grupos de distribuição de email.

A tabela a seguir mostra as propriedades que são obrigatórias quando você criar um grupo.

Parâmetro obrigatórioTipoDescrição
displayNamecadeia de caracteresO nome a ser exibido no catálogo de endereços do grupo.
mailEnabledbooleanDeve ser false. Isso ocorre porque somente grupos de segurança puros podem ser criados usando a API do Graph.
mailNicknamecadeia de caracteresO alias de email do grupo.
securityEnabledbooleanDeve ser true. Isso ocorre porque somente grupos de segurança puros podem ser criados usando a API do Graph.

Em caso de sucesso, retorna o Group recém-criado, caso contrário, o corpo da resposta contém os detalhes do erro. Para obter mais informações sobre erros, consulte Error Codes and Error Handling.

Request

POST https://graph.windows.net/myorganization/groups?api-version

Parameters

ParameterTypeValueNotes
Query
api-versionstringThe version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body
Content-Type: application/json
{
  "displayName": "Example Group",
  "mailNickname": "ExampleGroup",
  "mailEnabled": false,
  "securityEnabled": true
}

Requested URL

POST https://graph.windows.net/myorganization/groups?api-version

Response

Status Code:201
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Group/@Element",
  "odata.type": "Microsoft.DirectoryServices.Group",
  "objectType": "Group",
  "objectId": "c7ebe5ed-b1d2-4990-88f7-892e4db2e5f3",
  "deletionTimestamp": null,
  "description": null,
  "dirSyncEnabled": null,
  "displayName": "Example Group",
  "lastDirSyncTime": null,
  "mail": null,
  "mailNickname": "ExampleGroup",
  "mailEnabled": false,
  "onPremisesSecurityIdentifier": null,
  "provisioningErrors": [],
  "proxyAddresses": [],
  "securityEnabled": true
}

Response List

Status CodeDescription
201Created. Indicates success. The new group is returned in the response body.

Atualizar um grupo

Atualize as propriedades de um grupo. Especifique qualquer propriedade Group gravável no corpo da solicitação. Somente as propriedades especificadas são alteradas.

Importante:

  • Apenas grupos de segurança e grupos de segurança habilitados por email podem ser atualizados.
  • Um grupo de segurança não pode ser atualizado para um grupo de segurança habilitado por email ou para um grupo de distribuição de email.

Em caso de sucesso, não é retornado nenhum corpo de resposta, caso contrário, o corpo da resposta contém os detalhes do erro. Para obter mais informações sobre erros, consulte Error Codes and Error Handling.

Request

PATCH https://graph.windows.net/myorganization/groups/{object_id}?api-version

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target group.
Query
api-versionstringThe version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body
Content-Type: application/json
{
  "description": "Example Security Group"
}

Requested URL

PATCH https://graph.windows.net/myorganization/groups/{object_id}?api-version

Response

Status Code:204
Content-Type:
  • application/json

Response List

Status CodeDescription
204No Content. Indicates success. No response body is returned.

Excluir um grupo

Exclui um grupo. Os grupos excluídos não são recuperáveis.

Importante: você pode excluir somente grupos de segurança com a API do Graph. Você não pode excluir grupos de segurança habilitados por email ou grupos de distribuição de email.

Em caso de sucesso, não é retornado nenhum corpo de resposta, caso contrário, o corpo da resposta contém os detalhes do erro. Para obter mais informações sobre erros, consulte Error Codes and Error Handling.

Request

DELETE https://graph.windows.net/myorganization/groups/{object_id}[?api-version]

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target group.
Query
api-versionstringSpecifies the version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

Requested URL

DELETE https://graph.windows.net/myorganization/groups/{object_id}[?api-version]

Response

Status Code:204
Content-Type:
  • application/json

Response List

Status CodeDescription
204No Content. Indicates success.

Operações nas propriedades de navegação do grupo

As relações entre um grupo e outros objetos no diretório, como usuários, contatos e outros grupos, que pode ser seus membros são expostas por meio das propriedades de navegação. Você pode ler e, em alguns casos, modificar essas relações segmentando essas propriedades de navegação em suas solicitações.

As operações têm suporte da seguinte forma:

  • Leitura (GET): todos os grupos.
  • Atualização (POST): grupos de segurança e grupos de segurança habilitados por email (somente members e owners).
  • Exclusão (DELETE): somente grupos de segurança (somente members e owners).

Obter membros diretos de um grupo

Obtém os membros diretos do grupo da propriedade de navegação members.

Em caso de sucesso, retorna uma coleção de links para os Users, Contacts, ServicePrincipals e outros Groups que são membros diretos desse grupo, caso contrário, o corpo da resposta contém os detalhes do erro. Para obter mais informações sobre erros, consulte Error Codes and Error Handling.

Request

GET https://graph.windows.net/myorganization/groups/{object_id}/$links/members?api-version

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target group.
Query
api-versionstringThe version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

Requested URL

GET https://graph.windows.net/myorganization/groups/{object_id}/$links/members?api-version

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/$links/members",
  "value": [
    {
      "url": "https://graph.windows.net/myorganization/directoryObjects/06adda87-a819-4c2e-ab30-127f308468b5/Microsoft.DirectoryServices.User"
    },
    {
      "url": "https://graph.windows.net/myorganization/directoryObjects/225711c4-501c-4e38-b10c-654a4f62ad67/Microsoft.DirectoryServices.User"
    },
    {
      "url": "https://graph.windows.net/myorganization/directoryObjects/2355eace-6b1d-4560-a481-eddabb529537/Microsoft.DirectoryServices.User"
    },
    {
      "url": "https://graph.windows.net/myorganization/directoryObjects/2b0a2e75-f6f5-498a-9f5c-3543e171a5a6/Microsoft.DirectoryServices.User"
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. A collection of links to the group members is returned.

Code Samples


Adicionar membros do grupo

Adiciona um membro a um grupo de segurança ou um grupo de segurança habilitado por email por meio da propriedade de navegação members. Você pode adicionar usuários, contatos, entidades de serviço ou outros grupos. O corpo da solicitação contém um único link para o User, Contact, ServicePrincipal ou Group a ser adicionado.

Importante: você pode adicionar membros apenas a grupos de segurança e grupos de segurança habilitados para email.

Em caso de sucesso, não é retornado nenhum corpo de resposta, caso contrário, o corpo da resposta contém os detalhes do erro. Para obter mais informações sobre erros, consulte Error Codes and Error Handling.

Request

POST https://graph.windows.net/myorganization/groups/{object_id}/$links/members?api-version

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target group.
Query
api-versionstringThe version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body
Content-Type: application/json
{
  "url": "https://graph.windows.net/myorganization/directoryObjects/3eb6055a-baeb-44d4-a1ea-2fee86d8891b"
}

Requested URL

POST https://graph.windows.net/myorganization/groups/{object_id}/$links/members?api-version

Response

Status Code:204
Content-Type:
  • application/json

Response List

Status CodeDescription
204No Content. Indicates success. No response body is returned.

Excluir um membro do grupo

Exclui um membro do grupo especificado de um grupo de segurança por meio da propriedade de navegação members. Especifique a ID de objeto do User, Contact, ServicePrincipal ou Group para excluir o segmento de URL do terminal.

Importante: você pode excluir somente membros de grupos de segurança puros.

Em caso de sucesso, não é retornado nenhum corpo de resposta, caso contrário, o corpo da resposta contém os detalhes do erro. Para obter mais informações sobre erros, consulte Error Codes and Error Handling.

Request

DELETE https://graph.windows.net/myorganization/groups/{object_id}/$links/members/{member_id}?api-version

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target group.
member_idstringThe object ID (GUID) of the member to be removed. Can be a user, a contact, or a group.
Query
api-versionstringThe version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

Requested URL

DELETE https://graph.windows.net/myorganization/groups/{object_id}/$links/members/{member_id}?api-version

Response

Status Code:204
Content-Type:
  • application/json

Response List

Status CodeDescription
204No Content. Indicates success. No response body is returned.

Outras propriedades de navegação

Usando os mesmos padrões mostrados acima, você pode direcionar outras propriedades de navegação expostas pelos grupos. Algumas propriedades são somente leitura e outras podem ser modificadas. Para obter mais informações sobre propriedades de navegação do grupo, consulte a documentação para Group.


Funções e ações em grupos

Você pode chamar qualquer uma das seguintes funções ou ações em um grupo.

Verificar a associação em um grupo específico (transitiva)

Você pode chamar a função isMemberOf para verificar a associação de um usuário, contato, entidade de serviço ou outro grupo em um grupo específico. A verificação é transitiva.

Verificar a associação em uma lista de grupos (transitiva)

Você pode chamar a função checkMemberGroups para verificar a associação de um usuário, contato, entidade de serviço ou grupo em uma lista de grupos. A verificação é transitiva.

Obter todas as associações de grupo (transitiva)

Você pode chamar a função getMemberGroups para retornar todos os grupos dos quais um usuário, contato, entidade de serviço ou grupo é membro. A verificação é transitiva.

Obter todas as associações de grupo e função de diretório (transitiva)

Você pode chamar a função getMemberObjects para retornar todos os grupos e funções de diretório dos quais um usuário, contato, grupo ou entidade de serviço é membro. A verificação é transitiva.


##Recursos adicionais

  • Saiba mais sobre recursos, funcionalidades e recursos de visualização com suporte da API do Graph em Graph API concepts (Conceitos da API do Graph)
© 2018 Microsoft