azcli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

azcli — Azure Command-Line Interface

azcli — Azure命令行界面

Command-line interface for managing Azure resources. Covers

az

and its 200+ command groups for all Azure services.

Docs: https://learn.microsoft.com/en-us/cli/azure/

用于管理Azure资源的命令行界面，涵盖

az

及其200多个适用于所有Azure服务的命令组。

文档：https://learn.microsoft.com/en-us/cli/azure/

Platform Notes (Windows + Git Bash)

平台说明（Windows + Git Bash）

Install:
```
winget install --exact --id Microsoft.AzureCLI
```
(preferred) or MSI from https://aka.ms/installazurecliwindows
After install/update: close and reopen terminal — required for PATH
Config:
```
~/.azure/
```
(credentials, config, profiles)
Secrets: use Key Vault or env vars, never commit credentials
Extensions:
```
az extension add --name NAME
```
(some features require extensions)
Version:
```
az version
```
(check for updates:
```
az upgrade
```
)

安装：
```
winget install --exact --id Microsoft.AzureCLI
```
（推荐）或从https://aka.ms/installazurecliwindows下载MSI安装包
安装/更新后：关闭并重新打开终端 —— 这是更新PATH的必要操作
配置文件路径：
```
~/.azure/
```
（包含凭据、配置、配置文件）
密钥管理：使用Key Vault或环境变量，绝对不要提交凭据到代码仓库
扩展：
```
az extension add --name NAME
```
（部分功能需要安装扩展）
版本查看：
```
az version
```
（检查并更新：
```
az upgrade
```
）

⚠️ Quoting Gotchas

⚠️ 引号使用注意事项

Git Bash, PowerShell, and cmd have different quoting rules for

--query

(JMESPath):

bash

undefined

Git Bash、PowerShell和cmd对于

--query

（JMESPath）的引号使用规则不同：

bash

undefined

Git Bash — use single quotes for JMESPath

Git Bash —— 对JMESPath使用单引号

az vm list --query '[].name' -o tsv

PowerShell — use single quotes or escaped double quotes

PowerShell —— 使用单引号或转义双引号

az vm list --query '[].name' -o tsv

Avoid: Git Bash may mangle double-quoted JMESPath

避免：Git Bash可能会破坏双引号包裹的JMESPath


> **⚠️ Cost**: Commands that create resources (VMs, databases, clusters) incur
> Azure charges. Always confirm subscription and region before creating.


> **⚠️ 成本提示**：创建资源（如虚拟机、数据库、集群）的命令会产生Azure费用。创建前请务必确认订阅和区域。

Agent Safety Model

Agent安全模型

Operations classified by risk. Follow this model for all az commands.

Level	Gate	Examples
READ	Proceed autonomously	`list` , `show` , `get` , `account show` , `monitor log-analytics query`
WRITE	Confirm with user; note cost if billable	`create` , `deploy` , `update` , `az storage blob upload`
DESTRUCTIVE	Always confirm; show what's affected	`delete` , `purge` , `az group delete` , RBAC removal
EXPENSIVE	Confirm + state approximate cost	AKS clusters (~~$70+/mo), SQL Database (~~$5-2k/mo), VMs (~$5-2k/mo)
SECURITY	Confirm + explain impact	NSG rules opening ports, `--allow-unauthenticated` , RBAC owner/contributor grants, Key Vault access policies
FORBIDDEN	Refuse; escalate to human	`az ad app credential reset` with plaintext secrets, `az group delete` on production RGs, passwords in CLI args

Rules:

