Struttura delle definizioni di criteri di Azure

Criteri di Azure stabilisce le convenzioni per le risorse. Le definizioni di criteri descrivono le condizioni di conformità delle risorse e l'effetto da eseguire se viene soddisfatta una condizione. Una condizione confronta un valore o un campo proprietà della risorsa con un valore richiesto. È possibile accedere ai campi delle proprietà delle risorse usando alias. Quando un campo proprietà della risorsa è una matrice, è possibile usare un alias di matrice speciale per selezionare i valori di tutti i membri della matrice e applicare una condizione a ognuno. Altre informazioni sulle condizioni.

Definendo le convenzioni, è possibile controllare i costi e gestire più facilmente le risorse. È ad esempio possibile specificare che vengano consentiti solo determinati tipi di macchine virtuali. In alternativa, è possibile richiedere che le risorse abbiano un tag specifico. Le assegnazioni dei criteri vengono ereditate dalle risorse figlio. Se un'assegnazione dei criteri viene applicata a un gruppo di risorse, è applicabile a tutte le risorse in tale gruppo.

Lo schema policy definitionRule (Criteri di definizione dei criteri) è disponibile qui: https://schema.management.azure.com/schemas/2020-10-01/policyDefinition.json

Per creare una definizione di criterio è possibile usare JSON. La definizione dei criteri contiene gli elementi per:

  • nome visualizzato
  • description
  • mode
  • metadata
  • parametri
  • regola dei criteri
    • valutazione logica
    • effetto

Ad esempio, la notazione JSON seguente illustra un criterio che limita i punti in cui vengono distribuite le risorse:

{
    "properties": {
        "displayName": "Allowed locations",
        "description": "This policy enables you to restrict the locations your organization can specify when deploying resources.",
        "mode": "Indexed",
        "metadata": {
            "version": "1.0.0",
            "category": "Locations"
        },
        "parameters": {
            "allowedLocations": {
                "type": "array",
                "metadata": {
                    "description": "The list of locations that can be specified when deploying resources",
                    "strongType": "location",
                    "displayName": "Allowed locations"
                },
                "defaultValue": [ "westus2" ]
            }
        },
        "policyRule": {
            "if": {
                "not": {
                    "field": "location",
                    "in": "[parameters('allowedLocations')]"
                }
            },
            "then": {
                "effect": "deny"
            }
        }
    }
}

Criteri di Azure modelli e incorporati si trovano in Criteri di Azure esempi.

Nome visualizzato e descrizione

Usare displayName e description per identificare la definizione dei criteri e fornire il contesto d'uso. displayName ha una lunghezza massima di 128 caratteri e description una lunghezza massima di 512 caratteri.

Nota

Durante la creazione o l'aggiornamento di una definizione dei criteri, ID, tipo e nome sono definiti dalle proprietà esterne a JSON e non sono necessari nel file JSON. Il recupero della definizione dei criteri tramite SDK restituisce le proprietà id, tipo e nome come parte di JSON, ma ognuna è costituita da informazioni di sola lettura correlate alla definizione dei criteri.

Tipo

Anche se la proprietà type non può essere impostata, esistono tre valori restituiti dall'SDK e visibili nel portale:

  • Builtin: queste definizioni di criteri vengono fornite e gestite da Microsoft.
  • Custom: tutte le definizioni dei criteri create dai clienti hanno questo valore.
  • Static: indica una definizione dei criteri di conformità alle normative con proprietà Microsoft. I risultati della conformità per queste definizioni di criteri sono i risultati dei controlli di terze parti nell'infrastruttura Microsoft. Nel portale di Azure questo valore viene talvolta visualizzato come gestito da Microsoft. Per altre informazioni, vedere Responsabilità condivisa nel cloud.

Mode

La modalità viene configurata in base al fatto che i criteri siano destinati a una proprietà di Azure Resource Manager o a una proprietà del provider di risorse.

Modalità di Resource Manager

La modalità determina quali tipi di risorsa vengono valutati per una definizione di criteri. Le modalità supportate sono:

  • all: vengono valutati i gruppi di risorse, le sottoscrizioni e tutti i tipi di risorse
  • indexed: vengono valutati solo i tipi di risorse che supportano tag e il percorso

Ad esempio, la risorsa Microsoft.Network/routeTables supporta i tag e il percorso e viene valutata in entrambe le modalità. Tuttavia, la risorsa Microsoft.Network/routeTables/routes non può essere contrassegnata e non viene valutata in modalità Indexed.

Nella maggior parte dei casi, è consigliabile impostare il parametro mode su all. Tutte le definizioni di criteri create tramite il portale usano la modalità all. Se si usa PowerShell o l'interfaccia della riga di comando di Azure è necessario specificare il parametro mode manualmente. Se la definizione dei criteri non include un valore mode, assume il valore predefinito all in Azure PowerShell e null nell'interfaccia della riga di comando di Azure. Una null modalità è uguale a quella usata indexed per supportare la compatibilità con le versioni precedenti.

indexed deve essere usato durante la creazione di criteri che applicano tag o percorsi. Sebbene non sia necessario, evita che le risorse che non supportano tag e percorsi vengano visualizzate come non conformi nei risultati sulla conformità. L'eccezione è rappresentata dai gruppi di risorse e dalle sottoscrizioni. Per le definizioni dei criteri che applicano percorsi o tag a un gruppo di risorse o a una sottoscrizione, impostare il parametro mode su all e specificare una destinazione specifica per il tipo Microsoft.Resources/subscriptions/resourceGroups o Microsoft.Resources/subscriptions. Per un esempio, vedere Modello: Tag - Esempio n. 1. Per un elenco di risorse che supportano i tag, vedere Supporto dei tag per le risorse di Azure.

Modalità provider di risorse

Le modalità del provider di risorse seguenti sono completamente supportate:

  • Microsoft.Kubernetes.Data per la gestione di cluster e componenti Kubernetes, ad esempio pod, contenitori e ingresso. Supportato per i cluster servizio Azure Kubernetes e i cluster Kubernetes abilitati per Azure Arc. Le definizioni che usano questa modalità Provider di risorse usano il controllo degli effetti, nega e disabilitato.
  • Microsoft.KeyVault.Data per la gestione di insiemi di credenziali e certificati in Azure Key Vault. Per altre informazioni su queste definizioni di criteri, vedere Integrare Azure Key Vault con Criteri di Azure.

