Customer feedback | clarity needed for optional parameters that are conditionally required

[dbradish-microsoft]

Summary

We have a recurring theme in our customer verbatims that optional parameters are required. See example verbatims in the the table below. There is some information given in error handling, but we need better clarity in our autogenerated content.

The misunderstanding might be coming from the following:

1. We only have two parameter categories: required and optional.
2. This leaves "conditional" parameters sitting under the optional heading.

Request

We either need a third parameter category of conditional or similar, and/or we need our engineering teams to take advantage of the long-summary property and provide this useful information.

Customer suggestion azDO link: https://ceapex.visualstudio.com/Engineering/_workitems/edit/987623 (Permission is required to access.)

Related GitHub filtered query links

Because GitHub issues and customer feedback comes in all shapes and sizes, these links should be considered "90% accurate" for "customer feedback on conditional parameters".

Azure/azure-cli
GitHub issues about optional parameters
GitHub issues about required parameters

Azure/azure-cli-extensions
GitHub issues about optional parameters
GitHub issues about required parameters

Example customer verbatims:

Verbatim date	Reference URL	Verbatim
2025-01-15	https://learn.microsoft.com/en-us/cli/azure/afd/origin-group	The create comand is NOT correct. The following fields are REQUIRED:- Sample size- Successful samples required- Latency sensitivity (in milliseconds)
2025-01-16	https://learn.microsoft.com/en-us/cli/azure/staticwebapp/users	Authorization Provider is REQUIRED.
2024-10-16	https://learn.microsoft.com/en-us/cli/azure/aks/command#az-aks-command-result	When I run the command "az aks command result" without the parameter "--command-id -i", it complains that the parameter is missing. It makes sense, but the documentation still says it's Optional.
2024-06-19	https://learn.microsoft.com/en-us/cli/azure/network/application-gateway/routing-rule	"--priority" is a mandatory parameter not optional
2024-06-14	https://learn.microsoft.com/en-us/cli/azure/communication/email/domain/sender-username	--username is not optional, it is REQUIRED Exception Details: (ObjectMissingRequiredProperty) Missing required property: username. Paths in payload: '$.properties.username' Code: ObjectMissingRequiredProperty Message: Missing required
2024-05-17	https://learn.microsoft.com/en-us/cli/azure/cosmosdb/sql/container/throughput	Is the minimum 4000RUs? I've set autoscale accounts to 1000RUs. https://learn.microsoft.com/en-us/cli/azure/cosmosdb/sql/container/throughput?view=azure-cli-latest#az-cosmosdb-sql-container-throughput-update-optional-parameters
2024-05-15	https://learn.microsoft.com/en-us/cli/azure/functionapp/config/access-restriction	--use-same-restrictions-for-scm-site is not optional for az functionapp config access-restriction set
2024-02-09	https://learn.microsoft.com/en-us/cli/azure/monitor/log-analytics/workspace/table	For the az monitor log-analytics workspace table create the retention and column names are not optional parameters for the command to work as expected, these two flags should not be described as optional.
2024-01-30	https://learn.microsoft.com/en-us/cli/azure/webapp/vnet-integration	If we use "az webapp vnet-integration add" and set vnet and snet (complete path), than vnet is optional. Maybe adjust docu. thanks
2023-09-21	https://learn.microsoft.com/en-us/cli/azure/vmss/run-command	Lists many parameters as optional that the CLI reports as required
2023-08-24	https://learn.microsoft.com/en-us/cli/azure/role/assignment	Using Ubuntu on WSL - For az role assignment list if you do not provide the scope param it errors and fails contrary to this msg: ERROR: group or scope are not required when --all is used
2023-05-04	https://learn.microsoft.com/en-us/cli/azure/keyvault/secret	That --value is an optional parameter ist just wrong according to your installable CLI...
2023-04-07	https://learn.microsoft.com/en-us/cli/azure/datafactory/activity-run	az datafactory activity-run query-by-pipeline-run --last-updated-after --last-updated-before [--continuation-token] [--factory-name] [--filters] [--ids] [--order-by] [--resource-group] [--run-id] [--subscription] In doc page, it said --run-id is optional, but actually, it is required

Disclaimer:
This suggestion assumes there is no customer error in this feedback, just a misunderstanding of when an optional parameter is required.

[yonzhan]

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