Creare o aggiornare ruoli personalizzati di Azure usando l'API REST

Articolo
12/09/2023

Se i ruoli predefiniti di Azure non soddisfano le esigenze specifiche dell'organizzazione, è possibile creare ruoli personalizzati. Questo articolo descrive come elencare, creare, aggiornare o eliminare ruoli personalizzati usando l'API REST.

Prerequisiti

È necessario usare la versione seguente:

2015-07-01 o versioni successive

Per altre informazioni, vedere Versioni API delle API REST di Controllo degli accessi in base al ruolo di Azure.

Elencare tutte le definizioni di ruolo personalizzate

Per elencare tutte le definizioni di ruolo personalizzate in un tenant, usare l'API REST Definizioni ruolo - Elenco .

L'esempio seguente elenca tutte le definizioni di ruolo personalizzate in un tenant:

Richiesta

GET https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01

Response

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

Elencare tutte le definizioni di ruolo personalizzate in un ambito

Per elencare definizioni di ruolo personalizzate in un ambito, usare l'API REST Definizioni ruolo - Elenco .

Iniziare con la richiesta seguente:

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

All'interno dell'URI sostituire {scope} con l'ambito per il quale elencare i ruoli.

Scope	Tipo
`subscriptions/{subscriptionId1}`	Subscription
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Risorsa
`providers/Microsoft.Management/managementGroups/{groupId1}`	Gruppo di gestione

Sostituire {filter} con il tipo di ruolo.

Filtro	Descrizione
`$filter=type+eq+'CustomRole'`	Filtrare in base al tipo CustomRole

L'esempio seguente elenca tutte le definizioni di ruolo personalizzate in una sottoscrizione:

Richiesta

GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01

Response

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

Elencare una definizione di ruolo personalizzata in base al nome

Per ottenere informazioni su una definizione di ruolo personalizzata in base al nome visualizzato, usare l'API REST Definizioni ruolo - Get .

Iniziare con la richiesta seguente:

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

All'interno dell'URI sostituire {scope} con l'ambito per il quale elencare i ruoli.

Scope	Tipo
`subscriptions/{subscriptionId1}`	Subscription
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Risorsa
`providers/Microsoft.Management/managementGroups/{groupId1}`	Gruppo di gestione

Sostituire {filter} con il nome visualizzato per il ruolo.

Filtro	Descrizione
`$filter=roleName+eq+'{roleDisplayName}'`	Usare il form con codifica URL dell'esatto nome visualizzato del ruolo. Ad esempio: `$filter=roleName+eq+'Virtual%20Machine%20Contributor'`

L'esempio seguente elenca una definizione di ruolo personalizzata denominata Billing Reader Plus in una sottoscrizione:

Richiesta

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

Response

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

Elencare una definizione di ruolo personalizzata in base all'ID

Per ottenere informazioni su una definizione di ruolo personalizzata in base al relativo identificatore univoco, usare l'API REST Definizioni ruolo - Get .

Usare l'API REST Role Definitions - List (Definizione dei ruoli - Elenca) per ottenere l'identificatore del GUID del ruolo.

Iniziare con la richiesta seguente:

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

All'interno dell'URI sostituire {scope} con l'ambito per il quale elencare i ruoli.

Scope	Tipo
`subscriptions/{subscriptionId1}`	Subscription
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Risorsa
`providers/Microsoft.Management/managementGroups/{groupId1}`	Gruppo di gestione

Sostituire {roleDefinitionId} con l'identificatore del GUID della definizione di ruolo.

L'esempio seguente elenca una definizione di ruolo personalizzata con l'identificatore 17adabda-4bf1-4f4e-8c97-1f0cab6dea1c in una sottoscrizione:

Richiesta

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

Response

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

Creare un ruolo personalizzato

Per creare un ruolo personalizzato, usare l'API REST Role Definitions - Create Or Update (Definizione dei ruoli - Crea o Aggiorna). Per chiamare questa API, è necessario aver eseguito l'accesso con un utente a cui è assegnato un ruolo con l'autorizzazione Microsoft.Authorization/roleDefinitions/write per tutti gli oggetti assignableScopes. Tra i ruoli predefiniti, solo proprietario e accesso utente Amministrazione istrator includono questa autorizzazione.

Esaminare l'elenco delle operazioni del provider di risorse disponibili per creare le autorizzazioni per il ruolo personalizzato.
Usare uno strumento GUID per generare un identificatore univoco che verrà usato per l'identificatore del ruolo personalizzato. Il formato dell'identificatore è: 00000000-0000-0000-0000-000000000000

Iniziare con la richiesta e il corpo seguenti:

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

