Unclear docs and error message for --match-conditions format

[ssolders]

Related command

az network application-gateway waf-policy custom-rule create \
--resource-group my-group \
--policy-name my-policy \
--name azuredevopsip \
--priority 10 \
--rule-type MatchRule \
--match-conditions '[{"variables": "RemoteAddr","operator":"IPMatch","values": ["'"$CURRENT_IP"'"]}]' \
--action Allow

Is your feature request related to a problem? Please describe.
When reading docs / looking at examples, I was not able to find any relevant information about how --match-conditions should be formatted.

When I ran this command I got the error Failed to parse '--match-conditions' argument: Model 'AAZObjectArg' has no field named 'RemoteAddr'

When running --match-conditions with ?? for docs it suggested variables [Required] Space-separated list of variables to use when matching. Variable values: RemoteAddr, RequestMethod, QueryString, PostArgs, RequestUri, RequestHeaders, RequestBody, RequestCookies. Try "??" to show more..

Documentation on azure-cli docs doesn't present any examples on --match-conditions.

Solution to this was to pass variables as an array of objects, where each key should have one of the values from RemoteAddr, RequestMethod, QueryString, PostArgs, RequestUri, RequestHeaders, RequestBody, RequestCookie.

Correct format:

--match-conditions '[{"variables":[{"variableName":"RemoteAddr"}],"operator":"IPMatch","values": ["'"$CURRENT_IP"'"]}]'

Describe the solution you'd like
The error message returned did not describe clear enough what the problem was, it suggested the variables key was not correct, but the docs referred to that it should be one of the RemoteAddr, RequestMethod, QueryString, PostArgs, RequestUri, RequestHeaders, RequestBody, RequestCookie.

Describe alternatives you've considered
Including example payloads of --match-conditions.

Additional context

[yonzhan]

Thank you for opening this issue, we will look into it.

[necusjz]

documentation of shorthand syntax https://github.com/Azure/azure-cli/blob/dev/doc/shorthand_syntax.md

[ssolders]

documentation of shorthand syntax https://github.com/Azure/azure-cli/blob/dev/doc/shorthand_syntax.md

Yea I found my way there, the error message I got linked to that page, but I didn't get any help from it.
If the docs had also contained a few examples it would have helped a lot, a few common use cases.

The error message states that it should be a space separated list which is not true since it must be a list of objects in the format e.g {"variableName":"RemoteAddr"}

[pmeems]

I agree with @ssolders it is hard to understand the correct syntax.
We need improved documentation with examples how to use it.

I've tried several variants of this in my PowerShell script, but can't get it to work:

az network application-gateway waf-policy custom-rule create `
    --resource-group $ResourceGroupName `
    --name $RuleName `
    --policy-name $WafPolName `
    --action $Action `
    --priority $Priority `
    --match-conditions '[{variables:[{variableName:'$matchVariable'}],operator:'$Operator',values: '$value'}]' `
    --rule-type MatchRule

For the above command I get this error:

Error formatting a string: Input string was not in a correct format. Failure to parse near offset 4. Unexpected closing brace without a corresponding opening brace..

[pmeems]

After a full day of trial-and-error, Googling, and even a little bit of ChatGPT I found a working solution:

$matchCondition = @"
[{
    "variables": [
        {
            "variableName": "$matchVariable"
        }
    ],
    "operator": "$Operator",
    "values": [
        "$value"
    ]
}]
"@

az network application-gateway waf-policy custom-rule create `
    --resource-group $ResourceGroupName `
    --name $RuleName `
    --policy-name $WafPolName `
    --action $Action `
    --priority $Priority `
    --match-conditions $matchCondition `
    --rule-type MatchRule

I hope this will help somebody.

[edsaantos]

Com base na resposta do @pmeems, consegui executar no bash dessa forma:

az network application-gateway waf-policy custom-rule create --action Allow \
--name $rule_name --policy-name $policy --priority $priority \
--resource-group $rg --rule-type MatchRule \
--match-conditions "[{"variables":[{"variableName":"RemoteAddr"}],"operator":"IPMatch","values":["$agent_ip"]}]"

[ilyaro]

Hi

IMHO, it just requires a change of manual from list type to dict type

$ az network application-gateway waf-policy custom-rule create --policy-name AllowAWSBlockAllWAFPolicy --resource-group tf --name AllowSpecificIPs --priority 1 --action Allow --rule-type MatchRule --match-conditions "[{"variables":["RemoteAddr"],"operator":"IPMatch","values":["3.3.2.3"]}]"

Failed to parse '--match-conditions' argument: Invalid at [0] : Invalid 'variables' : Invalid at [0] : dict type value expected, got 'RemoteAddr'(<class 'str'>)

It is written in error that the dictionary type is expected when I gave it the list as written in the manual

In the latest version of az cli
$ az version
"azure-cli": "2.67.0",

In the documentation, it is written that "variables" is a list type

$ az network application-gateway waf-policy custom-rule create --match-conditions ??
variables [Required] : Space-separated list of variables to use when matching. Variable values:
RemoteAddr, RequestMethod, QueryString, PostArgs, RequestUri,

So the fix here IMHO is to change the documentation:
variables [Required] : dict type of variables and give example: --match-conditions "[{"variables":[{"variableName":"RemoteAddr"}],"operator":"IPMatch","values":["3.3.2.3"]}]"