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

[アーティクル]
12/01/2023

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 を使用します。

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

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01

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}`	管理グループ

{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 を使用します。

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

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01

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}`	管理グループ

{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 を使用します。

ロールの定義 - 一覧表示 REST API を使用して、ロールの GUID 識別子を取得します。

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

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

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}`	管理グループ

{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 アクセス許可を保持するロールに割り当てられたユーザーを使って、サインインする必要があります。組み込みのロールのうち、所有者とユーザーアクセス管理者のみに、このアクセス許可が含まれています。

カスタムロールのアクセス許可の作成に使用可能なリソースプロバイダー操作の一覧を確認します。
GUID ツールを使用し、カスタムロール識別子に使用する一意の識別子を生成します。この識別子の形式は 00000000-0000-0000-0000-000000000000 になります。

次の要求と本文から開始します。

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

URI 内の {scope} は、カスタムロールの 1 つ目の assignableScopes に置き換えます。

Scope	Type
`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/*",
          "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 など) でサインインする必要があります。

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

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

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

URI 内の {scope} は、カスタムロールの 1 つ目の assignableScopes に置き換えます。

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

カスタムロールの削除

カスタムロールを削除するには、ロールの定義 - 削除 REST API を使用します。この API を呼び出すには、すべての assignableScopes に対して Microsoft.Authorization/roleDefinitions/delete アクセス許可を保持するロールに割り当てられたユーザーを使って、サインインする必要があります。組み込みのロールのうち、所有者とユーザーアクセス管理者のみに、このアクセス許可が含まれています。

カスタムロールを使用しているロールの割り当てをすべて削除します。詳細については、「カスタムロールを削除するロールの割り当てを検索する」を参照してください。
カスタムロールの GUID 識別子を取得するには、ロールの定義 - 一覧表示またはロールの定義 - 取得 REST API を使用します。詳細については、先ほどの「すべてのカスタムロールの定義を一覧表示する」セクションをご覧ください。

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

DELETE https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

URI 内の {scope} は、カスタムロールを削除するスコープに置き換えます。

Scope	Type
`subscriptions/{subscriptionId1}`	サブスクリプション
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	リソースグループ
`providers/Microsoft.Management/managementGroups/{groupId1}`	管理グループ

{roleDefinitionId} は、カスタムロールの GUID 識別子に置き換えます。

次の方法で共有

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

前提条件

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

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

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

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

カスタムロールを作成する

カスタムロールの更新

カスタムロールの削除

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

前提条件

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

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

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

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

カスタム ロールを作成する

カスタム ロールの更新

カスタム ロールの削除

次のステップ

フィードバック

その他のリソース

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

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

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

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

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

カスタムロールを作成する

カスタムロールの更新

カスタムロールの削除