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

项目
03/15/2024

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

先决条件

必须使用以下版本：

2015-07-01 或更高版本

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

列出所有自定义角色定义

若要列出租户中的所有自定义角色定义，请使用角色定义 - 列出 REST API。

以下示例列出了租户中的所有自定义角色定义：

请求

GET https://management.chinacloudapi.cn/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.Consumption/*/read",
                            "Microsoft.Management/managementGroups/read",
                            "Microsoft.Billing/invoices/download/action"
                        ],
                        "notActions": [
                        ],
                        "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。

从下面的请求开始：

GET https://management.chinacloudapi.cn/{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.chinacloudapi.cn/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.Consumption/*/read",
                            "Microsoft.Management/managementGroups/read",
                            "Microsoft.Billing/invoices/download/action"
                        ],
                        "notActions": [
                        ],
                        "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。

从下面的请求开始：

GET https://management.chinacloudapi.cn/{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.chinacloudapi.cn/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.Consumption/*/read",
                            "Microsoft.Management/managementGroups/read",
                            "Microsoft.Billing/invoices/download/action"
                        ],
                        "notActions": [
                        ],
                        "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。

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

从下面的请求开始：

GET https://management.chinacloudapi.cn/{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.chinacloudapi.cn/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.Consumption/*/read",
                    "Microsoft.Management/managementGroups/read",
                    "Microsoft.Billing/invoices/download/action"
                ],
                "notActions": [
                ],
                "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 权限。在内置角色中，只有所有者和用户访问管理员包含此权限。

查看可用来为自定义角色创建权限的资源提供程序操作列表。
使用 GUID 工具生成用作自定义角色标识符的唯一标识符。标识符的格式为：00000000-0000-0000-0000-000000000000

从以下请求和正文开始：

PUT https://management.chinacloudapi.cn/{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/*"
        ],
        "notActions": []
      }
    ],
    "assignableScopes": [
      "/subscriptions/00000000-0000-0000-0000-000000000000",
      "/providers/Microsoft.Management/managementGroups/marketing-group"
    ]
  }
}

更新自定义角色

若要更新自定义角色，请使用角色定义 - 创建或更新 REST API。若要调用此 API，登录时使用的用户必须分配有一个角色，该角色在所有 assignableScopes 上具有 Microsoft.Authorization/roleDefinitions/write 权限（例如用户访问管理员）。

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

从下面的请求开始：

PUT https://management.chinacloudapi.cn/{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/*"
        ],
        "notActions": []
      }
    ],
    "assignableScopes": [
      "/subscriptions/00000000-0000-0000-0000-000000000000",
      "/providers/Microsoft.Management/managementGroups/marketing-group"
    ]
  }
}

删除自定义角色

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

删除使用自定义角色的任何角色分配。有关详细信息，请参阅查找角色分配以删除自定义角色。
使用角色定义 - 列出或角色定义 - 获取 REST API 获取自定义角色的 GUID 标识符。有关详细信息，请参阅前面的列出所有自定义角色定义部分。

从下面的请求开始：

DELETE https://management.chinacloudapi.cn/{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 标识符。

通过

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

先决条件

列出所有自定义角色定义

列出某个范围内的所有自定义角色定义

按名称列出自定义角色定义

按 ID 列出自定义角色定义

创建自定义角色

更新自定义角色

删除自定义角色

后续步骤

其他资源