Le modalità del provider di risorse seguenti sono attualmente supportate come anteprima:

  • Microsoft.Network.Dataper la gestione dei criteri di appartenenza personalizzati di Azure Rete virtuale Manager tramite Criteri di Azure.
  • Microsoft.ManagedHSM.Dataper la gestione delle chiavi HSM gestite tramite Criteri di Azure.

Nota

Se non specificato in modo esplicito, le modalità provider di risorse supportano solo le definizioni di criteri predefinite e le esenzioni non sono supportate a livello di componente.

Metadati

La proprietà facoltativa archivia metadata informazioni sulla definizione dei criteri. I clienti possono definire proprietà e valori utili per l'organizzazione in metadata. Esistono tuttavia alcune proprietà comuni usate da Criteri di Azure e nelle funzionalità predefinite. Ogni metadata proprietà ha un limite di 1024 caratteri.

Proprietà comuni dei metadati

  • version (stringa): tiene traccia dei dettagli sulla versione del contenuto di una definizione di criteri.
  • category(stringa): determina in quale categoria nella portale di Azure viene visualizzata la definizione del criterio.
  • preview (booleano): flag True o false per se la definizione dei criteri è in anteprima.
  • deprecated (booleano): flag True o false per se la definizione dei criteri è stata contrassegnata come deprecata.
  • portalReview (stringa): determina se i parametri devono essere esaminati nel portale, indipendentemente dall'input richiesto.

Nota

Il servizio Criteri di Azure usa le proprietà version, preview e deprecated per fornire il livello di modifica a una definizione o un'iniziativa di criteri predefinita e uno stato. Il formato di version è: {Major}.{Minor}.{Patch}. Gli stati specifici, ad esempio deprecato o anteprima, vengono aggiunti alla proprietà version o a un'altra proprietà come booleano. Per altre informazioni sul modo in cui Criteri di Azure versioni predefinite, vedere Controllo delle versioni predefinite. Per altre informazioni sul significato di un criterio da deprecare o in anteprima, vedere Criteri di anteprima e deprecati.

Parametri

I parametri consentono di semplificare la gestione dei criteri, riducendone il numero di definizioni. Si pensi a parametri come i campi in un modulo , name, address, citystate. Questi parametri rimangono sempre invariati, ma i loro valori cambiano a seconda dei dati immessi durante la compilazione del modulo da parte dei singoli utenti. I parametri funzionano nello stesso modo durante la creazione di criteri. L'inclusione dei parametri in una definizione dei criteri consente di riutilizzare i singoli criteri in vari scenari mediante l'uso di valori diversi.

Nota

I parametri possono essere aggiunti a una definizione esistente e assegnata. Il nuovo parametro deve includere la proprietà defaultValue. In questo modo le assegnazioni esistenti dei criteri o dell'iniziativa non possono essere rese indirettamente non valide.

Proprietà parametro

Un parametro presenta le proprietà seguenti, usate nella definizione di criteri:

  • name: nome del parametro. Usato dalla funzione di distribuzione parameters all'interno della regola dei criteri. Per altre informazioni, vedere Usare un valore di parametro.
  • type: Determina se il parametro è una stringa, matrice, oggetto, booleano, intero, float o datetime.
  • metadata: definisce le sottoproprietà usate principalmente dal portale di Azure per visualizzare informazioni di tipo descrittivo:
    • description: la spiegazione di ciò per cui viene usato il parametro. Può essere usata per fornire esempi di valori accettabili.
    • displayName: il nome descrittivo visualizzato per il parametro nel portale.
    • strongType: (facoltativa) usata quando si assegna la definizione di criteri tramite portale. Fornisce un elenco con riconoscimento del contesto. Per altre informazioni, vedere strongType.
    • assignPermissions: (Facoltativo) Impostare come true per consentire al portale di Azure di creare assegnazioni di ruolo durante l'assegnazione dei criteri. Questa proprietà è utile nel caso in cui si desideri assegnare autorizzazioni al di fuori dell'ambito di assegnazione. Esiste un'assegnazione di ruolo per ogni definizione di ruolo nei criteri (o per definizione di ruolo in tutti i criteri dell'iniziativa). Il valore del parametro deve essere una risorsa o un ambito valido.
  • defaultValue: (facoltativa) imposta il valore del parametro in un'assegnazione se non viene specificato alcun valore. Obbligatoria quando si aggiorna una definizione di criteri esistente già assegnata. Per i parametri di tipo oject, il valore deve corrispondere allo schema appropriato.
  • allowedValues: (Facoltativo) Fornisce una matrice di valori accettati dal parametro durante l'assegnazione. I confronti di valori consentiti fanno distinzione tra maiuscole e minuscole. Per i parametri di tipo oject, i valori devono corrispondere allo schema appropriato.
  • schema: (Facoltativo) Fornisce la convalida degli input dei parametri durante l'assegnazione usando uno schema JSON autodefi definito. Questa proprietà è supportata solo per i parametri di tipo oggetto e segue l'implementazione dello schema Json.NET 2019-09. Per altre informazioni sull'uso degli schemi, vedere https://json-schema.org/ e testare gli schemi bozza all'indirizzo https://www.jsonschemavalidator.net/.

Parametri di esempio

Esempio 1

Ad esempio, è possibile definire una definizione di criteri per limitare i percorsi in cui le risorse possono essere distribuite. Un parametro per questa definizione di criteri potrebbe essere allowedLocations. Questo parametro è stato usato da ogni assegnazione della definizione di criteri per limitare i valori accettati. L'uso di strongType offre un'esperienza migliorata nel completamento dell'assegnazione tramite portale:

"parameters": {
    "allowedLocations": {
        "type": "array",
        "metadata": {
            "description": "The list of allowed locations for resources.",
            "displayName": "Allowed locations",
            "strongType": "location"
        },
        "defaultValue": [ "westus2" ],
        "allowedValues": [
            "eastus2",
            "westus2",
            "westus"
        ]
    }
}

