Condividi tramite

Parametri della struttura di definizione di Criteri di Azure

  • Articolo

I parametri consentono di semplificare la gestione dei criteri, riducendone il numero di definizioni. I parametri possono essere paragonati ai campi di un modulo: name, address, city, state. Questi parametri rimangono sempre invariati, ma i relativi valori cambiano in base alla singola compilazione del modulo. 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.

Aggiunta o rimozione di parametri

È possibile aggiungere parametri a una definizione esistente e assegnata. Il nuovo parametro deve includere la proprietà defaultValue. Questa proprietà impedisce che le assegnazioni esistenti del criterio o dell'iniziativa vengano rese indirettamente non valide.

I parametri non possono essere rimossi da una definizione di criteri perché potrebbe esserci un'assegnazione che imposta il valore del parametro e tale riferimento verrebbe interrotto. Alcune definizioni di criteri predefinite deprecano i parametri utilizzando i metadati "deprecated": true, il che nasconde il parametro quando si assegna la definizione nel portale di Azure. Anche se questo metodo non è supportato per le definizioni di criteri personalizzate, un'altra opzione consiste nel duplicare e creare una nuova definizione di criteri personalizzata senza il parametro.

Proprietà parametri

Un parametro usa le proprietà seguenti in una 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 è un string, array, object, boolean, integer, floato dateTime.
  • metadata: definisce le sottoproprietà usate principalmente dal portale di Azure per visualizzare informazioni descrittive:
    • description: spiegazione dell'utilizzo del parametro. Può essere usata per fornire esempi di valori accettabili.
    • displayName: nome descrittivo visualizzato nel portale per il parametro .
    • strongType: (facoltativo) usato quando si assegna la definizione dei criteri tramite il portale. Fornisce un elenco con riconoscimento del contesto. Per altre informazioni, vedere strongType.
    • assignPermissions: (facoltativo) Impostare come true per fare in modo che il portale di Azure crei 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 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.
    • deprecated: flag booleano per indicare se un parametro è deprecato in una definizione predefinita.
  • defaultValue: (facoltativo) 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 oggetto, il valore deve corrispondere allo schema appropriato.
  • allowedValues: (facoltativo) Fornisce una matrice di valori accettati dal parametro durante l'assegnazione.
    • Distinzione tra maiuscole e minuscole: i confronti di valori consentiti fanno distinzione tra maiuscole e minuscole quando si assegna un criterio, ovvero i valori dei parametri selezionati nell'assegnazione devono corrispondere all'uso di maiuscole e minuscole nella matrice allowedValues nella definizione. Tuttavia, una volta selezionati i valori per l'assegnazione, la valutazione dei confronti tra stringhe potrebbe non fare distinzione tra maiuscole e minuscole a seconda della condizione usata. Ad esempio, se il parametro specifica Dev come valore di tag consentito in un'assegnazione e questo valore viene confrontato con una stringa di input usando la condizione equals, Criteri di Azure valuterà successivamente un valore di tag dev come corrispondenza anche se è minuscolo perché notEquals non fa distinzione tra maiuscole e minuscole.
    • Per i parametri di tipo oggetto, i valori devono corrispondere allo schema appropriato.
  • schema: (Facoltativo) Fornisce la convalida degli input dei parametri durante l'assegnazione usando uno schema JSON 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 di 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 tale definizione di criteri può essere allowedLocations e usato da ogni assegnazione della definizione di criteri per limitare i valori accettati. L'uso di strongType offre un'esperienza avanzata quando si completa l'assegnazione tramite il 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 ai pod del cluster Kubernetes di usare le etichette specificate. Un parametro per tale definizione di criteri può essere labelSelector e usato da ogni assegnazione della definizione dei criteri per specificare le risorse Kubernetes in questione in base a chiavi e valori di etichetta:

"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 sarebbe 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')]"
}

In questo esempio viene fatto riferimento al parametro allowedLocations illustrato nelle proprietà dei parametri.

strongType

Nella proprietà metadata è possibile usare strongType per fornire un elenco di opzioni di selezione multipla nel 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, utilizzare Get-AzResourceProvider. Il formato per un tipo di risorsa strongType è <Resource Provider>/<Resource Type>. Ad esempio: Microsoft.Network/virtualNetworks/subnets.

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

  • Microsoft.RecoveryServices/vaults/backupPolicies

I valori non tipo di risorsa consentiti per strongType sono:

  • location
  • resourceTypes
  • storageSkus
  • vmSKUs
  • existingResourceGroups

Passaggi successivi