Namespace: microsoft.graph
Importante
As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.
Crie um novo objeto unifiedRoleDefinition para um provedor RBAC. Esse recurso requer uma licença P1 ou P2 do Microsoft Entra ID.
Atualmente, há suporte para os seguintes provedores RBAC:
- PC na nuvem.
- gerenciamento de dispositivos (Intune)
- Defender (Microsoft Defender XDR)
- diretório (Microsoft Entra ID)
Essa API está disponível nas seguintes implantações de nuvem nacional.
| Serviço global |
Governo dos EUA L4 |
US Government L5 (DOD) |
China operada pela 21Vianet |
| ✅ |
✅ |
✅ |
✅ |
Permissões
As tabelas a seguir mostram a permissão ou permissões menos privilegiadas necessárias para chamar essa API em cada tipo de recurso com suporte. Siga as práticas recomendadas para solicitar permissões com privilégios mínimos. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.
Para um provedor de PC na nuvem
| Tipo de permissão |
Permissões menos privilegiadas |
Permissões com privilégios mais elevados |
| Delegado (conta corporativa ou de estudante) |
DeviceManagementRBAC.ReadWrite.All |
CloudPC.ReadWrite.All, Directory.ReadWrite.All, RoleManagement.ReadWrite.CloudPC, RoleManagement.ReadWrite.Directory |
| Delegado (conta pessoal da Microsoft) |
Sem suporte. |
Sem suporte. |
| Application |
DeviceManagementRBAC.ReadWrite.All |
CloudPC.ReadWrite.All, Directory.ReadWrite.All, RoleManagement.ReadWrite.CloudPC, RoleManagement.ReadWrite.Directory |
Para um provedor de gerenciamento de dispositivos (Intune)
| Tipo de permissão |
Permissões menos privilegiadas |
Permissões com privilégios mais elevados |
| Delegado (conta corporativa ou de estudante) |
RoleManagement.ReadWrite.Defender |
Indisponível. |
| Delegado (conta pessoal da Microsoft) |
Sem suporte. |
Sem suporte. |
| Application |
RoleManagement.ReadWrite.Defender |
Indisponível. |
Para um provedor Defender
| Tipo de permissão |
Permissões menos privilegiadas |
Permissões com privilégios mais elevados |
| Delegado (conta corporativa ou de estudante) |
RoleManagement.ReadWrite.Directory |
Directory.ReadWrite.All |
| Delegado (conta pessoal da Microsoft) |
Sem suporte. |
Sem suporte. |
| Application |
RoleManagement.ReadWrite.Directory |
Directory.ReadWrite.All |
Para um provedor de diretório (Microsoft Entra ID)
| Tipo de permissão |
Permissões menos privilegiadas |
Permissões com privilégios mais elevados |
| Delegado (conta corporativa ou de estudante) |
DeviceManagementRBAC.ReadWrite.All |
CloudPC.ReadWrite.All, Directory.ReadWrite.All, RoleManagement.ReadWrite.CloudPC, RoleManagement.ReadWrite.Directory |
| Delegado (conta pessoal da Microsoft) |
Sem suporte. |
Sem suporte. |
| Application |
DeviceManagementRBAC.ReadWrite.All |
CloudPC.ReadWrite.All, Directory.ReadWrite.All, RoleManagement.ReadWrite.CloudPC, RoleManagement.ReadWrite.Directory |
Importante
Para acesso delegado usando contas corporativas ou de estudante, o usuário conectado deve receber uma função do Microsoft Entra com suporte ou uma função personalizada que conceda as permissões necessárias para esta operação.
O Administrador de Função Privilegiada é a função com menos privilégios com suporte para esta operação.
Solicitação HTTP
Para criar uma definição de função para um provedor de gerenciamento de dispositivos:
POST /roleManagement/deviceManagement/roleDefinitions
Para criar uma definição de função para um provedor do Defender:
POST /roleManagement/defender/roleDefinitions
Para criar uma definição de função para um provedor de diretório:
POST /roleManagement/directory/roleDefinitions
Para criar uma definição de função para um provedor de PC na nuvem:
POST /roleManagement/cloudPc/roleDefinitions
Corpo da solicitação
No corpo da solicitação, forneça uma representação JSON do objeto unifiedRoleDefinition .
A tabela a seguir mostra as propriedades que são necessárias ao criar um roleDefinition.
| Parâmetro |
Tipo |
Descrição |
| displayName |
string |
O nome de exibição para a definição de função. |
| isEnabled |
Booliano |
Sinalizador que indica se a função está habilitada para atribuição. Se for false, a função não estará disponível para atribuição. |
| rolePermissions |
Coleção unifiedRolePermission |
Lista de permissões incluídas na função. |
Resposta
Se for bem-sucedido, esse método retornará 201 Created o código de resposta e um novo objeto unifiedRoleDefinition no corpo da resposta.
Exemplo 1: Criar uma função personalizada para um provedor de diretório
Solicitação
POST https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions
Content-type: application/json
{
"description": "Update basic properties of application registrations",
"displayName": "Application Registration Support Administrator",
"rolePermissions":
[
{
"allowedResourceActions":
[
"microsoft.directory/applications/basic/read"
]
}
],
"isEnabled" : "true"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models;
var requestBody = new UnifiedRoleDefinition
{
Description = "Update basic properties of application registrations",
DisplayName = "Application Registration Support Administrator",
RolePermissions = new List<UnifiedRolePermission>
{
new UnifiedRolePermission
{
AllowedResourceActions = new List<string>
{
"microsoft.directory/applications/basic/read",
},
},
},
IsEnabled = true,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.RoleManagement.Directory.RoleDefinitions.PostAsync(requestBody);
// 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.NewUnifiedRoleDefinition()
description := "Update basic properties of application registrations"
requestBody.SetDescription(&description)
displayName := "Application Registration Support Administrator"
requestBody.SetDisplayName(&displayName)
unifiedRolePermission := graphmodels.NewUnifiedRolePermission()
allowedResourceActions := []string {
"microsoft.directory/applications/basic/read",
}
unifiedRolePermission.SetAllowedResourceActions(allowedResourceActions)
rolePermissions := []graphmodels.UnifiedRolePermissionable {
unifiedRolePermission,
}
requestBody.SetRolePermissions(rolePermissions)
isEnabled := true
requestBody.SetIsEnabled(&isEnabled)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
roleDefinitions, err := graphClient.RoleManagement().Directory().RoleDefinitions().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UnifiedRoleDefinition unifiedRoleDefinition = new UnifiedRoleDefinition();
unifiedRoleDefinition.setDescription("Update basic properties of application registrations");
unifiedRoleDefinition.setDisplayName("Application Registration Support Administrator");
LinkedList<UnifiedRolePermission> rolePermissions = new LinkedList<UnifiedRolePermission>();
UnifiedRolePermission unifiedRolePermission = new UnifiedRolePermission();
LinkedList<String> allowedResourceActions = new LinkedList<String>();
allowedResourceActions.add("microsoft.directory/applications/basic/read");
unifiedRolePermission.setAllowedResourceActions(allowedResourceActions);
rolePermissions.add(unifiedRolePermission);
unifiedRoleDefinition.setRolePermissions(rolePermissions);
unifiedRoleDefinition.setIsEnabled(true);
UnifiedRoleDefinition result = graphClient.roleManagement().directory().roleDefinitions().post(unifiedRoleDefinition);
const options = {
authProvider,
};
const client = Client.init(options);
const unifiedRoleDefinition = {
description: 'Update basic properties of application registrations',
displayName: 'Application Registration Support Administrator',
rolePermissions:
[
{
allowedResourceActions:
[
'microsoft.directory/applications/basic/read'
]
}
],
isEnabled: 'true'
};
await client.api('/roleManagement/directory/roleDefinitions')
.version('beta')
.post(unifiedRoleDefinition);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\UnifiedRoleDefinition;
use Microsoft\Graph\Beta\Generated\Models\UnifiedRolePermission;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new UnifiedRoleDefinition();
$requestBody->setDescription('Update basic properties of application registrations');
$requestBody->setDisplayName('Application Registration Support Administrator');
$rolePermissionsUnifiedRolePermission1 = new UnifiedRolePermission();
$rolePermissionsUnifiedRolePermission1->setAllowedResourceActions(['microsoft.directory/applications/basic/read', ]);
$rolePermissionsArray []= $rolePermissionsUnifiedRolePermission1;
$requestBody->setRolePermissions($rolePermissionsArray);
$requestBody->setIsEnabled(true);
$result = $graphServiceClient->roleManagement()->directory()->roleDefinitions()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Identity.Governance
$params = @{
description = "Update basic properties of application registrations"
displayName = "Application Registration Support Administrator"
rolePermissions = @(
@{
allowedResourceActions = @(
"microsoft.directory/applications/basic/read"
)
}
)
isEnabled = "true"
}
New-MgBetaRoleManagementDirectoryRoleDefinition -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.unified_role_definition import UnifiedRoleDefinition
from msgraph_beta.generated.models.unified_role_permission import UnifiedRolePermission
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = UnifiedRoleDefinition(
description = "Update basic properties of application registrations",
display_name = "Application Registration Support Administrator",
role_permissions = [
UnifiedRolePermission(
allowed_resource_actions = [
"microsoft.directory/applications/basic/read",
],
),
],
is_enabled = True,
)
result = await graph_client.role_management.directory.role_definitions.post(request_body)
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/beta/$metadata#roleManagement/directory/roleDefinitions/$entity",
"id": "d5eec5e0-6992-4c6b-b430-0f833f1a815a",
"description": "Update basic properties of application registrations",
"displayName": "Application Registration Support Administrator",
"isBuiltIn": false,
"isEnabled": true,
"templateId": "d5eec5e0-6992-4c6b-b430-0f833f1a815a",
"version": null,
"rolePermissions": [
{
"allowedResourceActions": [
"microsoft.directory/applications/standard/read",
"microsoft.directory/applications/basic/update"
],
"condition": null
}
],
"inheritsPermissionsFrom": []
}
Exemplo 2: Criar uma função personalizada para um provedor de PC na nuvem
Solicitação
POST https://graph.microsoft.com/beta/roleManagement/cloudPC/roleDefinitions
Content-type: application/json
{
"description": "An example custom role",
"displayName": "ExampleCustomRole",
"rolePermissions":
[
{
"allowedResourceActions":
[
"Microsoft.CloudPC/CloudPCs/Read"
]
}
],
"condition" : "null"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models;
var requestBody = new UnifiedRoleDefinition
{
Description = "An example custom role",
DisplayName = "ExampleCustomRole",
RolePermissions = new List<UnifiedRolePermission>
{
new UnifiedRolePermission
{
AllowedResourceActions = new List<string>
{
"Microsoft.CloudPC/CloudPCs/Read",
},
},
},
AdditionalData = new Dictionary<string, object>
{
{
"condition" , "null"
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.RoleManagement.CloudPC.RoleDefinitions.PostAsync(requestBody);
// 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.NewUnifiedRoleDefinition()
description := "An example custom role"
requestBody.SetDescription(&description)
displayName := "ExampleCustomRole"
requestBody.SetDisplayName(&displayName)
unifiedRolePermission := graphmodels.NewUnifiedRolePermission()
allowedResourceActions := []string {
"Microsoft.CloudPC/CloudPCs/Read",
}
unifiedRolePermission.SetAllowedResourceActions(allowedResourceActions)
rolePermissions := []graphmodels.UnifiedRolePermissionable {
unifiedRolePermission,
}
requestBody.SetRolePermissions(rolePermissions)
additionalData := map[string]interface{}{
"condition" : "null",
}
requestBody.SetAdditionalData(additionalData)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
roleDefinitions, err := graphClient.RoleManagement().CloudPC().RoleDefinitions().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UnifiedRoleDefinition unifiedRoleDefinition = new UnifiedRoleDefinition();
unifiedRoleDefinition.setDescription("An example custom role");
unifiedRoleDefinition.setDisplayName("ExampleCustomRole");
LinkedList<UnifiedRolePermission> rolePermissions = new LinkedList<UnifiedRolePermission>();
UnifiedRolePermission unifiedRolePermission = new UnifiedRolePermission();
LinkedList<String> allowedResourceActions = new LinkedList<String>();
allowedResourceActions.add("Microsoft.CloudPC/CloudPCs/Read");
unifiedRolePermission.setAllowedResourceActions(allowedResourceActions);
rolePermissions.add(unifiedRolePermission);
unifiedRoleDefinition.setRolePermissions(rolePermissions);
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("condition", "null");
unifiedRoleDefinition.setAdditionalData(additionalData);
UnifiedRoleDefinition result = graphClient.roleManagement().cloudPC().roleDefinitions().post(unifiedRoleDefinition);
const options = {
authProvider,
};
const client = Client.init(options);
const unifiedRoleDefinition = {
description: 'An example custom role',
displayName: 'ExampleCustomRole',
rolePermissions:
[
{
allowedResourceActions:
[
'Microsoft.CloudPC/CloudPCs/Read'
]
}
],
condition: 'null'
};
await client.api('/roleManagement/cloudPC/roleDefinitions')
.version('beta')
.post(unifiedRoleDefinition);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\UnifiedRoleDefinition;
use Microsoft\Graph\Beta\Generated\Models\UnifiedRolePermission;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new UnifiedRoleDefinition();
$requestBody->setDescription('An example custom role');
$requestBody->setDisplayName('ExampleCustomRole');
$rolePermissionsUnifiedRolePermission1 = new UnifiedRolePermission();
$rolePermissionsUnifiedRolePermission1->setAllowedResourceActions(['Microsoft.CloudPC/CloudPCs/Read', ]);
$rolePermissionsArray []= $rolePermissionsUnifiedRolePermission1;
$requestBody->setRolePermissions($rolePermissionsArray);
$additionalData = [
'condition' => 'null',
];
$requestBody->setAdditionalData($additionalData);
$result = $graphServiceClient->roleManagement()->cloudPC()->roleDefinitions()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.DeviceManagement.Enrollment
$params = @{
description = "An example custom role"
displayName = "ExampleCustomRole"
rolePermissions = @(
@{
allowedResourceActions = @(
"Microsoft.CloudPC/CloudPCs/Read"
)
}
)
condition = "null"
}
New-MgBetaRoleManagementCloudPcRoleDefinition -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.unified_role_definition import UnifiedRoleDefinition
from msgraph_beta.generated.models.unified_role_permission import UnifiedRolePermission
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = UnifiedRoleDefinition(
description = "An example custom role",
display_name = "ExampleCustomRole",
role_permissions = [
UnifiedRolePermission(
allowed_resource_actions = [
"Microsoft.CloudPC/CloudPCs/Read",
],
),
],
additional_data = {
"condition" : "null",
}
)
result = await graph_client.role_management.cloud_p_c.role_definitions.post(request_body)
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/beta/$metadata#roleManagement/cloudPc/roleDefinitions/$entity",
"id": "b7f5ddc1-b7dc-4d37-abce-b9d6fc15ffff",
"description": "An example custom role",
"displayName": "ExampleCustomRole",
"isBuiltIn": false,
"isEnabled": true,
"templateId": "b7f5ddc1-b7dc-4d37-abce-b9d6fc15ffff",
"version": null,
"rolePermissions": [
{
"allowedResourceActions": [
"Microsoft.CloudPC/CloudPCs/Read"
],
"condition": null
}
],
"resourceScopes":["/"]
}
Exemplo 3: Criar uma função personalizada para um provedor do Defender
Solicitação
POST https://graph.microsoft.com/beta/roleManagement/defender/roleDefinitions
Content-type: application/json
{
"description": "Role 1 description",
"displayName": "Role 1",
"rolePermissions":
[
{
"allowedResourceActions":
[
"microsoft.xdr/securityposture/read"
]
}
]
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models;
var requestBody = new UnifiedRoleDefinition
{
Description = "Role 1 description",
DisplayName = "Role 1",
RolePermissions = new List<UnifiedRolePermission>
{
new UnifiedRolePermission
{
AllowedResourceActions = new List<string>
{
"microsoft.xdr/securityposture/read",
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.RoleManagement.Defender.RoleDefinitions.PostAsync(requestBody);
// 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.NewUnifiedRoleDefinition()
description := "Role 1 description"
requestBody.SetDescription(&description)
displayName := "Role 1"
requestBody.SetDisplayName(&displayName)
unifiedRolePermission := graphmodels.NewUnifiedRolePermission()
allowedResourceActions := []string {
"microsoft.xdr/securityposture/read",
}
unifiedRolePermission.SetAllowedResourceActions(allowedResourceActions)
rolePermissions := []graphmodels.UnifiedRolePermissionable {
unifiedRolePermission,
}
requestBody.SetRolePermissions(rolePermissions)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
roleDefinitions, err := graphClient.RoleManagement().Defender().RoleDefinitions().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UnifiedRoleDefinition unifiedRoleDefinition = new UnifiedRoleDefinition();
unifiedRoleDefinition.setDescription("Role 1 description");
unifiedRoleDefinition.setDisplayName("Role 1");
LinkedList<UnifiedRolePermission> rolePermissions = new LinkedList<UnifiedRolePermission>();
UnifiedRolePermission unifiedRolePermission = new UnifiedRolePermission();
LinkedList<String> allowedResourceActions = new LinkedList<String>();
allowedResourceActions.add("microsoft.xdr/securityposture/read");
unifiedRolePermission.setAllowedResourceActions(allowedResourceActions);
rolePermissions.add(unifiedRolePermission);
unifiedRoleDefinition.setRolePermissions(rolePermissions);
UnifiedRoleDefinition result = graphClient.roleManagement().defender().roleDefinitions().post(unifiedRoleDefinition);
const options = {
authProvider,
};
const client = Client.init(options);
const unifiedRoleDefinition = {
description: 'Role 1 description',
displayName: 'Role 1',
rolePermissions:
[
{
allowedResourceActions:
[
'microsoft.xdr/securityposture/read'
]
}
]
};
await client.api('/roleManagement/defender/roleDefinitions')
.version('beta')
.post(unifiedRoleDefinition);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\UnifiedRoleDefinition;
use Microsoft\Graph\Beta\Generated\Models\UnifiedRolePermission;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new UnifiedRoleDefinition();
$requestBody->setDescription('Role 1 description');
$requestBody->setDisplayName('Role 1');
$rolePermissionsUnifiedRolePermission1 = new UnifiedRolePermission();
$rolePermissionsUnifiedRolePermission1->setAllowedResourceActions(['microsoft.xdr/securityposture/read', ]);
$rolePermissionsArray []= $rolePermissionsUnifiedRolePermission1;
$requestBody->setRolePermissions($rolePermissionsArray);
$result = $graphServiceClient->roleManagement()->defender()->roleDefinitions()->post($requestBody)->wait();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.unified_role_definition import UnifiedRoleDefinition
from msgraph_beta.generated.models.unified_role_permission import UnifiedRolePermission
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = UnifiedRoleDefinition(
description = "Role 1 description",
display_name = "Role 1",
role_permissions = [
UnifiedRolePermission(
allowed_resource_actions = [
"microsoft.xdr/securityposture/read",
],
),
],
)
result = await graph_client.role_management.defender.role_definitions.post(request_body)
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/beta/$metadata#roleManagement/defender/roleDefinitions/$entity",
"id": "d5eec5e0-6992-4c6b-b430-0f833f1a815b",
"description": "Role 1 description",
"displayName": "Role 1",
"rolePermissions": [
{
"allowedResourceActions": [
"microsoft.xdr/securityposture/read"
]
}
]
}