Criar ou atualizar funções personalizadas do Azure usando a API REST

Artigo
12/01/2023

Se as funções internas do Azure não atenderem às necessidades específicas de sua organização, você poderá criar funções personalizadas próprias. Este artigo descreve como listar, criar, atualizar ou excluir funções personalizadas usando a API REST.

Pré-requisitos

Você deve usar a seguinte versão:

2015-07-01 ou posterior

Para obter mais informações, consulte as Versões da API das APIs REST do RBAC do Azure.

Listar todas as definições de função personalizadas

Para listar todas as definições de função personalizadas em um locatário, use a API REST Definições de Função - Listar .

O exemplo a seguir lista todas as definições de função personalizadas em um locatário:

Solicitação

GET https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01

Response

{
    "value": [
        {
            "properties": {
                "roleName": "Billing Reader Plus",
                "type": "CustomRole",
                "description": "Read billing data and download invoices",
                "assignableScopes": [
                    "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
                ],
                "permissions": [
                    {
                        "actions": [
                            "Microsoft.Authorization/*/read",
                            "Microsoft.Billing/*/read",
                            "Microsoft.Commerce/*/read",
                            "Microsoft.Consumption/*/read",
                            "Microsoft.Management/managementGroups/read",
                            "Microsoft.CostManagement/*/read",
                            "Microsoft.Billing/invoices/download/action",
                            "Microsoft.CostManagement/exports/*"
                        ],
                        "notActions": [
                            "Microsoft.CostManagement/exports/delete"
                        ],
                        "dataActions": [],
                        "notDataActions": []
                    }
                ],
                "createdOn": "2021-05-22T21:57:23.5764138Z",
                "updatedOn": "2021-05-22T21:57:23.5764138Z",
                "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
                "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
            },
            "id": "/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
            "type": "Microsoft.Authorization/roleDefinitions",
            "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
        }
    ]
}

Listar todas as definições de função personalizadas em um escopo

Para listar definições de função personalizadas em um escopo, use a API REST Definições de Função - Listar .

Comece com a solicitação a seguir:

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01

Dentro da URI, substitua {scope} pelo escopo para o qual você deseja listar as funções.

Escopo	Tipo
`subscriptions/{subscriptionId1}`	Subscription
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Recurso
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de gerenciamento

Substitua {filter} pelo tipo de função.

Filtro	Descrição
`$filter=type+eq+'CustomRole'`	Filtrar com base no tipo CustomRole

O exemplo a seguir lista todas as definições de função personalizadas em uma assinatura:

Solicitação

GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01

Response

{
    "value": [
        {
            "properties": {
                "roleName": "Billing Reader Plus",
                "type": "CustomRole",
                "description": "Read billing data and download invoices",
                "assignableScopes": [
                    "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
                ],
                "permissions": [
                    {
                        "actions": [
                            "Microsoft.Authorization/*/read",
                            "Microsoft.Billing/*/read",
                            "Microsoft.Commerce/*/read",
                            "Microsoft.Consumption/*/read",
                            "Microsoft.Management/managementGroups/read",
                            "Microsoft.CostManagement/*/read",
                            "Microsoft.Billing/invoices/download/action",
                            "Microsoft.CostManagement/exports/*"
                        ],
                        "notActions": [
                            "Microsoft.CostManagement/exports/delete"
                        ],
                        "dataActions": [],
                        "notDataActions": []
                    }
                ],
                "createdOn": "2021-05-22T21:57:23.5764138Z",
                "updatedOn": "2021-05-22T21:57:23.5764138Z",
                "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
                "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
            },
            "id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
            "type": "Microsoft.Authorization/roleDefinitions",
            "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
        }
    ]
}

Listar uma definição de função personalizada por nome

Para obter informações sobre uma definição de função personalizada por seu nome de exibição, use a Definições de Função - Obter API REST.

Comece com a solicitação a seguir:

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01

Dentro da URI, substitua {scope} pelo escopo para o qual você deseja listar as funções.

Escopo	Tipo
`subscriptions/{subscriptionId1}`	Subscription
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Recurso
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de gerenciamento

Substitua {filter} pelo nome de exibição da função.

Filtro	Descrição
`$filter=roleName+eq+'{roleDisplayName}'`	Use a forma codificada da URL do nome de exibição exato da função. Por exemplo, `$filter=roleName+eq+'Virtual%20Machine%20Contributor'`

O exemplo a seguir lista uma definição de função personalizada chamada Billing Reader Plus em uma assinatura:

Solicitação

GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=roleName+eq+'Billing Reader Plus'&api-version=2022-04-01

Response

