使用 REST API 创建或更新 Azure 自定义角色Create or update Azure custom roles using the REST API

重要

将管理组添加到 AssignableScopes 的功能目前为预览版。Adding a management group to AssignableScopes is currently in preview. 此预览版在提供时没有附带服务级别协议,不建议将其用于生产工作负荷。This preview version is provided without a service level agreement, and it's not recommended for production workloads. 某些功能可能不受支持或者受限。Certain features might not be supported or might have constrained capabilities. 有关详细信息,请参阅适用于 Azure 预览版的补充使用条款For more information, see Supplemental Terms of Use for Azure Previews.

如果 Azure 内置角色不满足组织的特定需求,你可以创建自己的自定义角色。If the Azure built-in roles don't meet the specific needs of your organization, you can create your own custom roles. 本文介绍如何使用 REST API 列出、创建、更新或删除自定义角色。This article describes how to list, create, update, or delete custom roles using the REST API.

列出自定义角色List custom roles

若要列出目录中的所有自定义角色,请使用角色定义 - 列出 REST API。To list all custom roles in a directory, use the Role Definitions - List REST API.

  1. 从下面的请求开始:Start with the following request:

    GET https://management.chinacloudapi.cn/providers/Microsoft.Authorization/roleDefinitions?api-version=2015-07-01&$filter={filter}
    
  2. {filter} 替换为角色类型。Replace {filter} with the role type.

    筛选器Filter 说明Description
    $filter=type+eq+'CustomRole' 基于 CustomRole 类型的筛选器Filter based on the CustomRole type

列出某个范围的自定义角色List custom roles at a scope

若要列出某个范围的自定义角色,请使用角色定义 - 列出 REST API。To list custom roles at a scope, use the Role Definitions - List REST API.

  1. 从下面的请求开始:Start with the following request:

    GET https://management.chinacloudapi.cn/{scope}/providers/Microsoft.Authorization/roleDefinitions?api-version=2015-07-01&$filter={filter}
    
  2. 在 URI 中,将 {scope} 替换为要列出角色的范围。Within the URI, replace {scope} with the scope for which you want to list the roles.

    作用域Scope 类型Type
    subscriptions/{subscriptionId1} 订阅Subscription
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} 资源组Resource group
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} 资源Resource
    providers/Microsoft.Management/managementGroups/{groupId1} 管理组Management group
  3. {filter} 替换为角色类型。Replace {filter} with the role type.

    筛选器Filter 说明Description
    $filter=type+eq+'CustomRole' 基于 CustomRole 类型的筛选器Filter based on the CustomRole type

按名称列出自定义角色定义List a custom role definition by name

若要按显示名称获取自定义角色的信息,请使用角色定义 - 获取 REST API。To get information about a custom role by its display name, use the Role Definitions - Get REST API.

  1. 从下面的请求开始:Start with the following request:

    GET https://management.chinacloudapi.cn/{scope}/providers/Microsoft.Authorization/roleDefinitions?api-version=2015-07-01&$filter={filter}
    
  2. 在 URI 中,将 {scope} 替换为要列出角色的范围。Within the URI, replace {scope} with the scope for which you want to list the roles.

    作用域Scope 类型Type
    subscriptions/{subscriptionId1} 订阅Subscription
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} 资源组Resource group
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} 资源Resource
    providers/Microsoft.Management/managementGroups/{groupId1} 管理组Management group
  3. {filter} 替换为角色的显示名称。Replace {filter} with the display name for the role.

    筛选器Filter 说明Description
    $filter=roleName+eq+'{roleDisplayName}' 使用角色的具体显示名称的 URL 编码形式。Use the URL encoded form of the exact display name of the role. 例如 $filter=roleName+eq+'Virtual%20Machine%20Contributor'For instance, $filter=roleName+eq+'Virtual%20Machine%20Contributor'

按 ID 列出自定义角色定义List a custom role definition by ID

若要按唯一标识符获取自定义角色的信息,请使用角色定义 - 获取 REST API。To get information about a custom role by its unique identifier, use the Role Definitions - Get REST API.

  1. 使用角色定义 - 列出 REST API 获取角色的 GUID 标识符。Use the Role Definitions - List REST API to get the GUID identifier for the role.

  2. 从下面的请求开始:Start with the following request:

    GET https://management.chinacloudapi.cn/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2015-07-01
    
  3. 在 URI 中,将 {scope} 替换为要列出角色的范围。Within the URI, replace {scope} with the scope for which you want to list the roles.

    作用域Scope 类型Type
    subscriptions/{subscriptionId1} 订阅Subscription
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} 资源组Resource group
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} 资源Resource
    providers/Microsoft.Management/managementGroups/{groupId1} 管理组Management group
  4. {roleDefinitionId} 替换为角色定义的 GUID 标识符。Replace {roleDefinitionId} with the GUID identifier of the role definition.

创建自定义角色Create a custom role