Un input di esempio per questo parametro di tipo matrice (senza strongType) in fase di assegnazione potrebbe essere ["westus", "eastus2"].

Esempio 2

In uno scenario più avanzato, è possibile definire un criterio che richiede pod del cluster Kubernetes per l'uso di etichette specificate. Un parametro per tale definizione di criteri può essere labelSelector, che verrebbe usato da ogni assegnazione della definizione dei criteri per specificare le risorse Kubernetes in questione in base alle chiavi e ai valori delle etichette:

"parameters": {
    "labelSelector": {
        "type": "Object",
        "metadata": {
            "displayName": "Kubernetes label selector",
            "description": "Label query to select Kubernetes resources for policy evaluation. An empty label selector matches all Kubernetes resources."
        },
        "defaultValue": {},
        "schema": {
            "description": "A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all resources.",
            "type": "object",
            "properties": {
                "matchLabels": {
                    "description": "matchLabels is a map of {key,value} pairs.",
                    "type": "object",
                    "additionalProperties": {
                        "type": "string"
                    },
                    "minProperties": 1
                },
                "matchExpressions": {
                    "description": "matchExpressions is a list of values, a key, and an operator.",
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "key": {
                                "description": "key is the label key that the selector applies to.",
                                "type": "string"
                            },
                            "operator": {
                                "description": "operator represents a key's relationship to a set of values.",
                                "type": "string",
                                "enum": [
                                    "In",
                                    "NotIn",
                                    "Exists",
                                    "DoesNotExist"
                                ]
                            },
                            "values": {
                                "description": "values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty.",
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            }
                        },
                        "required": [
                            "key",
                            "operator"
                        ],
                        "additionalProperties": false
                    },
                    "minItems": 1
                }
            },
            "additionalProperties": false
        }
    },
}

Un input di esempio per questo parametro di tipo oggetto in fase di assegnazione sarà in formato JSON, convalidato dallo schema specificato e potrebbe essere:

{
    "matchLabels": {
        "poolID": "abc123",
        "nodeGroup": "Group1",
        "region": "southcentralus"
    },
    "matchExpressions": [
        {
            "key": "name",
            "operator": "In",
            "values": ["payroll", "web"]
        },
        {
            "key": "environment",
            "operator": "NotIn",
            "values": ["dev"]
        }
    ]
}

Usare un valore di parametro

Nella regola dei criteri, fare riferimento ai parametri con la sintassi della funzione parameters seguente:

{
    "field": "location",
    "in": "[parameters('allowedLocations')]"
}

Questo esempio fa riferimento al parametro allowedLocations illustrato nella sezione relativa alle proprietà dei parametri.

strongType

All'interno della metadata proprietà è possibile usare strongType per fornire un elenco di opzioni a selezione multipla all'interno del portale di Azure. strongType può essere un tipo di risorsa supportato o un valore consentito. Per determinare se un tipo di risorsa è valido per strongType, usare Get-AzResourceProvider. Il formato per un tipo di risorsastrongType è <Resource Provider>/<Resource Type>. Ad esempio, Microsoft.Network/virtualNetworks/subnets.

Alcuni tipi di risorse non restituiti da Get-AzResourceProvider sono supportati. Questi tipi sono:

  • Microsoft.RecoveryServices/vaults/backupPolicies

I valori non tipo di risorsa consentiti per strongType sono:

  • location
  • resourceTypes
  • storageSkus
  • vmSKUs
  • existingResourceGroups

Posizione della definizione

Durante la creazione di iniziative o criteri è importante specificare la posizione della definizione. La posizione della definizione deve essere specificata come un gruppo di gestione o una sottoscrizione. Tale posizione determina l'ambito al quale la definizione delle iniziative o dei criteri può essere assegnata. Le risorse devono essere membri diretti o elementi figli all'interno della gerarchia della posizione della definizione da destinare all'assegnazione.

Se la posizione della definizione è:

  • Sottoscrizione: è possibile assegnare alla definizione dei criteri solo le risorse all'interno della sottoscrizione.
  • Gruppo di gestione : è possibile assegnare alla definizione dei criteri solo le risorse all'interno dei gruppi di gestione figlio e delle sottoscrizioni figlio. Se si prevede di applicare la definizione dei criteri a più sottoscrizioni, il percorso deve essere un gruppo di gestione che contiene ogni sottoscrizione.

Per altre informazioni, vedere Informazioni sull'ambito in Criteri di Azure.

Regola dei criteri

La regola dei criteri è costituita dai blocchi If e Then blocchi. Nel blocco If, si definiscono una o più condizioni che specificano quando i criteri vengono applicati. È possibile applicare gli operatori logici a queste condizioni per definire con precisione lo scenario di un criterio.

Nel blocco Then si definisce l'effetto che si verifica quando le condizioni If sono soddisfatte.

{
    "if": {
        <condition> | <logical operator>
    },
    "then": {
        "effect": "deny | audit | modify | append | auditIfNotExists | deployIfNotExists | disabled"
    }
}

Operatori logici

Gli operatori logici supportati sono:

  • "not": {condition or operator}
  • "allOf": [{condition or operator},{condition or operator}]
  • "anyOf": [{condition or operator},{condition or operator}]

La sintassi not inverte il risultato della condizione. La sintassi allOf (simile all'operazione logica And) richiede che tutte le condizioni siano vere. La sintassi anyOf (simile all'operazione logica Or) richiede che una o più condizioni siano vere.

È possibile annidare gli operatori logici. L'esempio seguente illustra un'operazione not nidificata in un'operazione allOf.

"if": {
    "allOf": [{
            "not": {
                "field": "tags",
                "containsKey": "application"
            }
        },
        {
            "field": "type",
            "equals": "Microsoft.Storage/storageAccounts"
        }
    ]
},

Condizioni