{
    "value": [
        {
            "properties": {
                "roleName": "Billing Reader Plus",
                "type": "CustomRole",
                "description": "Read billing data and download invoices",
                "assignableScopes": [
                    "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
                ],
                "permissions": [
                    {
                        "actions": [
                            "Microsoft.Authorization/*/read",
                            "Microsoft.Billing/*/read",
                            "Microsoft.Commerce/*/read",
                            "Microsoft.Consumption/*/read",
                            "Microsoft.Management/managementGroups/read",
                            "Microsoft.CostManagement/*/read",
                            "Microsoft.Billing/invoices/download/action",
                            "Microsoft.CostManagement/exports/*"
                        ],
                        "notActions": [
                            "Microsoft.CostManagement/exports/delete"
                        ],
                        "dataActions": [],
                        "notDataActions": []
                    }
                ],
                "createdOn": "2021-05-22T21:57:23.5764138Z",
                "updatedOn": "2021-05-22T21:57:23.5764138Z",
                "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
                "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
            },
            "id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
            "type": "Microsoft.Authorization/roleDefinitions",
            "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
        }
    ]
}

Listar uma definição de função personalizada por ID

Para obter informações sobre uma definição de função personalizada por seu identificador exclusivo, use as Definições de Função - Obter API REST.

Use Definições de Função - Lista API REST para obter o identificador GUID para a função.

Comece com a solicitação a seguir:

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

Dentro da URI, substitua {scope} pelo escopo para o qual você deseja listar as funções.

Escopo	Tipo
`subscriptions/{subscriptionId1}`	Subscription
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Recurso
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de gerenciamento

Substitua {roleDefinitionId} pelo identificador GUID de definição da função.

O exemplo a seguir lista uma definição de função personalizada com o identificador 17adabda-4bf1-4f4e-8c97-1f0cab6dea1c em uma assinatura:

Solicitação

GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c?api-version=2022-04-01

Response

{
    "properties": {
        "roleName": "Billing Reader Plus",
        "type": "CustomRole",
        "description": "Read billing data and download invoices",
        "assignableScopes": [
            "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Authorization/*/read",
                    "Microsoft.Billing/*/read",
                    "Microsoft.Commerce/*/read",
                    "Microsoft.Consumption/*/read",
                    "Microsoft.Management/managementGroups/read",
                    "Microsoft.CostManagement/*/read",
                    "Microsoft.Billing/invoices/download/action",
                    "Microsoft.CostManagement/exports/*"
                ],
                "notActions": [
                    "Microsoft.CostManagement/exports/delete"
                ],
                "dataActions": [],
                "notDataActions": []
            }
        ],
        "createdOn": "2021-05-22T21:57:23.5764138Z",
        "updatedOn": "2021-05-22T21:57:23.5764138Z",
        "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
        "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
    },
    "id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
    "type": "Microsoft.Authorization/roleDefinitions",
    "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
}

Criar uma função personalizada

Para criar uma função personalizada, use Definições de Função - Criar ou Atualizar API REST. Para chamar essa API, você deve entrar com um usuário que recebe uma função que tenha a permissão Microsoft.Authorization/roleDefinitions/write em todos os assignableScopes. Das funções internas, somente Proprietário e dministrador do Acesso de Usuário recebem essa permissão.

Examine a lista de operações do provedor de recursos que estão disponíveis para criar as permissões para a função personalizada.
Use uma ferramenta GUID para gerar um identificador exclusivo que será usado para o identificador de função personalizada. O identificador tem o formato: 00000000-0000-0000-0000-000000000000

Comece com a solicitação e corpo a seguir:

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

{
  "name": "{roleDefinitionId}",
  "properties": {
    "roleName": "",
    "description": "",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [

        ],
        "notActions": [

        ]
      }
    ],
    "assignableScopes": [
      "/subscriptions/{subscriptionId1}",
      "/subscriptions/{subscriptionId2}",
      "/subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}",
      "/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroup2}",
      "/providers/Microsoft.Management/managementGroups/{groupId1}"
    ]
  }
}

Dentro da URI, substita {scope} pelo primeiro assignableScopes da função personalizada.

Escopo	Tipo
`subscriptions/{subscriptionId1}`	Subscription
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupo de recursos
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de gerenciamento

Substitua {roleDefinitionId} pelo identificador GUID de definição da função personalizada.
Dentro do corpo de solicitação, substitua {roleDefinitionId} pelo identificador GUID.
Se assignableScopes for uma assinatura ou grupo de recursos, substitua as instâncias {subscriptionId} ou {resourceGroup} por seus identificadores.
Se assignableScopes for um grupo de gerenciamento, substitua a instância {groupId} pelo identificador do grupo de gerenciamento.
Na propriedade actions, adicione as ações que permitem que a função seja executada.
Na propriedade notActions, adicione as ações que são excluídas das actions permitidas.

