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 da sua organização, você poderá criar suas próprias funções personalizadas. 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 mais tarde

Para obter mais informações, consulte Versões de 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 de Definições de Função - Lista .

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

Pedir

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 de Definições de Função - Listagem .

Comece com a seguinte solicitação:

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

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

Âmbito	Tipo
`subscriptions/{subscriptionId1}`	Subscrição
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupo de recursos
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Recurso
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de gestão

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

Filtro	Description
`$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:

Pedir

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 para exibição, use a API Definições de função - Obter REST.

Comece com a seguinte solicitação:

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

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

Âmbito	Tipo
`subscriptions/{subscriptionId1}`	Subscrição
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupo de recursos
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Recurso
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de gestão

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

Filtro	Description
`$filter=roleName+eq+'{roleDisplayName}'`	Use a forma codificada por URL do nome exato para exibição 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:

Pedir

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 a API Definições de função - Obter REST.

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

Comece com a seguinte solicitação:

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

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

Âmbito	Tipo
`subscriptions/{subscriptionId1}`	Subscrição
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupo de recursos
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Recurso
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de gestão

Substitua {roleDefinitionId} pelo identificador GUID da definição de 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:

Pedir

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 a API REST Definições de Função - Criar ou Atualizar . Para chamar essa API, você deve estar conectado com um usuário ao qual é atribuída uma função que tenha a Microsoft.Authorization/roleDefinitions/write permissão em todos os assignableScopesarquivos . Das funções internas, apenas Proprietário e Administrador de Acesso de Usuário incluem essa permissão.

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

Comece com a seguinte solicitação e corpo:

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}"
    ]
  }
}

No URI, substitua {scope} pela primeira assignableScopes da função personalizada.

Âmbito	Tipo
`subscriptions/{subscriptionId1}`	Subscrição
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupo de recursos
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de gestão

Substitua {roleDefinitionId} pelo identificador GUID da função personalizada.
No corpo da 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.
actions Na propriedade, adicione as ações que a função permite que sejam executadas.
notActions Na propriedade, adicione as ações que são excluídas do permitido actions.

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

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 a API REST Definições de função - Criar ou atualizar . Para chamar essa API, você deve estar conectado com um usuário ao qual é 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 as 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 personalizada.

Comece com a seguinte solicitação:

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

No URI, substitua {scope} pela primeira assignableScopes da função personalizada.

Âmbito	Tipo
`subscriptions/{subscriptionId1}`	Subscrição
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupo de recursos
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de gestão

Substitua {roleDefinitionId} pelo identificador GUID 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 da solicitação com as alterações que você deseja fazer na função personalizada.

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"
    ]
  }
}

Eliminar 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 estar conectado com um usuário ao qual é atribuída uma função que tenha a Microsoft.Authorization/roleDefinitions/delete permissão em todos os assignableScopesarquivos . Das funções internas, apenas Proprietário e Administrador de Acesso de Usuário incluem essa permissão.

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

Comece com a seguinte solicitação:

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

No URI, substitua {scope} pelo escopo que você deseja excluir a função personalizada.

Âmbito	Tipo
`subscriptions/{subscriptionId1}`	Subscrição
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupo de recursos
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupo de gestão

Substitua {roleDefinitionId} pelo identificador GUID 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

Eliminar uma função personalizada

Próximos passos

Recursos adicionais