Una condizione valuta se un valore soddisfa determinati criteri. Le condizioni supportate sono:

  • "equals": "stringValue"
  • "notEquals": "stringValue"
  • "like": "stringValue"
  • "notLike": "stringValue"
  • "match": "stringValue"
  • "matchInsensitively": "stringValue"
  • "notMatch": "stringValue"
  • "notMatchInsensitively": "stringValue"
  • "contains": "stringValue"
  • "notContains": "stringValue"
  • "in": ["stringValue1","stringValue2"]
  • "notIn": ["stringValue1","stringValue2"]
  • "containsKey": "keyName"
  • "notContainsKey": "keyName"
  • "less": "dateValue" | "less": "stringValue" | "less": intValue
  • "lessOrEquals": "dateValue" | "lessOrEquals": "stringValue" | "lessOrEquals": intValue
  • "greater": "dateValue" | "greater": "stringValue" | "greater": intValue
  • "greaterOrEquals": "dateValue" | "greaterOrEquals": "stringValue" | "greaterOrEquals": intValue
  • "exists": "bool"

Per less, lessOrEquals, greater e greaterOrEquals, se il tipo di proprietà non corrisponde al tipo di condizione, viene generato un errore. I confronti tra stringhe vengono eseguiti usando InvariantCultureIgnoreCase.

Quando si usano le condizioni like e notLike, è possibile inserire un carattere jolly * nel valore. Il valore non deve contenere più di un carattere jolly *.

Quando si usano le condizioni match e notMatch, specificare # per rappresentare una cifra, ? per rappresentare una lettera, . per rappresentare tutti i caratteri e qualunque altro carattere per rappresentare il carattere effettivo. Anche se la corrispondenza e la notMatch fanno distinzione tra maiuscole e minuscole, tutte le altre condizioni che valutano un valore stringValue non fanno distinzione tra maiuscole e minuscole. Alternative senza distinzione tra maiuscole e minuscole sono disponibili in matchInsensitively e notMatchInsensitively.

Campi

Le condizioni che valutano se i valori delle proprietà nel payload della richiesta di risorsa soddisfano determinati criteri possono essere formati usando un'espressione di campo . Sono supportati i seguenti campi:

  • name
  • fullName
    • Restituisce il nome completo della risorsa. Il nome completo di una risorsa è il nome della risorsa con anteposti gli eventuali nomi delle risorse padre (ad esempio "myServer/myDatabase").
  • kind
  • type
  • location
    • I campi di posizione vengono normalizzati per supportare vari formati. Ad esempio, East US 2 è considerato uguale a eastus2.
    • Usare global per le risorse che sono indipendenti dalla posizione.
  • id
    • Restituisce l'ID risorsa della risorsa da valutare.
    • Esempio: /subscriptions/06be863d-0996-4d56-be22-384767287aa2/resourceGroups/myRG/providers/Microsoft.KeyVault/vaults/myVault
  • identity.type
  • tags
  • tags['<tagName>']
    • Questa sintassi tra parentesi quadre supporta nomi di tag con segni di punteggiatura, ad esempio un trattino, punti o spazi.
    • Dove <tagName> è il nome del tag per il quale convalidare la condizione.
    • Esempi: tags['Acct.CostCenter'] dove Acct.CostCenter è il nome del tag.
  • tags['''<tagName>''']
    • Questa sintassi tra parentesi quadre supporta nomi di tag contenenti apostrofi eseguendo l'escape con esso in caratteri di escape con apostrofi doppi.
    • Dove '<tagName>' è il nome del tag per il quale convalidare la condizione.
    • Esempio: tags['''My.Apostrophe.Tag'''] dove 'My.Apostrophe.Tag' è il nome del tag.
  • alias delle proprietà; per un elenco, vedere alias.

Nota

tags.<tagName>, tags[tagName] e tags[tag.with.dots] sono comunque modi accettabili per dichiarare un campo tags. Tuttavia, le espressioni preferibili sono quelle elencate in precedenza.

Nota

Nelle espressioni di campo che fanno riferimento all'alias [*] ogni elemento della matrice viene valutato singolarmente con elementi logici e tra gli elementi. Per altre informazioni, vedere Riferimento alle proprietà delle risorse della matrice.

Usare tag con parametri

È possibile passare a un campo di tag un valore di parametro. Passare un parametro a un campo di tag aumenta la flessibilità della definizione dei criteri durante l'assegnazione dei criteri.

Nell'esempio seguente, concat viene usato per creare una ricerca nei campi di tag per il tag che ha come nome il valore del parametro tagName. Se il tag non esiste, viene usato l'effetto modify per aggiungere il tag usando il valore del tag con lo stesso nome impostato sul gruppo di risorse padre delle risorse controllate tramite la funzione di ricerca resourcegroup().

{
    "if": {
        "field": "[concat('tags[', parameters('tagName'), ']')]",
        "exists": "false"
    },
    "then": {
        "effect": "modify",
        "details": {
            "operations": [{
                "operation": "add",
                "field": "[concat('tags[', parameters('tagName'), ']')]",
                "value": "[resourcegroup().tags[parameters('tagName')]]"
            }],
            "roleDefinitionIds": [
                "/providers/microsoft.authorization/roleDefinitions/4a9ae827-6dc8-4573-8ac7-8239d42aa03f"
            ]
        }
    }
}

valore

Condizioni che valutano se un valore soddisfa determinati criteri possono essere formate usando un'espressione di valore . I valori possono essere valori letterali, i valori dei parametri o i valori restituiti di qualsiasi funzione di modello supportata.

Avviso

Se il risultato di una funzione modello è un errore, la valutazione dei criteri non riesce. Una valutazione non riuscita è un risultato deny implicito. Per altre informazioni, vedere come evitare errori dei modelli. Usare enforcementMode di DoNotEnforce per evitare l'effetto di una valutazione non riuscita su risorse nuove o aggiornate durante il test e la convalida di una nuova definizione dei criteri.

Esempi d'uso di value