若要创建自定义角色,请使用角色定义 - 创建或更新 REST API。To create a custom role, use the Role Definitions - Create Or Update REST API. 若要调用此 API,登录时使用的用户必须分配有一个角色,该角色在所有 assignableScopes 上具有 Microsoft.Authorization/roleDefinitions/write 权限。To call this API, you must be signed in with a user that is assigned a role that has the Microsoft.Authorization/roleDefinitions/write permission on all the assignableScopes. 在内置角色中,只有所有者用户访问管理员包含此权限。Of the built-in roles, only Owner and User Access Administrator include this permission.

  1. 查看可用来为自定义角色创建权限的资源提供程序操作列表。Review the list of resource provider operations that are available to create the permissions for your custom role.

  2. 使用 GUID 工具生成用作自定义角色标识符的唯一标识符。Use a GUID tool to generate a unique identifier that will be used for the custom role identifier. 标识符的格式为:00000000-0000-0000-0000-000000000000The identifier has the format: 00000000-0000-0000-0000-000000000000

  3. 从以下请求和正文开始:Start with the following request and body:

    PUT https://management.chinacloudapi.cn/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2015-07-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} 替换为自定义角色的第一个 assignableScopesWithin the URI, replace {scope} with the first assignableScopes of the custom role.

    作用域Scope 类型Type
    subscriptions/{subscriptionId1} 订阅Subscription
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} 资源组Resource group
    providers/Microsoft.Management/managementGroups/{groupId1} 管理组Management group
  5. {roleDefinitionId} 替换为自定义角色的 GUID 标识符。Replace {roleDefinitionId} with the GUID identifier of the custom role.

  6. 在请求正文中,将 {roleDefinitionId} 替换为 GUID 标识符。Within the request body, replace {roleDefinitionId} with the GUID identifier.

  7. 如果 assignableScopes 是订阅或资源组,请将 {subscriptionId} 或 {resourceGroup} 实例替换为你的标识符。If assignableScopes is a subscription or resource group, replace the {subscriptionId} or {resourceGroup} instances with your identifiers.

  8. 如果 assignableScopes 是管理组,请将 {groupId} 实例替换为你的管理组标识符。If assignableScopes is a management group, replace the {groupId} instance with your management group identifier. 将管理组添加到 assignableScopes 的功能目前处于预览状态。Adding a management group to assignableScopes is currently in preview.

  9. actions 属性中,添加该角色允许执行的操作。In the actions property, add the operations that the role allows to be performed.

  10. notActions 属性中,添加要从允许的 actions 中排除的操作。In the notActions property, add the operations that are excluded from the allowed actions.

  11. roleNamedescription 属性中,指定唯一的角色名称和说明。In the roleName and description properties, specify a unique role name and a description. 有关属性的详细信息,请参阅 Azure 自定义角色For more information about the properties, see Azure custom roles.

    下面显示了请求正文的示例:The following shows an example of a request body:

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

更新自定义角色Update a custom role

若要更新自定义角色,请使用角色定义 - 创建或更新 REST API。To update a custom role, use the Role Definitions - Create Or Update REST API. 若要调用此 API,登录时使用的用户必须分配有一个角色,该角色在所有 assignableScopes 上具有 Microsoft.Authorization/roleDefinitions/write 权限。To call this API, you must be signed in with a user that is assigned a role that has the Microsoft.Authorization/roleDefinitions/write permission on all the assignableScopes. 在内置角色中,只有所有者用户访问管理员包含此权限。Of the built-in roles, only Owner and User Access Administrator include this permission.

  1. 使用角色定义 - 列出角色定义 - 获取 REST API 获取有关自定义角色的信息。Use the Role Definitions - List or Role Definitions - Get REST API to get information about the custom role. 有关详细信息,请参阅前面的列出自定义角色部分。For more information, see the earlier List custom roles section.

  2. 从下面的请求开始:Start with the following request:

    PUT https://management.chinacloudapi.cn/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2015-07-01
    
  3. 在 URI 中,将 {scope} 替换为自定义角色的第一个 assignableScopesWithin the URI, replace {scope} with the first assignableScopes of the custom role.

    作用域Scope 类型Type
    subscriptions/{subscriptionId1} 订阅Subscription
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} 资源组Resource group
    providers/Microsoft.Management/managementGroups/{groupId1} 管理组Management group
  4. {roleDefinitionId} 替换为自定义角色的 GUID 标识符。Replace {roleDefinitionId} with the GUID identifier of the custom role.

  5. 根据自定义角色的信息,使用以下格式创建请求正文:Based on the information about the custom role, create a request body with the following format:

    {
      "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. 使用想要对自定义角色所做的更改来更新请求正文。Update the request body with the changes you want to make to the custom role.

    下面显示了已添加新诊断设置操作的请求正文示例:The following shows an example of a request body with a new diagnostic settings action added:

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

删除自定义角色Delete a custom role

若要删除自定义角色,请使用角色定义 - 删除 REST API。To delete a custom role, use the Role Definitions - Delete REST API. 若要调用此 API,登录时使用的用户必须分配有一个角色,该角色在所有 assignableScopes 上具有 Microsoft.Authorization/roleDefinitions/delete 权限。To call this API, you must be signed in with a user that is assigned a role that has the Microsoft.Authorization/roleDefinitions/delete permission on all the assignableScopes. 在内置角色中,只有所有者用户访问管理员包含此权限。Of the built-in roles, only Owner and User Access Administrator include this permission.

  1. 使用角色定义 - 列出角色定义 - 获取 REST API 获取自定义角色的 GUID 标识符。Use the Role Definitions - List or Role Definitions - Get REST API to get the GUID identifier of the custom role. 有关详细信息,请参阅前面的列出自定义角色部分。For more information, see the earlier List custom roles section.

  2. 从下面的请求开始:Start with the following request:

    DELETE https://management.chinacloudapi.cn/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2015-07-01
    
  3. 在 URI 中,将 {scope} 替换为要删除自定义角色的范围。Within the URI, replace {scope} with the scope that you want to delete the custom role.

    作用域Scope 类型Type
    subscriptions/{subscriptionId1} 订阅Subscription
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} 资源组Resource group
    providers/Microsoft.Management/managementGroups/{groupId1} 管理组Management group
  4. {roleDefinitionId} 替换为自定义角色的 GUID 标识符。Replace {roleDefinitionId} with the GUID identifier of the custom role.

后续步骤Next steps