Description
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:
- We only have two parameter categories:
requiredandoptional. - This leaves "conditional" parameters sitting under the
optionalheading.
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 |
|---|---|---|
| 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.
