你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

使用 REST API 创建或更新 Azure 自定义角色

如果 Azure 内置角色不满足组织的特定需求,你可以创建自己的自定义角色。 本文介绍如何使用 REST API 列出、创建、更新或删除自定义角色。

先决条件

必须使用以下版本:

  • 2015-07-01 或更高版本

有关详细信息,请参阅 Azure RBAC REST API 的 API 版本

列出所有自定义角色定义

若要列出租户中的所有自定义角色定义,请使用角色定义 - 列出 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。

  1. 从下面的请求开始:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01
    
  2. 在 URI 中,将 {scope} 替换为要列出角色的范围。

    作用域 类型
    subscriptions/{subscriptionId1} 订阅
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} 资源组
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} 资源
    providers/Microsoft.Management/managementGroups/{groupId1} 管理组
  3. {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。

  1. 从下面的请求开始:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01
    
  2. 在 URI 中,将 {scope} 替换为要列出角色的范围。

    作用域 类型
    subscriptions/{subscriptionId1} 订阅
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} 资源组
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} 资源
    providers/Microsoft.Management/managementGroups/{groupId1} 管理组
  3. {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"
            }
        ]
    }
    

按 ID 列出自定义角色定义

若要按唯一标识符获取有关自定义角色定义的信息,请使用角色定义 - 获取 REST API。

  1. 使用角色定义 - 列出 REST API 获取角色的 GUID 标识符。

  2. 从下面的请求开始:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01
    
  3. 在 URI 中,将 {scope} 替换为要列出角色的范围。

    作用域 类型
    subscriptions/{subscriptionId1} 订阅
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} 资源组
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} 资源
    providers/Microsoft.Management/managementGroups/{groupId1} 管理组
  4. {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,登录时使用的用户必须分配有一个角色,该角色在所有 assignableScopes 上具有 Microsoft.Authorization/roleDefinitions/write 权限。 在内置角色中,只有所有者用户访问管理员包含此权限。

  1. 查看可用来为自定义角色创建权限的资源提供程序操作列表。

  2. 使用 GUID 工具生成用作自定义角色标识符的唯一标识符。 标识符的格式为:00000000-0000-0000-0000-000000000000

  3. 从以下请求和正文开始:

    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}"
        ]
      }
    }
    
  4. 在 URI 中,将 {scope} 替换为自定义角色的第一个 assignableScopes

    作用域 类型
    subscriptions/{subscriptionId1} 订阅
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} 资源组
    providers/Microsoft.Management/managementGroups/{groupId1} 管理组
  5. {roleDefinitionId} 替换为自定义角色的 GUID 标识符。

  6. 在请求正文中,将 {roleDefinitionId} 替换为 GUID 标识符。

  7. 如果 assignableScopes 是订阅或资源组,请将 {subscriptionId} 或 {resourceGroup} 实例替换为你的标识符。

  8. 如果 assignableScopes 是管理组,请将 {groupId} 实例替换为你的管理组标识符。

  9. actions 属性中,添加该角色允许执行的操作。

  10. notActions 属性中,添加要从允许的 actions 中排除的操作。

  11. roleNamedescription 属性中,指定唯一的角色名称和说明。 有关属性的详细信息,请参阅 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,必须使用分配有所有权限assignableScopes的角色Microsoft.Authorization/roleDefinitions/write(例如用户访问管理员istrator)的用户登录。

  1. 使用角色定义 - 列出角色定义 - 获取 REST API 获取有关自定义角色的信息。 有关详细信息,请参阅前面的列出所有自定义角色定义部分。

  2. 从下面的请求开始:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01
    
  3. 在 URI 中,将 {scope} 替换为自定义角色的第一个 assignableScopes

    作用域 类型
    subscriptions/{subscriptionId1} 订阅
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} 资源组
    providers/Microsoft.Management/managementGroups/{groupId1} 管理组
  4. {roleDefinitionId} 替换为自定义角色的 GUID 标识符。

  5. 根据自定义角色的信息,使用以下格式创建请求正文:

    {
      "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}"
        ]
      }
    }
    
  6. 使用想要对自定义角色所做的更改来更新请求正文。

    下面显示了已添加新诊断设置操作的请求正文示例:

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

删除自定义角色

若要删除自定义角色,请使用角色定义 - 删除 REST API。 若要调用此 API,登录时使用的用户必须分配有一个角色,该角色在所有 assignableScopes 上具有 Microsoft.Authorization/roleDefinitions/delete 权限。 在内置角色中,只有所有者用户访问管理员包含此权限。

  1. 删除使用自定义角色的任何角色分配。 有关详细信息,请参阅查找角色分配以删除自定义角色

  2. 使用角色定义 - 列出角色定义 - 获取 REST API 获取自定义角色的 GUID 标识符。 有关详细信息,请参阅前面的列出所有自定义角色定义部分。

  3. 从下面的请求开始:

    DELETE https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01
    
  4. 在 URI 中,将 {scope} 替换为要删除自定义角色的范围。

    作用域 类型
    subscriptions/{subscriptionId1} 订阅
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} 资源组
    providers/Microsoft.Management/managementGroups/{groupId1} 管理组
  5. {roleDefinitionId} 替换为自定义角色的 GUID 标识符。

后续步骤