Questa regola dei criteri usa value per confrontare il risultato della funzione resourceGroup() e la proprietà restituita name rispetto a una condizione like di *netrg. La regola nega qualsiasi risorsa non del tipo in alcun gruppo di risorse il Microsoft.Network/* cui nome termina in .*netrg

{
    "if": {
        "allOf": [{
                "value": "[resourceGroup().name]",
                "like": "*netrg"
            },
            {
                "field": "type",
                "notLike": "Microsoft.Network/*"
            }
        ]
    },
    "then": {
        "effect": "deny"
    }
}

Questa regola dei criteri usa value per verificare se il risultato di più funzioni annidate corrisponde a equalstrue. La regola respinge qualsiasi risorsa che non dispone di almeno tre tag.

{
    "mode": "indexed",
    "policyRule": {
        "if": {
            "value": "[less(length(field('tags')), 3)]",
            "equals": "true"
        },
        "then": {
            "effect": "deny"
        }
    }
}

Evitare gli errori dei modelli

L'uso di funzioni modello in value consente numerose funzioni annidate complesse. Se il risultato di una funzione modello è un errore, la valutazione dei criteri non riesce. Una valutazione non riuscita è un risultato deny implicito. Un esempio di value che ha esito negativo in determinati scenari:

{
    "policyRule": {
        "if": {
            "value": "[substring(field('name'), 0, 3)]",
            "equals": "abc"
        },
        "then": {
            "effect": "audit"
        }
    }
}

La regola dei criteri di esempio precedente usa substring() per confrontare i primi tre caratteri di name con abc. Se name è più breve di tre caratteri, la funzione substring() genera un errore. Questo errore fa sì che il criterio diventi un effetto deny.

Usare invece la funzione if() per verificare se i primi tre caratteri di name sono uguali ad abc senza consentire che un name più breve di tre caratteri generi un errore:

{
    "policyRule": {
        "if": {
            "value": "[if(greaterOrEquals(length(field('name')), 3), substring(field('name'), 0, 3), 'not starting with abc')]",
            "equals": "abc"
        },
        "then": {
            "effect": "audit"
        }
    }
}

Con la regola dei criteri modificata, if() controlla la lunghezza di name prima di provare a ottenere un substring() su un valore con meno di tre caratteri. Se name è troppo breve, viene invece restituito il valore "not starting with abc" e viene confrontato con abc. Una risorsa con un nome breve che non inizia con abc non soddisfa ancora la regola dei criteri, ma non causa più un errore durante la valutazione.

Conteggio

Condizioni che contano il numero di membri di una matrice che soddisfano determinati criteri possono essere formate usando un'espressione count . Gli scenari comuni verificano se "almeno uno di", "esattamente uno di", "tutti" o "nessuno dei membri della matrice" soddisfano una condizione. Count valuta ogni membro della matrice per un'espressione di condizione e somma i risultati true , che vengono quindi confrontati con l'operatore di espressione.

Conteggio campi

Contare il numero di membri di una matrice nel payload della richiesta che soddisfano un'espressione di condizione. La struttura delle espressioni di conteggio dei campi è:

{
    "count": {
        "field": "<[*] alias>",
        "where": {
            /* condition expression */
        }
    },
    "<condition>": "<compare the count of true condition expression array members to this value>"
}

Le proprietà seguenti vengono usate con il conteggio dei campi:

  • count.field (obbligatorio): Contiene il percorso della matrice e deve essere un alias di matrice.
  • count.where (facoltativo): espressione della condizione da valutare singolarmente per ogni membro della matrice alias [*] di count.field. Se questa proprietà non viene specificata, tutti i membri della matrice con il percorso di 'campo' vengono valutati su true. All'interno di questa proprietà è possibile usare qualunque condizione. Gli operatori logici possono essere usati all'interno di questa proprietà per creare requisiti di valutazione complessi.
  • <condizione> (obbligatorio): Il valore viene confrontato con il numero di elementi che soddisfano l'espressione della condizione count.where. È necessario usare una condizione numerica.

Per altre informazioni su come usare le proprietà della matrice in Criteri di Azure, inclusa una spiegazione dettagliata su come viene valutata l'espressione del conteggio dei campi, vedere Riferimento alle proprietà delle risorse della matrice.

Conteggio valori

Contare il numero di membri di una matrice che soddisfano una condizione. La matrice può essere una matrice letterale o un riferimento al parametro della matrice. La struttura delle espressioni di conteggio dei valori è:

{
    "count": {
        "value": "<literal array | array parameter reference>",
        "name": "<index name>",
        "where": {
            /* condition expression */
        }
    },
    "<condition>": "<compare the count of true condition expression array members to this value>"
}

Le proprietà seguenti vengono usate con il conteggio dei valori:

  • count.value (obbligatorio): matrice da valutare.
  • count.name (obbligatorio): nome dell'indice composto da lettere e cifre inglesi. Definisce un nome per il valore del membro della matrice valutato nell'iterazione corrente. Il nome viene usato per fare riferimento al valore corrente all'interno della count.where condizione. Facoltativo quando l'espressione count non si trova in un elemento figlio di un'altra espressione count . Se non specificato, il nome dell'indice viene impostato in modo implicito su "default".
  • count.where (facoltativo): espressione della condizione da valutare singolarmente per ogni membro della matrice di count.value. Se questa proprietà non viene specificata, tutti i membri della matrice vengono valutati su true. All'interno di questa proprietà è possibile usare qualunque condizione. Gli operatori logici possono essere usati all'interno di questa proprietà per creare requisiti di valutazione complessi. È possibile accedere al valore del membro della matrice attualmente enumerato chiamando la funzione corrente .
  • <condition> (obbligatorio): il valore viene confrontato con il numero di elementi che soddisfano l'espressione della count.where condizione. È necessario usare una condizione numerica.

Funzione corrente

La current() funzione è disponibile solo all'interno della count.where condizione. Restituisce il valore del membro della matrice attualmente enumerato dalla valutazione dell'espressione count .

Utilizzo del conteggio dei valori

  • current(<index name defined in count.name>). Ad esempio: current('arrayMember').
  • current(). Consentito solo quando l'espressione conteggio valori non è figlio di un'altra espressione count. Restituisce lo stesso valore di quello precedente.

Se il valore restituito dalla chiamata è un oggetto, sono supportate le funzioni di accesso alle proprietà. Ad esempio: current('objectArrayMember').property.

Utilizzo del conteggio dei campi

  • current(<the array alias defined in count.field>). Ad esempio, current('Microsoft.Test/resource/enumeratedArray[*]').
  • current(). Consentito solo quando l'espressione del conteggio dei campi non è figlio di un'altra espressione count . Restituisce lo stesso valore di quello precedente.
  • current(<alias of a property of the array member>). Ad esempio, current('Microsoft.Test/resource/enumeratedArray[*].property').

