使用 REST API 创建或更新 Azure 自定义角色
如果 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 标识符。