REST API を使用して Azure カスタム ロールを作成または更新する

Azure の組み込みロールが組織の特定のニーズを満たさない場合は、独自のカスタム ロールを作成することができます。 この記事では、REST API を使用してカスタムロールを一覧表示、作成、更新、または削除する方法について説明します。

前提条件

次のバージョンを使用する必要があります。

  • 2015-07-01 以降

詳細については、Azure RBAC REST API の API バージョンに関するページを参照してください。

カスタム ロールの定義をすべて一覧表示する

テナント内のカスタム ロールの定義をすべて一覧表示するには、Role Definitions - List REST API を使用します。

  • 次の例では、テナント内のカスタム ロールの定義をすべて一覧表示します。

    Request

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

あるスコープのカスタム ロールの定義をすべて一覧表示する

あるスコープのカスタム ロールの定義をすべて一覧表示するには、Role Definitions - List REST API を使用します。

  1. 次の要求から開始します。

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01
    
  2. URI 内の {scope} は、ロールを一覧表示するスコープに置き換えます。

    Scope Type
    subscriptions/{subscriptionId1} サブスクリプション
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Resource group
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} リソース
    providers/Microsoft.Management/managementGroups/{groupId1} 管理グループ
  3. {filter} をロールの種類に置き換えます。

    フィルター 説明
    $filter=type+eq+'CustomRole' CustomRole 型に基づいてフィルター処理する

    次の例では、サブスクリプションのカスタム ロールの定義をすべて一覧表示します。

    Request

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

名前によるカスタム ロール定義の一覧表示

カスタム ロールの定義に関する情報を表示名によって取得するには、Role Definitions - Get REST API を使用します。

  1. 次の要求から開始します。

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01
    
  2. URI 内の {scope} は、ロールを一覧表示するスコープに置き換えます。

    Scope Type
    subscriptions/{subscriptionId1} サブスクリプション
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Resource group
    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 という名前のカスタム ロールの定義を一覧表示します。

    Request

    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 によるカスタム ロール定義の一覧表示

カスタム ロールの定義に関する情報を一意識別子によって取得するには、Role Definitions - Get 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} は、ロールを一覧表示するスコープに置き換えます。

    Scope Type
    subscriptions/{subscriptionId1} サブスクリプション
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Resource group
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} リソース
    providers/Microsoft.Management/managementGroups/{groupId1} 管理グループ
  4. {roleDefinitionId} は、ロールの定義の GUID 識別子に置き換えます。

    次の例では、サブスクリプションの識別子 17adabda-4bf1-4f4e-8c97-1f0cab6dea1c を持つカスタム ロールの定義を一覧表示します。

    Request

    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} は、カスタム ロールの 1 つ目の assignableScopes に置き換えます。

    Scope Type
    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. 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/*",
              "Microsoft.Support/*"
            ],
            "notActions": []
          }
        ],
        "assignableScopes": [
          "/subscriptions/00000000-0000-0000-0000-000000000000",
          "/providers/Microsoft.Management/managementGroups/marketing-group"
        ]
      }
    }
    

カスタム ロールの更新

カスタム ロールを更新するには、ロールの定義 - 作成または更新 REST API を使用します。 この API を呼び出すには、すべてのassignableScopesアクセス許可を持つMicrosoft.Authorization/roleDefinitions/writeロールが割り当てられているユーザー (User Access 管理istrator など) でサインインする必要があります。

  1. カスタム ロールに関する情報を取得するには、ロールの定義 - 一覧表示またはロールの定義 - 取得 REST API を使用します。 詳細については、先ほどの「すべてのカスタム ロールの定義を一覧表示する」セクションをご覧ください。

  2. 次の要求から開始します。

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01
    
  3. URI 内の {scope} は、カスタム ロールの 1 つ目の assignableScopes に置き換えます。

    Scope Type
    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. カスタム ロールの GUID 識別子を取得するには、ロールの定義 - 一覧表示またはロールの定義 - 取得 REST API を使用します。 詳細については、先ほどの「すべてのカスタム ロールの定義を一覧表示する」セクションをご覧ください。

  3. 次の要求から開始します。

    DELETE https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01
    
  4. URI 内の {scope} は、カスタム ロールを削除するスコープに置き換えます。

    Scope Type
    subscriptions/{subscriptionId1} サブスクリプション
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} リソース グループ
    providers/Microsoft.Management/managementGroups/{groupId1} 管理グループ
  5. {roleDefinitionId} は、カスタム ロールの GUID 識別子に置き換えます。

次のステップ