search

Azure / azure-cli

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

Documentation is lacking output details #15702

Open jorgensigvardsson opened 4 years ago

jorgensigvardsson commented 4 years ago

All az cosmosdb sql command documentation is lacking detailed information about the output.

ghost commented 4 years ago

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @Wmengmsft, @MehaKaushik, @shurd, @anfeldma-ms

ghost commented 4 years ago

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @Wmengmsft, @MehaKaushik, @shurd, @anfeldma-ms.

yonzhan commented 4 years ago

cosmosdb

MehaKaushik commented 4 years ago

Hi @jorgensigvardsson Thanks for creating the issue. Can you please be more elaborate on what sort of detailing you are looking for here ? We have our docs in here https://docs.microsoft.com/en-us/cli/azure/cosmosdb/sql?view=azure-cli-latest The same would be shown for each command on using the "help" parameter.

jorgensigvardsson commented 4 years ago

All commands seem to return a response in a structured format. I would like to use the response to figure out what happened. In order to do that, some kind of schema for the output would be nice.

MehaKaushik commented 4 years ago

These are our REST API docs https://docs.microsoft.com/en-us/rest/api/cosmos-db-resource-provider/

The responses would adhere to what is described here. Can you please have a look and let me know is this what you are expecting. The response would look exactly like what is described in there. Make sure to look for 2020-04-01 apiVersion https://docs.microsoft.com/en-us/rest/api/cosmos-db-resource-provider/2020-04-01/databaseaccounts.

Let me know if just the above docs are helpful or if you would want this information to be incorporated in some specific place elsewhere.

jorgensigvardsson commented 4 years ago

Ok, so the az command is tightly coupled to the REST API and a specific version. Would it be possible to reference that, either in the documentation, or using the az command itself? Or am I asking for something that az cli wasn't supposed to do?

I could do integrations against the REST API myself, but that is much more cumbersome from a scripting perspective than running az. As it stands now, the response of the az command kind of lands between a user tool (command line driven) and an API (responds with structured data adhering to an API).

MehaKaushik commented 3 years ago

Makes sense. I understand your ASK better now. We will take this up in a future release of CLI.

markjbrown commented 3 years ago

I'm confused as to what you are asking for.

If you want to learn what the schema is, just run the command. Am I missing something else here?