Never combine
--yes
with destructive operations — it suppresses the only safety gate
Never put passwords/secrets as command-line arguments — visible in process list & shell history
Always use
-o json
for machine-parseable output (agents can't reliably parse tables)
When in doubt, treat as DESTRUCTIVE

操作按风险等级分类。所有az命令都需遵循此模型。

风险等级	操作要求	示例
只读	可自主执行	`list` , `show` , `get` , `account show` , `monitor log-analytics query`
写入	需与用户确认；若产生费用需注明	`create` , `deploy` , `update` , `az storage blob upload`
破坏性	必须确认；需展示受影响对象	`delete` , `purge` , `az group delete` , RBAC权限移除
高成本	需确认并说明大致费用	AKS集群（约70美元+/月）、SQL数据库（约5-2000美元/月）、虚拟机（约5-2000美元/月）
安全相关	需确认并说明影响	NSG规则开放端口、 `--allow-unauthenticated` 、RBAC所有者/参与者权限授予、Key Vault访问策略变更
禁止操作	拒绝执行；需升级至人工处理	使用明文密钥执行 `az ad app credential reset` 、删除生产环境资源组、在CLI参数中传入密码

规则：

绝对不要将
--yes
与破坏性操作结合使用 —— 这会关闭唯一的安全验证关卡
绝对不要将密码/密钥作为命令行参数传入 —— 会在进程列表和Shell历史中暴露
始终使用
-o json
以获得机器可解析的输出（Agent无法可靠解析表格格式）
存疑时，按破坏性操作处理

Command Structure

命令结构

text

az [GROUP] [SUBGROUP] COMMAND [ARGS] [FLAGS]

Key global flags:

--subscription

--output

(

-o

--query

--verbose

--debug

--only-show-errors

--yes

text

az [GROUP] [SUBGROUP] COMMAND [ARGS] [FLAGS]

核心全局参数：

--subscription

、

--output

（缩写

-o

）、

--query

、

--verbose

、

--debug

、

--only-show-errors

、

--yes

Service Reference

服务参考

Service	File	Key Commands
Auth & Config	auth.md	Login, service principals, managed identities, subscriptions, config
IAM & Resources	iam.md	Resource groups, RBAC, Entra ID (Azure AD), Key Vault
Compute & Networking	compute.md	VMs, VNets, NSGs, DNS, load balancers, monitoring
Serverless & Containers	serverless.md	App Service, Functions, Container Apps, AKS, Container Registry
Storage	storage.md	Storage accounts, blobs, file shares, queues, tables
Data	data.md	SQL Database, Cosmos DB, Service Bus, Event Hubs
Automation & CI/CD	automation.md	Scripting, output formats, JMESPath, Bicep/ARM, GitHub Actions

Read the per-service file for full command reference.

服务类别	文档文件	核心命令
身份验证与配置	auth.md	登录、服务主体、托管标识、订阅、配置
IAM与资源	iam.md	资源组、RBAC、Entra ID（Azure AD）、Key Vault
计算与网络	compute.md	虚拟机、虚拟网络、网络安全组、DNS、负载均衡器、监控
无服务器与容器	serverless.md	App Service、Functions、Container Apps、AKS、容器注册表
存储	storage.md	存储账户、Blob、文件共享、队列、表格
数据服务	data.md	SQL Database、Cosmos DB、Service Bus、Event Hubs
自动化与CI/CD	automation.md	脚本编写、输出格式、JMESPath、Bicep/ARM、GitHub Actions

请查看对应服务的文档文件以获取完整命令参考。

Pre-Flight Checks

预检查步骤

Before working with any Azure service:

bash

undefined

在操作任何Azure服务之前，请执行以下步骤：

bash

undefined

1. Logged in?

1. 是否已登录？

az account show -o json

2. Correct subscription?

2. 是否为正确的订阅？

az account show --query '{Name:name, Id:id, State:state}' -o json

3. Change subscription if needed

3. 如需切换订阅

az account set --subscription "<name-or-id>"

4. Default location set?

4. 是否设置了默认区域？

az config get defaults.location 2>/dev/null

5. Set default location (optional)

5. 设置默认区域（可选）

az config set defaults.location=westeurope

6. Resource provider registered? (most are auto-registered)

6. 资源提供程序是否已注册？（大多数会自动注册）

az provider show --namespace Microsoft.ContainerApp --query "registrationState" -o tsv az provider register --namespace Microsoft.ContainerApp --wait

undefined

az provider show --namespace Microsoft.ContainerApp --query "registrationState" -o tsv az provider register --namespace Microsoft.ContainerApp --wait

undefined

Troubleshooting

故障排查

Problem	Diagnosis	Fix
Auth failure	`az account show`	`az login` or check service principal
Permission denied	Check RBAC (see iam.md)	Grant correct role
Provider not registered	Error says which provider	`az provider register --namespace Microsoft.X`
Quota exceeded	Error message	Request increase in Portal or `az quota`
Wrong subscription	`az account show`	`az account set --subscription X`
Wrong region	Check resource's `location`	Recreate in correct region
Extension missing	`az extension list`	`az extension add --name NAME`
Slow commands	Large result set	Use `--query` , `--top` , or `--output tsv`

bash

undefined

问题	诊断方法	解决办法
身份验证失败	执行 `az account show`	执行 `az login` 或检查服务主体配置
权限不足	检查RBAC权限（参考iam.md）	授予正确的角色权限
资源提供程序未注册	错误信息会指明具体提供程序	执行 `az provider register --namespace Microsoft.X`
配额不足	错误信息会提示	在Azure门户或通过 `az quota` 申请配额提升
订阅错误	执行 `az account show`	执行 `az account set --subscription X` 切换订阅
区域错误	检查资源的 `location` 属性	在正确的区域重新创建资源
扩展缺失	执行 `az extension list` 查看已安装扩展	执行 `az extension add --name NAME` 安装对应扩展
命令执行缓慢	结果集过大	使用 `--query` 、 `--top` 或 `--output tsv` 过滤结果

bash

undefined

Debug mode

调试模式

az vm list --debug 2>&1 | head -50

Full environment info

完整环境信息

az version az account show -o json

undefined

az version az account show -o json

undefined

Quick Reference

快速参考

Task	Command
Login	`az login`
Set subscription	`az account set --subscription "NAME_OR_ID"`
Current subscription	`az account show -o json`
List subscriptions	`az account list -o table`
Register provider	`az provider register --namespace Microsoft.X`
List anything	`az RESOURCE list -o json`
Show anything	`az RESOURCE show --name NAME -g RG -o json`
JSON output	`-o json`
TSV (single values)	`-o tsv`
JMESPath query	`--query "expression"`
Suppress prompts ⚠️	`--yes` — suppresses ALL confirmations
Help	`az RESOURCE --help` or `az find "search term"`
Upgrade CLI	`az upgrade`

任务	命令
登录	`az login`
设置订阅	`az account set --subscription "NAME_OR_ID"`
查看当前订阅	`az account show -o json`
列出所有订阅	`az account list -o table`
注册资源提供程序	`az provider register --namespace Microsoft.X`
列出任意资源	`az RESOURCE list -o json`
查看任意资源详情	`az RESOURCE show --name NAME -g RG -o json`
JSON格式输出	`-o json`
TSV格式输出（单值）	`-o tsv`
JMESPath查询	`--query "expression"`
跳过确认提示 ⚠️	`--yes` —— 会跳过所有确认步骤
查看帮助	`az RESOURCE --help` 或 `az find "search term"`
升级CLI	`az upgrade`