Skapa principer för matrisegenskaper på Azure-resurser

Azure Resource Manager definieras vanligtvis som strängar och booleska tecken. När det finns en en-till-många-relation definieras komplexa egenskaper i stället som matriser. I Azure Policy används matriser på flera olika sätt:

• Typ av definitionsparameter föratt tillhandahålla flera alternativ
• En del av en principregel som använder villkoren i eller notIn
• En del av en principregel som räknar hur många matrismedlemmar som uppfyller ett villkor
• I tilläggs- och ändringseffekterna för att uppdatera en befintlig matris

Den här artikeln beskriver varje användning av Azure Policy och innehåller flera exempeldefinitioner.

Parametermatriser

Definiera en parametermatris

Om du definierar en parameter som en matris kan principen vara flexibel när mer än ett värde behövs. Den här principdefinitionen tillåter valfri enskild plats för parametern allowedLocations och använder som standard eastus2:

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

Eftersom typen var sträng kan endast ett värde anges när principen tilldelas. Om den här principen tilldelas tillåts endast resurser i omfånget inom en enda Azure-region. De flesta policydefinitioner måste tillåta en lista över godkända alternativ, till exempel att tillåta eastus2, eastus och westus2.

Om du vill skapa principdefinitionen för att tillåta flera alternativ använder du matristypen . Samma princip kan skrivas om på följande sätt:

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

    }
}

Den här nya parameterdefinitionen tar fler än ett värde under principtilldelningen. När matrisegenskapen allowedValues har definierats begränsas de värden som är tillgängliga under tilldelningen ytterligare till den fördefinierade listan med alternativ. Användning av allowedValues är valfritt.

Skicka värden till en parametermatris under tilldelningen

När du tilldelar principen via Azure Portal visas en parameter av typen matris som en enda textruta. Tipset säger "Använd ; för att avgränsa värden. (t.ex. London; New York)". Om du vill skicka de tillåtna platsvärdena eastus2, eastus och westus2 till parametern använder du följande sträng:

eastus2;eastus;westus2

Formatet för parametervärdet skiljer sig när du använder Azure CLI, Azure PowerShell eller REST API. Värdena skickas via en JSON-sträng som även innehåller namnet på parametern .

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

Om du vill använda den här strängen med varje SDK använder du följande kommandon:

• Azure CLI: Kommandot az policy assignment create med parameterparametrar
• Azure PowerShell: Cmdlet New-AzPolicyAssignment med parametern PolicyParameter
• REST API: I PUT-åtgärden skapar du som en del av begärandetexten som värdet för egenskapen properties.parameters

Använda matriser i villkor

In och notIn

Villkoren in och fungerar bara med notIn matrisvärden. De kontrollerar om det finns ett värde i en matris. Matrisen kan vara en literal JSON-matris eller en referens till en matrisparameter. Exempel:

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

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

Antal värden

Värdet count expression räknar hur många matrismedlemmar som uppfyller ett villkor. Det är ett sätt att utvärdera samma villkor flera gånger, med olika värden för varje iteration. Följande villkor kontrollerar till exempel om resursnamnet matchar något mönster från en matris med mönster:

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

För att utvärdera uttrycket utvärderar Azure Policy villkoret tre gånger, en gång för varje medlem i , räkna hur många gånger det where [ "test*", "dev*", "prod*" ] utvärderades till true . Vid varje iteration paras värdet för den aktuella matrismedlemmen med indexnamnet pattern som definieras av count.name . Det här värdet kan sedan refereras till i villkoret where genom att anropa en särskild mallfunktion: current('pattern') .

Villkoret är bara sant om antalet resultat är större än 0.

Om du vill göra villkoret ovan mer allmänt använder du parameterreferensen i stället för en literalmatris:

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

När value count-uttrycket inte finns under något annat count-uttryck är valfritt count.name och funktionen kan användas utan current() argument:

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

Värdeantal stöder också matriser med komplexa objekt, vilket möjliggör mer komplexa villkor. Följande villkor definierar till exempel ett önskat taggvärde för varje namnmönster och kontrollerar om resursnamnet matchar mönstret, men inte har det taggvärde som krävs:

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

Användbara exempel finns i exempel på värdeantal.

Referera till matrisresursegenskaper

Många användningsfall kräver arbete med matrisegenskaper i den utvärderade resursen. Vissa scenarier kräver referens till en hel matris (till exempel för att kontrollera dess längd). Andra kräver att ett villkor tillämpas på varje enskild matrismedlem (se till exempel till att all brandväggsregel blockerar åtkomst från Internet). Att förstå de olika Azure Policy kan referera till resursegenskaper och hur dessa referenser beter sig när de refererar till matrisegenskaper är nyckeln för att skriva villkor som omfattar dessa scenarier.

