使用 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'

    下列範例會列出訂用帳戶中名為「計費讀者加號」的自訂角色定義：

    要求

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

依識別碼列出自訂角色定義

若要依其唯一識別碼取得自訂角色定義的相關資訊，請使用 角色定義 - 取得 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 的使用者登入。 在內建角色中，只有 擁有者和 使用者存取管理員istrator 才包含此許可權。

  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. 在 和 description 屬性中 roleName ，指定唯一的角色名稱和描述。 如需屬性的詳細資訊，請參閱 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 的使用者登入。 在內建角色中，只有 擁有者和 使用者存取管理員istrator 才包含此許可權。

  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 識別碼。

下一步