Beleid maken voor matrixeigenschappen in Azure-resources

Azure Resource Manager eigenschappen worden doorgaans gedefinieerd als tekenreeksen en booleaansen. Wanneer er een een-op-veel-relatie bestaat, worden complexe eigenschappen in plaats daarvan gedefinieerd als matrices. In Azure Policy worden matrices op verschillende manieren gebruikt:

• Het type van een definitieparameter ommeerdere opties te bieden
• Onderdeel van een beleidsregel met behulp van de voorwaarden in of nietIn
• Onderdeel van een beleidsregel die telt hoeveel matrixleden aan een voorwaarde voldoen
• In de effecten voor het append en wijzigen van een bestaande matrix

In dit artikel wordt elk gebruik door Azure Policy en worden verschillende voorbeelddefinities beschreven.

Parameter matrices

Een parameter array definiëren

Als u een parameter als matrix definieert, wordt de beleidsflexibiliteit mogelijk wanneer er meer dan één waarde nodig is. Deze beleidsdefinitie staat één locatie toe voor de parameter allowedLocations en wordt standaard ingesteld op eastus2:

"parameters": {
    "allowedLocations": {
        "type": "string",
        "metadata": {
            "description": "The list of allowed locations for resources.",
            "displayName": "Allowed locations",
            "strongType": "location"
        },
        "defaultValue": "eastus2"
    }
}

Omdat type tekenreeks is, kan er slechts één waarde worden ingesteld bij het toewijzen van het beleid. Als dit beleid is toegewezen, zijn resources in het bereik alleen toegestaan binnen één Azure-regio. De meeste beleidsdefinities moeten een lijst met goedgekeurde opties toestaan, zoals het toestaan van eastus2, eastus en westus2.

Als u de beleidsdefinitie wilt maken om meerdere opties toe te staan, gebruikt u het matrixtype . Hetzelfde beleid kan als volgt worden herschreven:

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

    }
}

Deze nieuwe parameterdefinitie heeft meer dan één waarde tijdens de beleidstoewijzing. Nu de eigenschap allowedValues van de matrix is gedefinieerd, worden de waarden die beschikbaar zijn tijdens de toewijzing verder beperkt tot de vooraf gedefinieerde lijst met opties. Het gebruik van allowedValues is optioneel.

Waarden doorgeven aan een parameter matrix tijdens de toewijzing

Wanneer u het beleid toewijst via Azure Portal, wordt een parameter van het type matrix weergegeven als één tekstvak. De hint geeft aan: "Gebruiken; om waarden te scheiden. (bijvoorbeeld Londen; New York)'. Gebruik de volgende tekenreeks om de toegestane locatiewaarden eastus2, eastus en westus2 door te geven aan de parameter :

eastus2;eastus;westus2

De indeling voor de parameterwaarde is anders wanneer u Azure CLI, Azure PowerShell of de REST API. De waarden worden doorgegeven via een JSON-tekenreeks die ook de naam van de parameter bevat.

{
    "allowedLocations": {
        "value": [
            "eastus2",
            "eastus",
            "westus2"
        ]
    }
}

Gebruik de volgende opdrachten om deze tekenreeks te gebruiken voor elke SDK:

• Azure CLI: opdracht az policy assignment create met parameterparameters
• Azure PowerShell: Cmdlet New-AzPolicyAssignment met parameter PolicyParameter
• REST API: In de put-maakbewerking als onderdeel van de aanvraag body als de waarde van de eigenschap properties.parameters

Matrices gebruiken in voorwaarden

In en notIn

De in voorwaarden en werken alleen met notIn matrixwaarden. Ze controleren het bestaan van een waarde in een matrix. De matrix kan een letterlijke JSON-matrix of een verwijzing naar een matrixparameter zijn. Bijvoorbeeld:

{
      "field": "tags.environment",
      "in": [ "dev", "test" ]
}

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

Aantal waarden

De expressie aantal waarden telt hoeveel matrixleden aan een voorwaarde voldoen. Het biedt een manier om dezelfde voorwaarde meerdere keren te evalueren, met behulp van verschillende waarden voor elke iteratie. Met de volgende voorwaarde wordt bijvoorbeeld gecontroleerd of de resourcenaam overeenkomt met een patroon uit een matrix met patronen:

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

Als u de expressie wilt evalueren, Azure Policy de voorwaarde drie keer, eenmaal voor elk lid van , geteld hoe vaak deze where [ "test*", "dev*", "prod*" ] is geëvalueerd als true . Bij elke iteratie wordt de waarde van het huidige matrixlid gekoppeld aan de pattern indexnaam die is gedefinieerd door count.name . Er kan vervolgens naar deze waarde in de voorwaarde worden verwezen where door een speciale sjabloonfunctie aan te roepen: current('pattern') .