All'interno dell'URI sostituire {scope} con il primo assignableScopes del ruolo personalizzato.

Scope	Tipo
`subscriptions/{subscriptionId1}`	Subscription
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`providers/Microsoft.Management/managementGroups/{groupId1}`	Gruppo di gestione

Sostituire {roleDefinitionId} con l'identificatore del GUID del ruolo personalizzato.
Nel corpo della richiesta sostituire {roleDefinitionId} con l'identificatore GUID.
Se assignableScopes è una sottoscrizione o un gruppo di risorse, sostituire le istanze {subscriptionId} o {resourceGroup} con gli identificatori.
Se assignableScopes è un gruppo di gestione, sostituire l'istanza di {groupId} con l'identificatore del gruppo di gestione.
actions Nella proprietà aggiungere le azioni che il ruolo consente di eseguire.
notActions Nella proprietà aggiungere le azioni escluse dall'oggetto consentitoactions.

Nelle proprietà roleName e description specificare un nome e una descrizione univoci per il ruolo. Per altre informazioni sulle proprietà, vedere Ruoli personalizzati di Azure.

Di seguito è illustrato un esempio di corpo della richiesta:

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

Aggiornare un ruolo personalizzato

Per aggiornare un ruolo personalizzato, usare l'API REST Role Definitions - Create Or Update (Definizione dei ruoli - Crea o Aggiorna). Per chiamare questa API, è necessario accedere con un utente a cui è assegnato un ruolo con l'autorizzazione Microsoft.Authorization/roleDefinitions/write per tutti gli assignableScopesoggetti , ad esempio Accesso utente Amministrazione istrator.

Per ottenere informazioni sul ruolo personalizzato, usare l'API REST Role Definitions - List (Definizione dei ruoli - Elenca) o Role Definitions - Get (Definizione dei ruoli - Ottieni). Per altre informazioni, vedere la sezione Elencare tutte le definizioni di ruolo personalizzate in precedenza.

Iniziare con la richiesta seguente:

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

All'interno dell'URI sostituire {scope} con il primo assignableScopes del ruolo personalizzato.

Scope	Tipo
`subscriptions/{subscriptionId1}`	Subscription
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`providers/Microsoft.Management/managementGroups/{groupId1}`	Gruppo di gestione

Sostituire {roleDefinitionId} con l'identificatore del GUID del ruolo personalizzato.

In base alle informazioni sul ruolo personalizzato, creare un corpo della richiesta con il formato seguente:

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

Aggiornare il corpo della richiesta con le modifiche che si vogliono apportare al ruolo personalizzato.

Di seguito è illustrato un esempio di corpo della richiesta a cui è stata aggiunta una nuova azione di impostazioni di diagnostica:

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

Eliminare un ruolo personalizzato

Per eliminare un ruolo personalizzato, usare l'API REST Role Definitions - Delete (Definizione dei ruoli - Elimina). Per chiamare questa API, è necessario aver eseguito l'accesso con un utente a cui è assegnato un ruolo con l'autorizzazione Microsoft.Authorization/roleDefinitions/delete per tutti gli oggetti assignableScopes. Tra i ruoli predefiniti, solo proprietario e accesso utente Amministrazione istrator includono questa autorizzazione.

Rimuovere tutte le assegnazioni di ruolo che usano il ruolo personalizzato. Per altre informazioni, vedere Trovare assegnazioni di ruolo per eliminare un ruolo personalizzato.
Per ottenere informazioni sull'identificatore del GUID del ruolo personalizzato, usare l'API REST Role Definitions - List (Definizione dei ruoli - Elenca) o Role Definitions - Get (Definizione dei ruoli - Ottieni). Per altre informazioni, vedere la sezione Elencare tutte le definizioni di ruolo personalizzate in precedenza.

Iniziare con la richiesta seguente:

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

All'interno dell'URI sostituire {scope} con l'ambito in cui si vuole eliminare il ruolo personalizzato.

Scope	Tipo
`subscriptions/{subscriptionId1}`	Subscription
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`providers/Microsoft.Management/managementGroups/{groupId1}`	Gruppo di gestione

Sostituire {roleDefinitionId} con l'identificatore del GUID del ruolo personalizzato.

Creare o aggiornare ruoli personalizzati di Azure usando l'API REST

Prerequisiti

Elencare tutte le definizioni di ruolo personalizzate

Elencare tutte le definizioni di ruolo personalizzate in un ambito

Elencare una definizione di ruolo personalizzata in base al nome

Elencare una definizione di ruolo personalizzata in base all'ID

Creare un ruolo personalizzato

Aggiornare un ruolo personalizzato

Eliminare un ruolo personalizzato

Passaggi successivi

Risorse aggiuntive