Esempi di conteggio dei campi

Esempio 1: Verificare se una matrice è vuota

{
    "count": {
        "field": "Microsoft.Network/networkSecurityGroups/securityRules[*]"
    },
    "equals": 0
}

Esempio 2: Verificare che un solo membro della matrice soddisfi l'espressione della condizione

{
    "count": {
        "field": "Microsoft.Network/networkSecurityGroups/securityRules[*]",
        "where": {
            "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].description",
            "equals": "My unique description"
        }
    },
    "equals": 1
}

Esempio 3: Verificare che almeno un membro della matrice soddisfi l'espressione della condizione

{
    "count": {
        "field": "Microsoft.Network/networkSecurityGroups/securityRules[*]",
        "where": {
            "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].description",
            "equals": "My common description"
        }
    },
    "greaterOrEquals": 1
}

Esempio 4: Verificare che tutti i membri della matrice di oggetti soddisfino l'espressione della condizione

{
    "count": {
        "field": "Microsoft.Network/networkSecurityGroups/securityRules[*]",
        "where": {
            "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].description",
            "equals": "description"
        }
    },
    "equals": "[length(field('Microsoft.Network/networkSecurityGroups/securityRules[*]'))]"
}

Esempio 5: Verificare che almeno un membro della matrice corrisponda a più proprietà nell'espressione della condizione

{
    "count": {
        "field": "Microsoft.Network/networkSecurityGroups/securityRules[*]",
        "where": {
            "allOf": [
                {
                    "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].direction",
                    "equals": "Inbound"
                },
                {
                    "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].access",
                    "equals": "Allow"
                },
                {
                    "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].destinationPortRange",
                    "equals": "3389"
                }
            ]
        }
    },
    "greater": 0
}

Esempio 6: usare current() la funzione all'interno delle where condizioni per accedere al valore del membro matrice attualmente enumerato in una funzione modello. Questa condizione controlla se una rete virtuale contiene un prefisso di indirizzo non compreso nell'intervallo CIDR 10.0.0.0/24.

{
    "count": {
        "field": "Microsoft.Network/virtualNetworks/addressSpace.addressPrefixes[*]",
        "where": {
          "value": "[ipRangeContains('10.0.0.0/24', current('Microsoft.Network/virtualNetworks/addressSpace.addressPrefixes[*]'))]",
          "equals": false
        }
    },
    "greater": 0
}

Esempio 7: usare field() la funzione all'interno delle where condizioni per accedere al valore del membro matrice attualmente enumerato. Questa condizione controlla se una rete virtuale contiene un prefisso di indirizzo non compreso nell'intervallo CIDR 10.0.0.0/24.

{
    "count": {
        "field": "Microsoft.Network/virtualNetworks/addressSpace.addressPrefixes[*]",
        "where": {
          "value": "[ipRangeContains('10.0.0.0/24', first(field(('Microsoft.Network/virtualNetworks/addressSpace.addressPrefixes[*]')))]",
          "equals": false
        }
    },
    "greater": 0
}

Esempi di conteggio valori

Esempio 1: controllare se il nome della risorsa corrisponde a uno dei modelli di nome specificati.

{
    "count": {
        "value": [ "prefix1_*", "prefix2_*" ],
        "name": "pattern",
        "where": {
            "field": "name",
            "like": "[current('pattern')]"
        }
    },
    "greater": 0
}

Esempio 2: controllare se il nome della risorsa corrisponde a uno dei modelli di nome specificati. La current() funzione non specifica un nome di indice. Il risultato è lo stesso dell'esempio precedente.

{
    "count": {
        "value": [ "prefix1_*", "prefix2_*" ],
        "where": {
            "field": "name",
            "like": "[current()]"
        }
    },
    "greater": 0
}

Esempio 3: verificare se il nome della risorsa corrisponde a uno dei modelli di nome specificati forniti da un parametro di matrice.

{
    "count": {
        "value": "[parameters('namePatterns')]",
        "name": "pattern",
        "where": {
            "field": "name",
            "like": "[current('pattern')]"
        }
    },
    "greater": 0
}

Esempio 4: verificare se uno dei prefissi degli indirizzi della rete virtuale non è compreso nell'elenco dei prefissi approvati.

{
    "count": {
        "field": "Microsoft.Network/virtualNetworks/addressSpace.addressPrefixes[*]",
        "where": {
            "count": {
                "value": "[parameters('approvedPrefixes')]",
                "name": "approvedPrefix",
                "where": {
                    "value": "[ipRangeContains(current('approvedPrefix'), current('Microsoft.Network/virtualNetworks/addressSpace.addressPrefixes[*]'))]",
                    "equals": true
                },
            },
            "equals": 0
        }
    },
    "greater": 0
}

Esempio 5: verificare che tutte le regole del gruppo di sicurezza di rete riservate siano definite in un gruppo di sicurezza di rete. Le proprietà delle regole del gruppo di sicurezza di rete riservate sono definite in un parametro di matrice contenente oggetti.

Valore del parametro:

[
    {
        "priority": 101,
        "access": "deny",
        "direction": "inbound",
        "destinationPortRange": 22
    },
    {
        "priority": 102,
        "access": "deny",
        "direction": "inbound",
        "destinationPortRange": 3389
    }
]

Criteri:

{
    "count": {
        "value": "[parameters('reservedNsgRules')]",
        "name": "reservedNsgRule",
        "where": {
            "count": {
                "field": "Microsoft.Network/networkSecurityGroups/securityRules[*]",
                "where": {
                    "allOf": [
                        {
                            "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].priority",
                            "equals": "[current('reservedNsgRule').priority]"
                        },
                        {
                            "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].access",
                            "equals": "[current('reservedNsgRule').access]"
                        },
                        {
                            "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].direction",
                            "equals": "[current('reservedNsgRule').direction]"
                        },
                        {
                            "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].destinationPortRange",
                            "equals": "[current('reservedNsgRule').destinationPortRange]"
                        }
                    ]
                }
            },
            "equals": 1
        }
    },
    "equals": "[length(parameters('reservedNsgRules'))]"
}