Em roleName e description propriedades, especifique um nome exclusivo de função e uma descrição. Para obter informações sobre as propriedades, confira Funções personalizadas do Azure.

O exemplo a seguir mostra um exemplo de um corpo de solicitação:

{
  "name": "88888888-8888-8888-8888-888888888888",
  "properties": {
    "roleName": "Virtual Machine Operator",
    "description": "Can monitor and restart virtual machines.",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [
          "Microsoft.Storage/*/read",
          "Microsoft.Network/*/read",
          "Microsoft.Compute/*/read",
          "Microsoft.Compute/virtualMachines/start/action",
          "Microsoft.Compute/virtualMachines/restart/action",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Support/*"
        ],
        "notActions": []
      }
    ],
    "assignableScopes": [
      "/subscriptions/00000000-0000-0000-0000-000000000000",
      "/providers/Microsoft.Management/managementGroups/marketing-group"
    ]
  }
}

Atualizar uma função personalizada

Para atualizar uma função personalizada, use Definições de Função - Criar ou Atualizar API REST. Para chamar essa API, você deve estar conectado com um usuário ao qual seja atribuída uma função que tenha a Microsoft.Authorization/roleDefinitions/write permissão em todos os , como Administrador de Acesso de assignableScopesUsuário.

Use Definições de Função - Lista ou Definições de Função - Obter API REST para obter informações sobre a função personalizada. Para obter mais informações, consulte a seção anterior Listar todas as definições de função personalizadas.

Comece com a solicitação a seguir:

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

Dentro da URI, substita {scope} pelo primeiro assignableScopes da função personalizada.

Escopo	Tipo
`subscriptions/{subscriptionId1}`	Subscription
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupo de recursos
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de gerenciamento

Substitua {roleDefinitionId} pelo identificador GUID de definição da função personalizada.

Com base nas informações sobre a função personalizada, crie um corpo de solicitação com o seguinte formato:

{
  "name": "{roleDefinitionId}",
  "properties": {
    "roleName": "",
    "description": "",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [

        ],
        "notActions": [

        ]
      }
    ],
    "assignableScopes": [
      "/subscriptions/{subscriptionId1}",
      "/subscriptions/{subscriptionId2}",
      "/subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}",
      "/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroup2}",
      "/providers/Microsoft.Management/managementGroups/{groupId1}"
    ]
  }
}

Atualize o corpo de solicitação com as alterações que você deseja fazer a função personalizada.

O exemplo a seguir mostra um exemplo de um corpo de solicitação com uma nova ação de configurações de diagnóstico adicionada:

{
  "name": "88888888-8888-8888-8888-888888888888",
  "properties": {
    "roleName": "Virtual Machine Operator",
    "description": "Can monitor and restart virtual machines.",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [
          "Microsoft.Storage/*/read",
          "Microsoft.Network/*/read",
          "Microsoft.Compute/*/read",
          "Microsoft.Compute/virtualMachines/start/action",
          "Microsoft.Compute/virtualMachines/restart/action",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Insights/diagnosticSettings/*",
          "Microsoft.Support/*"
        ],
        "notActions": []
      }
    ],
    "assignableScopes": [
      "/subscriptions/00000000-0000-0000-0000-000000000000",
      "/providers/Microsoft.Management/managementGroups/marketing-group"
    ]
  }
}

Excluir uma função personalizada

Para excluir uma função personalizada, use Definições de Função - Excluir API REST. Para chamar essa API, você deve entrar com um usuário que recebe uma função que tenha a permissão Microsoft.Authorization/roleDefinitions/delete em todos os assignableScopes. Das funções internas, somente Proprietário e dministrador do Acesso de Usuário recebem essa permissão.

Remova as atribuições de função que usam a função personalizada. Para obter mais informações, confira Localizar atribuições de função para excluir uma função personalizada.
Use Definições de Função - Lista ou Definições de Função - Obter API REST para obter o identificador GUI da função personalizada. Para obter mais informações, consulte a seção anterior Listar todas as definições de função personalizadas.

Comece com a solicitação a seguir:

DELETE https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

Dentro da URI, substitua {scope} pelo escopo para o qual você deseja excluir a função personalizada.

Escopo	Tipo
`subscriptions/{subscriptionId1}`	Subscription
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupo de recursos
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de gerenciamento

Substitua {roleDefinitionId} pelo identificador GUID de definição da função personalizada.

Criar ou atualizar funções personalizadas do Azure usando a API REST

Pré-requisitos

Listar todas as definições de função personalizadas

Listar todas as definições de função personalizadas em um escopo

Listar uma definição de função personalizada por nome

Listar uma definição de função personalizada por ID

Criar uma função personalizada

Atualizar uma função personalizada

Excluir uma função personalizada

Próximas etapas

Recursos adicionais