De voorwaarde is alleen waar als het resultaat groter is dan 0.

Als u de bovenstaande voorwaarde algemener wilt maken, gebruikt u parameterverwijzing in plaats van een letterlijke matrix:

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

Wanneer de expressie voor het aantal waarden zich niet onder een andere count-expressie valt, is optioneel en kan de functie count.name zonder argumenten worden current() gebruikt:

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

Het aantal waarden ondersteunt ook matrices van complexe objecten, waardoor complexere omstandigheden mogelijk zijn. De volgende voorwaarde definieert bijvoorbeeld een gewenste tagwaarde voor elk naampatroon en controleert of de resourcenaam overeenkomt met het patroon, maar niet de vereiste tagwaarde heeft:

{
    "count": {
        "value": [
            { "pattern": "test*", "envTag": "dev" },
            { "pattern": "dev*", "envTag": "dev" },
            { "pattern": "prod*", "envTag": "prod" },
        ],
        "name": "namePatternRequiredTag",
        "where": {
            "allOf": [
                {
                    "field": "name",
                    "like": "[current('namePatternRequiredTag').pattern]"
                },
                {
                    "field": "tags.env",
                    "notEquals": "[current('namePatternRequiredTag').envTag]"
                }
            ]
        }
    },
    "greater": 0
}

Zie voorbeelden van het aantal waarden voor nuttige voorbeelden.

Verwijzen naar eigenschappen van matrixresources

Voor veel gebruiksgevallen moet u werken met matrixeigenschappen in de geëvalueerde resource. Voor sommige scenario's moet naar een volledige matrix worden verwezen (bijvoorbeeld door de lengte te controleren). Voor andere moet een voorwaarde worden toegepast op elk afzonderlijk matrixlid (zorg er bijvoorbeeld voor dat alle firewallregels de toegang vanaf internet blokkeren). Inzicht in de verschillende manieren waarop Azure Policy kunnen verwijzen naar resource-eigenschappen en hoe deze verwijzingen zich gedragen wanneer ze naar matrixeigenschappen verwijzen, is de sleutel voor het schrijven van voorwaarden die betrekking hebben op deze scenario's.

Verwijzen naar resource-eigenschappen

Resource-eigenschappen kunnen worden gebruikt Azure Policy aliassen. Er zijn twee manieren om te verwijzen naar de waarden van een resource-eigenschap in Azure Policy:

• Gebruik veldvoorwaarde om te controleren of alle geselecteerde resource-eigenschappen voldoen aan een voorwaarde. Voorbeeld:

  {
    "field" : "Microsoft.Test/resourceType/property",
    "equals": "value"
  }
  

• Gebruik field() functie om toegang te krijgen tot de waarde van een eigenschap. Voorbeeld:

  {
    "value": "[take(field('Microsoft.Test/resourceType/property'), 7)]",
    "equals": "prefix_"
  }
  

De veldvoorwaarde heeft een impliciet 'alles'-gedrag. Als de alias een verzameling waarden vertegenwoordigt, wordt gecontroleerd of alle afzonderlijke waarden aan de voorwaarde voldoen. De functie retourneert de waarden die worden vertegenwoordigd door de alias as-is, die vervolgens kunnen worden field() bewerkt door andere sjabloonfuncties.

Naar matrixvelden verwijzen

Eigenschappen van matrixresources worden vertegenwoordigd door twee verschillende typen aliassen. Een 'normale' alias en matrixaliassen die eraan [*] zijn gekoppeld:

• Microsoft.Test/resourceType/stringArray
• Microsoft.Test/resourceType/stringArray[*]

Naar de matrix verwijzen

De eerste alias vertegenwoordigt één waarde, de waarde van stringArray de eigenschap van de aanvraaginhoud. Omdat de waarde van die eigenschap een matrix is, is deze niet nuttig in beleidsvoorwaarden. Bijvoorbeeld:

{
  "field": "Microsoft.Test/resourceType/stringArray",
  "equals": "..."
}

Met deze voorwaarde wordt de hele stringArray matrix vergeleken met één tekenreekswaarde. De meeste voorwaarden, waaronder , accepteren alleen tekenreekswaarden, dus er is niet veel gebruik bij het vergelijken van een equals matrix met een tekenreeks. Het belangrijkste scenario waarbij het verwijzen naar de matrix-eigenschap nuttig is, is wanneer u controleert of deze bestaat:

{
  "field": "Microsoft.Test/resourceType/stringArray",
  "exists": "true"
}

Met de functie is de geretourneerde waarde de matrix van de aanvraaginhoud, die vervolgens kan worden gebruikt met een van de ondersteunde sjabloonfuncties field() die matrixargumenten accepteren. Met de volgende voorwaarde wordt bijvoorbeeld gecontroleerd of de lengte van stringArray groter is dan 0:

{
  "value": "[length(field('Microsoft.Test/resourceType/stringArray'))]",
  "greater": 0
}

Verwijzen naar de verzameling matrixleden

Aliassen die gebruikmaken van de syntaxis vertegenwoordigen een verzameling eigenschapswaarden die zijn geselecteerd uit een matrix-eigenschap , die anders is dan het selecteren van [*] de matrix-eigenschap zelf. In het geval van Microsoft.Test/resourceType/stringArray[*] retourneert deze een verzameling met alle leden van stringArray . Zoals eerder vermeld, controleert een voorwaarde of alle geselecteerde resource-eigenschappen voldoen aan de voorwaarde. Daarom is de volgende voorwaarde alleen waar als alle leden van gelijk zijn aan field stringArray ''waarde'.

{
  "field": "Microsoft.Test/resourceType/stringArray[*]",
  "equals": "value"
}

Als de matrix objecten bevat, kan een alias worden gebruikt om de waarde van een specifieke eigenschap van elk matrixlid [*] te selecteren. Voorbeeld:

{
  "field": "Microsoft.Test/resourceType/objectArray[*].property",
  "equals": "value"
}

Deze voorwaarde is true als de waarden van alle property eigenschappen in gelijk zijn aan objectArray "value" . Zie Aanvullende [ * ] aliasvoorbeelden voor meer voorbeelden.

Wanneer u de functie field() gebruikt om te verwijzen naar een matrixalias, is de geretourneerde waarde een matrix van alle geselecteerde waarden. Dit gedrag betekent dat de algemene use-case van de functie, de mogelijkheid om sjabloonfuncties toe te passen op field() waarden van resource-eigenschappen, beperkt is. De enige sjabloonfuncties die in dit geval kunnen worden gebruikt, zijn de functies die matrixargumenten accepteren. Het is bijvoorbeeld mogelijk om de lengte van de matrix op te halen met [length(field('Microsoft.Test/resourceType/objectArray[*].property'))] . Complexere scenario's zoals het toepassen van een sjabloonfunctie op elk matrixlid en het vergelijken ervan met een gewenste waarde zijn echter alleen mogelijk wanneer u de expressie count gebruikt. Zie Veldtellingexpressie voor meer informatie.

Zie de volgende voorbeeldresource-inhoud en de geselecteerde waarden die worden geretourneerd door verschillende aliassen om samen te vatten:

{
  "tags": {
    "env": "prod"
  },
  "properties":
  {
    "stringArray": [ "a", "b", "c" ],
    "objectArray": [
      {
        "property": "value1",
        "nestedArray": [ 1, 2 ]
      },
      {
        "property": "value2",
        "nestedArray": [ 3, 4 ]
      }
    ]
  }
}

Wanneer u de veldvoorwaarde voor de voorbeeldresourceinhoud gebruikt, zijn de resultaten als volgt:

Wanneer u de field() functie gebruikt voor de voorbeeldresource-inhoud, zijn de resultaten als volgt:

Expressies voor veldtelling

Met expressies voor het aantal velden wordt geteld hoeveel matrixleden aan een voorwaarde voldoen en wordt het aantal vergeleken met een doelwaarde. Count is intuïtiever en veelzijdiger voor het evalueren van matrices vergeleken met field voorwaarden. De syntaxis is:

{
  "count": {
    "field": <[*] alias>,
    "where": <optional policy condition expression>
  },
  "equals|greater|less|any other operator": <target value>
}

Wanneer u zonder een where voorwaarde gebruikt, count retourneert gewoon de lengte van een matrix. Met de voorbeeldresource-inhoud uit de vorige sectie wordt de volgende count expressie geëvalueerd omdat drie leden true stringArray heeft:

{
  "count": {
    "field": "Microsoft.Test/resourceType/stringArray[*]"
  },
  "equals": 3
}

Dit gedrag werkt ook met geneste matrices. De volgende expressie wordt bijvoorbeeld geëvalueerd op omdat er vier count true matrixleden in de nestedArray matrices zijn:

{
  "count": {
    "field": "Microsoft.Test/resourceType/objectArray[*].nestedArray[*]"
  },
  "greaterOrEquals": 4
}

De kracht van count zit in de where voorwaarde. Wanneer deze is opgegeven, Azure Policy de matrixleden op en evalueert ze elk op basis van de voorwaarde, met het aantal matrixleden dat wordt geëvalueerd als true . Met name bij elke iteratie van de evaluatie van de voorwaarde selecteert Azure Policy één matrixlid * i _ en evalueert de resource-inhoud aan de voorwaarde alsof * ik het enige lid van de where where array_. __ Als er slechts één matrixlid beschikbaar is in elke iteratie, kunt u complexe voorwaarden toepassen op elk afzonderlijk matrixlid.

Voorbeeld:

{
  "count": {
    "field": "Microsoft.Test/resourceType/stringArray[*]",
    "where": {
      "field": "Microsoft.Test/resourceType/stringArray[*]",
      "equals": "a"
    }
  },
  "equals": 1
}

Om de expressie te evalueren, Azure Policy de voorwaarde drie keer geëvalueerd, eenmaal voor elk lid van , tellend hoe vaak deze count where is geëvalueerd als stringArray true . Wanneer de voorwaarde naar de matrixleden verwijst, worden in plaats van alle leden van te selecteren slechts één where Microsoft.Test/resourceType/stringArray[*] stringArray matrixlid telkens geselecteerd:

De count retourneert 1 .

Hier is een complexere expressie:

{
  "count": {
    "field": "Microsoft.Test/resourceType/objectArray[*]",
    "where": {
      "allOf": [
        {
          "field": "Microsoft.Test/resourceType/objectArray[*].property",
          "equals": "value2"
        },
        {
          "field": "Microsoft.Test/resourceType/objectArray[*].nestedArray[*]",
          "greater": 2
        }
      ]
    }
  },
  "equals": 1
}

De count retourneert 1 .

Het feit dat de expressie wordt geëvalueerd op basis van de volledige aanvraaginhoud (met wijzigingen alleen in het matrixlid dat momenteel wordt where geïndeereerd), betekent dat de voorwaarde ook naar velden buiten de matrix kan where verwijzen:

{
  "count": {
    "field": "Microsoft.Test/resourceType/objectArray[*]",
    "where": {
      "field": "tags.env",
      "equals": "prod"
    }
  },
  "equals": 0
}

Geneste count-expressies kunnen worden gebruikt om voorwaarden toe te passen op geneste matrixvelden. Met de volgende voorwaarde wordt bijvoorbeeld gecontroleerd of de matrix precies twee objectArray[*] leden heeft met een of meer nestedArray[*] leden:

{
  "count": {
    "field": "Microsoft.Test/resourceType/objectArray[*]",
    "where": {
      "count": {
        "field": "Microsoft.Test/resourceType/objectArray[*].nestedArray[*]"
      },
      "greaterOrEquals": 1
    }
  },
  "equals": 2
}

Omdat beide leden van objectArray[*] een onderliggende matrix met twee leden hebben, retourneert nestedArray[*] de expressie outer count 2 .

Complexer voorbeeld: controleer of de matrix precies twee leden heeft objectArray[*] met leden die gelijk zijn aan of nestedArray[*] 2 3 :

{
  "count": {
    "field": "Microsoft.Test/resourceType/objectArray[*]",
    "where": {
      "count": {
        "field": "Microsoft.Test/resourceType/objectArray[*].nestedArray[*]",
        "where": {
            "field": "Microsoft.Test/resourceType/objectArray[*].nestedArray[*]",
            "in": [ 2, 3 ]
        }
      },
      "greaterOrEquals": 1
    }
  },
  "equals": 2
}

Omdat beide leden van een onderliggende matrix hebben die of bevat, retourneert objectArray[*] nestedArray[*] de expressie outer 2 3 2 count.

Toegang tot huidig matrixlid met sjabloonfuncties

Wanneer u sjabloonfuncties gebruikt, gebruikt u de functie om toegang te krijgen tot de waarde van het huidige current() matrixlid of de waarden van een van de eigenschappen. Als u toegang wilt krijgen tot de waarde van het huidige matrixlid, geeft u de alias die is gedefinieerd in of een van de onderliggende aliassen als argument door count.field aan de current() functie . Bijvoorbeeld:

{
  "count": {
    "field": "Microsoft.Test/resourceType/objectArray[*]",
    "where": {
        "value": "[current('Microsoft.Test/resourceType/objectArray[*].property')]",
        "like": "value*"
    }
  },
  "equals": 2
}