Referera till resursegenskaper

Resursegenskaper kan refereras av Azure Policy med hjälp av alias Det finns två sätt att referera till värdena för en resursegenskap i Azure Policy:

• Använd fältvillkor för att kontrollera om alla valda resursegenskaper uppfyller ett villkor. Exempel:

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

• Använd field() funktionen för att komma åt värdet för en egenskap. Exempel:

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

Fältvillkoret har ett implicit "allt av"-beteende. Om aliaset representerar en samling värden kontrolleras om alla enskilda värden uppfyller villkoret. Funktionen field() returnerar de värden som representeras av aliaset som de är, som sedan kan ändras av andra mallfunktioner.

Referera till matrisfält

Matrisresursegenskaper representeras av två olika typer av alias. Ett "normalt" alias och matrisalias som har [*] kopplats till det:

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

Referera till matrisen

Det första aliaset representerar ett enda värde, värdet för stringArray egenskapen från begärandeinnehållet. Eftersom värdet för egenskapen är en matris är det inte användbart i principvillkor. Exempel:

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

Det här villkoret jämför hela stringArray matrisen med ett enda strängvärde. De flesta villkor, equals inklusive , accepterar endast strängvärden, så det finns inte mycket användning för att jämföra en matris med en sträng. Huvudscenariot där det är användbart att referera till matrisegenskapen är när du kontrollerar om den finns:

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

Med funktionen är det returnerade värdet matrisen från begärandeinnehållet, som sedan kan användas med alla mallfunktioner som stöds och field() som accepterar matrisargument. Följande villkor kontrollerar till exempel om längden på stringArray är större än 0:

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

Referera till samlingen med matrismedlemmar

Alias som använder syntaxen representerar en samling egenskapsvärden som valts från en matrisegenskap , vilket skiljer sig [*] från att välja själva matrisegenskapen. När det gäller Microsoft.Test/resourceType/stringArray[*] returnerar den en samling som har alla medlemmar i stringArray . Som tidigare nämnts kontrollerar ett villkor att alla valda resursegenskaper uppfyller villkoret. Därför är följande villkor endast sant om alla medlemmar i är lika med field stringArray "värde".

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

Om matrisen innehåller objekt kan [*] ett alias användas för att välja värdet för en specifik egenskap från varje matrismedlem. Exempel:

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

Det här villkoret gäller om värdena för alla property egenskaper i är lika med objectArray "value" . Fler exempel finns i Ytterligare [ * ] aliasexempel.

När du använder field() funktionen för att referera till ett matrisalias är det returnerade värdet en matris med alla valda värden. Det här beteendet innebär att funktionens vanliga användningsfall, möjligheten att field() tillämpa mallfunktioner på resursegenskapsvärden, är begränsad. De enda mallfunktioner som kan användas i det här fallet är de som accepterar matrisargument. Det är till exempel möjligt att hämta längden på matrisen med [length(field('Microsoft.Test/resourceType/objectArray[*].property'))] . Mer komplexa scenarier som att tillämpa mallfunktionen på varje matrismedlem och jämföra den med ett önskat värde är dock bara möjliga när du använder count uttrycket. Mer information finns i Uttryck för antal fält.

Sammanfattningsvis kan du se följande exempel på resursinnehåll och de valda värden som returneras av olika alias:

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

När du använder fältvillkoret för exempelresursinnehållet blir resultatet följande:

När du field() använder funktionen i exempelresursinnehållet blir resultatet följande:

Uttryck för antal fält

Fältantalsuttryck räknar hur många matrismedlemmar som uppfyller ett villkor och jämför antalet med ett målvärde. Count är mer intuitivt och flexibelt för utvärdering av matriser jämfört med field villkor. Syntax:

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

När det används utan where ett villkor count returnerar det helt enkelt längden på en matris. Med exempelresursinnehållet från föregående avsnitt utvärderas följande uttryck till eftersom count true har tre stringArray medlemmar:

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

Det här beteendet fungerar även med kapslade matriser. Till exempel utvärderas följande count uttryck till eftersom det finns fyra true matrismedlemmar i nestedArray matriserna:

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

Kraften i count är i where villkoret. När den har angetts räknar Azure Policy upp matrismedlemmarna och utvärderar var och en mot villkoret och räknar hur många matrismedlemmar som utvärderas till true . Mer specifikt väljer Azure Policy i varje iteration av villkorsutvärderingen en enda matrismedlem * i _ och utvärderar resursinnehållet mot villkoret som om * i är den enda medlemmen i where where array_. __ Att bara ha en matrismedlem tillgänglig i varje iteration är ett sätt att tillämpa komplexa villkor på varje enskild matrismedlem.