Effetto

Criteri di Azure supporta i tipi di effetto seguenti:

  • Append: aggiunge il set di campi definiti alla richiesta
  • Audit: genera un evento di avviso nel log attività, ma non nega la richiesta
  • AuditIfNotExists: genera un evento di avviso nel log attività se una risorsa correlata non esiste
  • Deny: genera un evento nel log attività e nega la richiesta
  • DeployIfNotExists: distribuisce una risorsa correlata se non esiste già
  • Disabled: non valuta le risorse per garantire la conformità alla regola dei criteri
  • Modifica: aggiunge, aggiorna o rimuove il set definito di campi nella richiesta
  • EnforceOPAConstraint (deprecato): configura il controller di ammissione Open Policy Agent con Gatekeeper v3 per i cluster Kubernetes self-managed in Azure
  • EnforceRegoPolicy (deprecato): configura il controller di ammissione Open Policy Agent con Gatekeeper v2 in servizio Azure Kubernetes

Per informazioni dettagliate su ogni effetto, ordine di valutazione, proprietà ed esempi, vedere Informazioni sugli effetti di Criteri di Azure.

Funzioni dei criteri

Le funzioni possono essere usate per introdurre logica aggiuntiva in una regola dei criteri. Vengono risolti all'interno della regola dei criteri di una definizione dei criteri e all'interno dei valori dei parametri assegnati alle definizioni dei criteri in un'iniziativa.

Tutte le funzioni del modello di Resource Manager sono disponibili per l'uso all'interno di una regola dei criteri, ad eccezione delle seguenti funzioni e funzioni definite dall'utente:

  • copyIndex()
  • dateTimeAdd()
  • deployment()
  • environment()
  • extensionResourceId()
  • listAccountSas()
  • listKeys()
  • listSecrets()
  • list*
  • managementGroup()
  • newGuid()
  • pickZones()
  • providers()
  • reference()
  • resourceId()
  • subscriptionResourceId()
  • tenantResourceId()
  • tenant()
  • utcNow(format)
  • variables()

Nota

Queste funzioni sono ancora disponibili all'interno della porzione details.deployment.properties.template della distribuzione del modello in una definizione dei criteri deployIfNotExists.

La funzione seguente è disponibile per l'uso in una regola dei criteri, ma differisce dall'uso in un modello di Azure Resource Manager (modello arm):

  • utcNow() - A differenza di un modello di Resource Manager, questa proprietà può essere usata all'esterno di defaultValue.
    • Restituisce una stringa impostata sulla data e l'ora correnti nel formato yyyy-MM-ddTHH:mm:ss.fffffffZDateTime universale ISO 8601 .

Le funzioni seguenti sono disponibili solo nelle regole dei criteri:

  • addDays(dateTime, numberOfDaysToAdd)

    • dateTime: [Obbligatorio] stringa - Stringa nel formato DateTime universale ISO 8601 'a-MM-ddTHH:mm:ss. FFFFFFFZ'
    • numberOfDaysToAdd: [Obbligatorio] numero intero - Numero intero di giorni da aggiungere
  • field(fieldName)

    • fieldName: [Obbligatorio] stringa - Nome del campo da recuperare
    • Restituisce il valore di tale campo dalla risorsa che viene valutata dalla condizione If.
    • field viene principalmente usata con AuditIfNotExists e DeployIfNotExists per fare riferimento ai campi sulla risorsa che viene valutata. Altre informazioni sono disponibili nell'esempio DeployIfNotExists.
  • requestContext().apiVersion

    • Restituisce la versione dell'API della richiesta che ha attivato la valutazione del criterio, ad esempio: 2021-09-01. Questo valore è la versione dell'API usata nella richiesta PUT/PATCH per le valutazioni sulla creazione/aggiornamento delle risorse. La versione più recente dell'API viene sempre usata durante la valutazione della conformità sulle risorse esistenti.
  • policy()

    • Restituisce le informazioni seguenti sui criteri da valutare. Le proprietà possono essere accessibili dall'oggetto restituito (ad esempio: [policy().assignmentId]).

      {
        "assignmentId": "/subscriptions/ad404ddd-36a5-4ea8-b3e3-681e77487a63/providers/Microsoft.Authorization/policyAssignments/myAssignment",
        "definitionId": "/providers/Microsoft.Authorization/policyDefinitions/34c877ad-507e-4c82-993e-3452a6e0ad3c",
        "setDefinitionId": "/providers/Microsoft.Authorization/policySetDefinitions/42a694ed-f65e-42b2-aa9e-8052e9740a92",
        "definitionReferenceId": "StorageAccountNetworkACLs"
      }
      
  • ipRangeContains(range, targetRange)

    • intervallo: [Obbligatorio] stringa : stringa che specifica un intervallo di indirizzi IP per verificare se targetRange è all'interno.
    • targetRange: stringa [Obbligatorio] - Stringa che specifica un intervallo di indirizzi IP da convalidare come incluso nell'intervallo.
    • Restituisce un valore booleano per se l'intervallo di indirizzi IP di intervallo contiene l'intervallo di indirizzi IP targetRange . Gli intervalli vuoti o la combinazione tra le famiglie IP non sono consentite e generano errori di valutazione.

    Formati supportati:

    • Indirizzo IP singolo (esempi: 10.0.0.0, 2001:0DB8::3:FFFE)
    • Intervallo CIDR (esempi: 10.0.0.0/24, 2001:0DB8::/110)
    • Intervallo definito dagli indirizzi IP iniziali e finali (esempi: 192.168.0.1-192.168.0.9, 2001:0DB8::-2001:0DB8::3:FFFF)
  • current(indexName)

Esempio di funzione dei criteri

Questo esempio di regola dei criteri usa la resourceGroup funzione risorsa per ottenere la proprietà name, in combinazione con la matrice concat e la funzione oggetto per creare una condizione like che fa in modo che il nome della risorsa inizi con il nome del gruppo di risorse.

{
    "if": {
        "not": {
            "field": "name",
            "like": "[concat(resourceGroup().name,'*')]"
        }
    },
    "then": {
        "effect": "deny"
    }
}

