search

Azure / azure-cli

Azure Command-Line Interface
MIT License
4.02k stars 2.99k forks source link

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

Open dbradish-microsoft opened 3 months ago

dbradish-microsoft commented 3 months ago

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
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 commented 3 months ago

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

github-actions[bot] commented 3 months ago

Here are some similar issues that might help you. Please check if they can solve your problem.

microsoft-github-policy-service[bot] commented 3 months ago

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @zhangyd2015, @Frey-Wang, @Jingshu923.

microsoft-github-policy-service[bot] commented 3 months ago

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @kamperiadis, @khkh-ms, @shreyabatra4.

microsoft-github-policy-service[bot] commented 3 months ago

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @SameergMS, @yairgil.

microsoft-github-policy-service[bot] commented 3 months ago

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @AzureAppServiceCLI, @antcp.