Создание или обновление пользовательских ролей Azure с помощью REST API

Статья
2025-04-07

Если встроенные роли Azure не соответствуют потребностям вашей организации, вы можете создать собственные настраиваемые роли. В этой статье описывается, как перечислять, создавать, обновлять или удалять пользовательские роли с помощью REST API.

Предпосылки

Необходимо использовать следующую версию:

2015-07-01 или более поздняя версия.

Дополнительные сведения см. в версиях API Azure RBAC REST APIs.

Перечисление всех определений настраиваемых ролей

Чтобы перечислить все определения настраиваемых ролей в клиенте, используйте определения ролей — список REST API.

В следующем примере перечислены все определения пользовательских ролей в клиенте:

запрос

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

Ответ

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

Список всех пользовательских определений ролей в рамках области

Чтобы вывести список пользовательских определений ролей в определенной области, используйте REST API Role Definitions - List.

Можете начать со следующего запроса:

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

В URI замените {scope} областью, для которой нужно перечислить роли.

Область действия	Тип
`subscriptions/{subscriptionId1}`	Подписка
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Группа ресурсов
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Ресурс
`providers/Microsoft.Management/managementGroups/{groupId1}`	Группа управления

Замените {filter} типом роли.

Фильтр	Описание
`$filter=type+eq+'CustomRole'`	Фильтрация на основе типа CustomRole

В следующем примере перечислены все определения пользовательских ролей в подписке:

запрос

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

Ответ

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

Перечислить определение настраиваемой роли по имени

Чтобы получить сведения об определении пользовательской роли по отображаемому имени, используйте REST API Role Definitions - Get.

Можете начать со следующего запроса:

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

В URI замените {scope} областью, для которой нужно перечислить роли.

Область действия	Тип
`subscriptions/{subscriptionId1}`	Подписка
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Группа ресурсов
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Ресурс
`providers/Microsoft.Management/managementGroups/{groupId1}`	Группа управления

Замените {filter} на отображаемое имя роли.

Фильтр	Описание
`$filter=roleName+eq+'{roleDisplayName}'`	Используйте закодированную URL-адресную форму точного отображаемого имени роли. Например `$filter=roleName+eq+'Virtual%20Machine%20Contributor'`

В следующем примере перечислено пользовательское определение роли с именем Billing Reader Plus в подписке.

запрос

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

Ответ

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

Перечислить определение настраиваемой роли по идентификатору

Чтобы получить сведения об определении пользовательской роли по уникальному идентификатору, используйте API Role Definitions - Get REST.

Используйте определения ролей — список REST API для получения идентификатора GUID для роли.

Можете начать со следующего запроса:

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

В URI замените {scope} областью, для которой нужно перечислить роли.

Область действия	Тип
`subscriptions/{subscriptionId1}`	Подписка
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Группа ресурсов
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Ресурс
`providers/Microsoft.Management/managementGroups/{groupId1}`	Группа управления

Замените {roleDefinitionId} идентификатором GUID определения роли.

В следующем примере приводится определение пользовательской роли с идентификатором 17adabda-4bf1-4f4e-8c97-1f0cab6dea1c в подписке:

запрос

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

Ответ

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

Создание настраиваемой роли

Чтобы создать настраиваемую роль, используйте определения ролей — создание или обновление REST API. Чтобы вызвать этот API, необходимо войти с помощью пользователя, которому назначена роль, имеющая Microsoft.Authorization/roleDefinitions/write разрешение на все объекты assignableScopes. Из встроенных ролей только владелец и администратор доступа пользователей включают это разрешение.

Просмотрите список операций поставщика ресурсов , доступных для создания разрешений для пользовательской роли.
Используйте средство GUID для создания уникального идентификатора, который будет использоваться для пользовательского идентификатора роли. Идентификатор имеет формат: 00000000-0000-0000-0000-000000000000

Начните со следующего запроса и текста:

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

В URI замените {scope} первой assignableScopes пользовательской ролью.

Область действия	Тип
`subscriptions/{subscriptionId1}`	Подписка
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Группа ресурсов
`providers/Microsoft.Management/managementGroups/{groupId1}`	Группа управления

Замените {roleDefinitionId} идентификатором GUID настраиваемой роли.
В тексте запроса замените {roleDefinitionId} идентификатором GUID.
Если assignableScopes это подписка или группа ресурсов, замените экземпляры {subscriptionId} или {resourceGroup} идентификаторами.
Если assignableScopes это группа управления, замените экземпляр {groupId} идентификатором группы управления.
В свойстве actions добавьте действия, которые позволяет выполнять роль.
В свойстве notActions добавьте действия, исключенные из разрешенного actions.

В свойствах roleName и description укажите уникальное имя роли и описание. Дополнительные сведения о свойствах см. в разделе "Пользовательские роли Azure".

Ниже показан пример текста запроса:

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

Обновление настраиваемой роли

Чтобы обновить пользовательскую роль, используйте определения ролей — создание или обновление REST API. Чтобы вызвать этот API, необходимо войти в систему с помощью пользователя, которому назначена роль, которая имеет Microsoft.Authorization/roleDefinitions/write разрешение для всех пользователей assignableScopes, таких как администратор доступа пользователей.

Используйте REST API Role Definitions - List или Role Definitions - Get для получения информации о настраиваемой роли. Дополнительные сведения см. в предыдущем разделе "Список всех определений пользовательских ролей ".

Можете начать со следующего запроса:

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

В URI замените {scope} первой assignableScopes пользовательской ролью.

Область действия	Тип
`subscriptions/{subscriptionId1}`	Подписка
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Группа ресурсов
`providers/Microsoft.Management/managementGroups/{groupId1}`	Группа управления

Замените {roleDefinitionId} идентификатором GUID настраиваемой роли.

На основе сведений о пользовательской роли создайте текст запроса со следующим форматом:

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

Обновите текст запроса с изменениями, которые необходимо внести в настраиваемую роль.

Далее представлен пример основной части запроса, включающий новое действие в настройках диагностики.

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

Удаление настраиваемой роли

Чтобы удалить пользовательскую роль, используйте Role Definitions - Delete REST API. Чтобы вызвать этот API, необходимо войти с помощью пользователя, которому назначена роль, которая имеет Microsoft.Authorization/roleDefinitions/delete разрешение на все assignableScopes. Из встроенных ролей только владелец и администратор доступа пользователей включают это разрешение.

Удалите все назначения ролей, использующие пользовательскую роль. Дополнительные сведения см. в разделе "Поиск назначений ролей" для удаления настраиваемой роли.
Чтобы получить идентификатор GUID настраиваемой роли, используйте определения ролей — список или определения ролей. Дополнительные сведения см. в предыдущем разделе "Список всех определений пользовательских ролей ".

Можете начать со следующего запроса:

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

В URI замените {scope} областью, в которой вы хотите удалить пользовательскую роль.

Область действия	Тип
`subscriptions/{subscriptionId1}`	Подписка
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Группа ресурсов
`providers/Microsoft.Management/managementGroups/{groupId1}`	Группа управления

Замените {roleDefinitionId} идентификатором GUID настраиваемой роли.

Поделиться через

Создание или обновление пользовательских ролей Azure с помощью REST API

Предпосылки

Перечисление всех определений настраиваемых ролей

Список всех пользовательских определений ролей в рамках области

Перечислить определение настраиваемой роли по имени

Перечислить определение настраиваемой роли по идентификатору

Создание настраиваемой роли

Обновление настраиваемой роли

Удаление настраиваемой роли

Дальнейшие действия

Обратная связь

Дополнительные ресурсы