Limiti delle regole dei criteri

Limiti applicati durante la creazione

Durante la creazione o l'assegnazione di un criterio vengono applicati limiti alla struttura delle regole dei criteri. I tentativi di creare o assegnare definizioni di criteri che superano questi limiti avranno esito negativo.

Limite valore Dettagli aggiuntivi
Espressioni della condizione nella condizione if 4096
Espressioni della condizione nel blocco then 128 Si applica all'esistenzaCondition dei criteri AuditIfNotExists e DeployIfNotExists
Funzioni dei criteri per ogni regola dei criteri 2048
Numero dei parametri della funzione dei criteri 128 Esempio: [function('parameter1', 'parameter2', ...)]
Profondità delle funzioni dei criteri annidate 64 Esempio: [function(nested1(nested2(...)))]
Lunghezza della stringa dell'espressione delle funzioni dei criteri 81920 Esempio: lunghezza di "[function(....)]"
Espressioni di conteggio dei campi per matrice 5
Espressioni di conteggio dei valori per regola dei criteri 10
Conteggio delle espressioni di conteggio dei valori 100 Per le espressioni di conteggio valori annidati, include anche il conteggio dell'iterazione dell'espressione padre

Limiti applicati durante la valutazione

Limiti alle dimensioni degli oggetti elaborati dalle funzioni dei criteri durante la valutazione dei criteri. Questi limiti non possono essere sempre applicati durante la creazione perché dipendono dal contenuto valutato. Ad esempio:

{
    "field": "name",
    "equals": "[concat(field('stringPropertyA'), field('stringPropertyB'))]"
}

La lunghezza della stringa creata dalla concat() funzione dipende dal valore delle proprietà nella risorsa valutata.

Limite Valore Esempio
Lunghezza della stringa restituita da una funzione 131072 [concat(field('longString1'), field('longString2'))]
Profondità degli oggetti complessi fornita come parametro a una funzione o restituita da essa 128 [union(field('largeObject1'), field('largeObject2'))]
Numero di nodi degli oggetti complessi fornito come parametro a una funzione o restituito da essa 32768 [concat(field('largeArray1'), field('largeArray2'))]

Avviso

I criteri che superano i limiti precedenti durante la valutazione diventeranno effettivamente un criterio di negazione e possono bloccare le richieste in ingresso. Quando si scrivono criteri con funzioni complesse, tenere presente questi limiti e testare i criteri sulle risorse che potrebbero superarli.

Alias

Usare gli alias delle proprietà per accedere alle proprietà specifiche per un tipo di risorsa. Gli alias consentono di limitare le condizioni o i valori consentiti per una proprietà su una risorsa. Ogni alias esegue il mapping ai percorsi in versioni di API diverse per un tipo di risorsa specificato. Durante la valutazione dei criteri, il motore dei criteri ottiene il percorso della proprietà per la versione API specificata.

L'elenco degli alias è in costante crescita. Per scoprire quali alias sono attualmente supportati da Criteri di Azure usare uno dei metodi seguenti:

  • Estensione di Criteri di Azure per Visual Studio Code (scelta consigliata)

    Usare l'estensione Criteri di Azure per Visual Studio Code per visualizzare e individuare gli alias per le proprietà delle risorse.

    Screenshot dell'estensione Criteri di Azure per Visual Studio Code che posiziona il puntatore del mouse su una proprietà per visualizzare i nomi degli alias.

  • Azure PowerShell

    # Login first with Connect-AzAccount if not using Cloud Shell
    
    # Use Get-AzPolicyAlias to list available providers
    Get-AzPolicyAlias -ListAvailable
    
    # Use Get-AzPolicyAlias to list aliases for a Namespace (such as Azure Compute -- Microsoft.Compute)
    (Get-AzPolicyAlias -NamespaceMatch 'compute').Aliases
    

    Nota

    Per trovare gli alias che possono essere usati con l'effetto modify, usare il comando seguente in Azure PowerShell 4.6.0 o versione successiva:

    Get-AzPolicyAlias | Select-Object -ExpandProperty 'Aliases' | Where-Object { $_.DefaultMetadata.Attributes -eq 'Modifiable' }
    
  • Interfaccia della riga di comando di Azure

    # Login first with az login if not using Cloud Shell
    
    # List namespaces
    az provider list --query [*].namespace
    
    # Get Azure Policy aliases for a specific Namespace (such as Azure Compute -- Microsoft.Compute)
    az provider show --namespace Microsoft.Compute --expand "resourceTypes/aliases" --query "resourceTypes[].aliases[].name"
    
  • API REST / ARMClient

    GET https://management.azure.com/providers/?api-version=2019-10-01&$expand=resourceTypes/aliases
    

Informazioni sull'alias [*]

Diversi alias disponibili hanno una versione visualizzata come nome "normale" e un'altra con [*] associata. Ad esempio:

  • Microsoft.Storage/storageAccounts/networkAcls.ipRules
  • Microsoft.Storage/storageAccounts/networkAcls.ipRules[*]

L'alias "normal" rappresenta il campo come valore singolo. Questo campo è per gli scenari di confronto con corrispondenza esatta quando l'intero set di valori deve essere esattamente come definito, non più e non meno.

L'alias [*] rappresenta una raccolta di valori selezionati dagli elementi di una proprietà della risorsa di matrice. Ad esempio:

Alias Valori selezionati
Microsoft.Storage/storageAccounts/networkAcls.ipRules[*] Elementi della ipRules matrice.
Microsoft.Storage/storageAccounts/networkAcls.ipRules[*].action Valori della action proprietà da ogni elemento della ipRules matrice.

Se usato in una condizione di campo , gli alias di matrice consentono di confrontare ogni singolo elemento di matrice con un valore di destinazione. Se usato con l'espressione count , è possibile:

  • Controllare le dimensioni di una matrice
  • Controllare se all\any\nuno degli elementi della matrice soddisfa una condizione complessa
  • Controllare se esattamente n elementi della matrice soddisfano una condizione complessa

Per altre informazioni ed esempi, vedere Riferimento alle proprietà delle risorse della matrice.

Passaggi successivi