De veldfunctie binnen de voorwaarden

De functie kan ook worden gebruikt voor toegang tot de waarde van het huidige matrixlid, zolang de count-expressie zich niet binnen een bestaansvoorwaarde (de functie verwijst altijd naar de resource die in de field() if-voorwaarde field() wordt geëvalueerd). Het gedrag van field() bij het verwijzen naar de geëvalueerde matrix is gebaseerd op de volgende concepten:

1. Matrixaliassen worden opgelost in een verzameling waarden die zijn geselecteerd van alle matrixleden.
2. field() Functies die verwijzen naar matrixaliassen retourneren een matrix met de geselecteerde waarden.
3. Als u verwijst naar de getelde matrixalias in de voorwaarde, wordt een verzameling met één waarde geselecteerd uit het matrixlid dat wordt geëvalueerd in de where huidige iteratie.

Dit gedrag betekent dat wanneer wordt verwezen naar het getelde matrixlid met een functie binnen de voorwaarde, deze een matrix met field() where één lid retourneert. Hoewel dit gedrag mogelijk niet intuïtief is, is het consistent met het idee dat matrixaliassen altijd een verzameling geselecteerde eigenschappen retourneren. Hier volgt een voorbeeld:

{
  "count": {
    "field": "Microsoft.Test/resourceType/stringArray[*]",
    "where": {
      "field": "Microsoft.Test/resourceType/stringArray[*]",
      "equals": "[field('Microsoft.Test/resourceType/stringArray[*]')]"
    }
  },
  "equals": 0
}

Wanneer er dus toegang nodig is tot de waarde van de getelde matrixalias met een functie, kunt u dit doen door deze te verpakken field() met een first() sjabloonfunctie:

{
  "count": {
    "field": "Microsoft.Test/resourceType/stringArray[*]",
    "where": {
      "field": "Microsoft.Test/resourceType/stringArray[*]",
      "equals": "[first(field('Microsoft.Test/resourceType/stringArray[*]'))]"
    }
  }
}

Zie Voorbeelden van aantal velden voor nuttige voorbeelden.

Matrices wijzigen

De eigenschappen van een resource wijzigen en deze wijzigen tijdens het maken of bijwerken. Wanneer u werkt met matrixeigenschappen, is het gedrag van deze effecten afhankelijk van of de bewerking de alias probeert te [*] wijzigen of niet:

Zie de app-voorbeelden voor meer informatie.

Aanvullende voorbeelden van [*] aliassen

Het is raadzaam om de expressies voor het aantal velden te gebruiken om te controleren of 'alle' of 'een van' de leden van een matrix in de aanvraaginhoud voldoen aan een voorwaarde. Voor een aantal eenvoudige omstandigheden is het echter mogelijk om hetzelfde resultaat te bereiken met behulp van een veldaccesses met een matrixalias, zoals beschreven in Verwijzen naar de verzameling matrixleden. Dit patroon kan handig zijn in beleidsregels die de limiet van toegestane aantal expressies overschrijden. Hier zijn voorbeelden voor veelvoorkomende gebruiksvoorbeelden:

De voorbeeldbeleidsregel voor de onderstaande scenariotabel:

"policyRule": {
    "if": {
        "allOf": [
            {
                "field": "Microsoft.Storage/storageAccounts/networkAcls.ipRules",
                "exists": "true"
            },
            <-- Condition (see table below) -->
        ]
    },
    "then": {
        "effect": "[parameters('effectType')]"
    }
}

De matrix ipRules is als volgt voor de onderstaande scenariotabel:

"ipRules": [
    {
        "value": "127.0.0.1",
        "action": "Allow"
    },
    {
        "value": "192.168.1.1",
        "action": "Allow"
    }
]

Vervang voor elk voorbeeld van de voorwaarde <field> hieronder door "field": "Microsoft.Storage/storageAccounts/networkAcls.ipRules[*].value" .

De volgende resultaten zijn het resultaat van de combinatie van de voorwaarde en de voorbeeldbeleidsregel en matrix van bestaande waarden hierboven:

Volgende stappen

• Bekijk voorbeelden op Azure Policy voorbeelden.
• Lees over de structuur van Azure Policy-definities.
• Lees Informatie over de effecten van het beleid.
• Begrijpen hoe u programmatisch beleid kunt maken.
• Ontdek hoe u niet-compatibele resources kunt herstellen.
• Bekijk wat een beheergroep is met Uw resources organiseren met Azure-beheergroepen.