Exempel:

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

För att utvärdera uttrycket Azure Policy villkoret tre gånger, en gång för varje medlem i , och räknar hur många gånger det count where stringArray utvärderades till true . När villkoret where refererar till matrismedlemmarna, i stället för att välja alla medlemmar i , väljer det bara Microsoft.Test/resourceType/stringArray[*] en enda stringArray matrismedlem varje gång:

returnerar count 1 .

Här är ett mer komplext uttryck:

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

returnerar count 1 .

Det faktum att uttrycket utvärderas mot hela begärandeinnehållet (med ändringar av matrismedlemmen som för närvarande räknas upp) innebär att villkoret även kan referera till fält utanför where where matrisen:

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

Kapslade antalsuttryck kan användas för att tillämpa villkor på kapslade matrisfält. Följande villkor kontrollerar till exempel att objectArray[*] matrisen har exakt två medlemmar med nestedArray[*] som innehåller en eller flera medlemmar:

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

Eftersom båda medlemmarna i objectArray[*] har en underordnad matris med två medlemmar nestedArray[*] returnerar det yttre count-uttrycket 2 .

Mer komplext exempel: kontrollera att objectArray[*] matrisen har exakt två medlemmar med nestedArray[*] alla medlemmar som är lika med eller 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
}

Eftersom båda medlemmarna i objectArray[*] har en underordnad matris som innehåller nestedArray[*] antingen eller 2 3 returnerar det yttre count-uttrycket 2 .

Åtkomst till aktuell matrismedlem med mallfunktioner

När du använder mallfunktioner använder du funktionen för att komma åt värdet för den current() aktuella matrismedlemmen eller värdena för någon av dess egenskaper. Om du vill komma åt värdet för den aktuella matrismedlemmen skickar du aliaset som definierats i eller något av dess underordnade count.field alias som ett argument till current() funktionen. Exempel:

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

Fältfunktionen inuti where-villkor

Funktionen kan också användas för att komma åt värdet för den aktuella matrismedlemmen så länge count-uttrycket inte finns i ett villkor (funktionen refererar alltid till den resurs som utvärderas i field() field() if-villkoret). Beteendet field() för när du refererar till den utvärderade matrisen baseras på följande begrepp:

1. Matrisalias matchas till en samling värden som valts från alla matrismedlemmar.
2. field() funktioner som refererar till matrisalias returnerar en matris med de valda värdena.
3. Om du refererar till det räknade matrisaliaset i villkoret returneras en samling med ett enda värde valt från matrismedlemmen som utvärderas i den where aktuella iterationen.

Det här beteendet innebär att när du refererar till den räknade matrismedlemmen med en funktion inuti villkoret field() where returneras en matris med en enda medlem. Även om det här beteendet kanske inte är intuitivt stämmer det överens med idén att matrisalias alltid returnerar en samling valda egenskaper. Här är ett exempel:

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

När du behöver komma åt värdet för det räknade matrisaliaset med en funktion är därför sättet att göra det att omsluta field() det med en first() mallfunktion:

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

Användbara exempel finns i Exempel på antal fält.

Ändra matriser

Lägg till och ändra egenskaper för en resurs under skapande eller uppdatering. När du arbetar med matrisegenskaper beror beteendet för dessa effekter på om åtgärden försöker ändra [*] aliaset eller inte:

Mer information finns i exemplen med tillägg.

Ytterligare [*] aliasexempel

Vi rekommenderar att du använder uttrycken för antal fält för att kontrollera om "alla" eller "alla" medlemmarna i en matris i begärandeinnehållet uppfyller ett villkor. För vissa enkla villkor är det dock möjligt att uppnå samma resultat genom att använda en fältåtkomst med ett matrisalias enligt beskrivningen i Referera till samlingen med matrismedlemmar. Det här mönstret kan vara användbart i principregler som överskrider gränsen för tillåtna antal uttryck. Här följer några exempel på vanliga användningsfall:

Exempelprincipregeln för scenariotabellen nedan:

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

Matrisen ipRules är följande för scenariotabellen nedan:

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

Ersätt med för varje villkorsexempel <field> "field": "Microsoft.Storage/storageAccounts/networkAcls.ipRules[*].value" nedan.

Följande resultat är resultatet av kombinationen av villkoret och exempelprincipregeln och matrisen med befintliga värden ovan:

Nästa steg

• Granska exempel på Azure Policy exempel.
• Granska Azure Policy-definitionsstrukturen.
• Granska Förstå policy-effekter.
• Förstå hur du programmässigt skapar principer.
• Lär dig hur du åtgärdar icke-kompatibla resurser.
• Granska vad en hanteringsgrupp är med Organisera dina resurser med Azure-hanteringsgrupper.