你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
本文重点介绍以下 GitHub 存储库中提供的 Azure PowerShell 概念和参考内容:
版本
与大多数 Microsoft Learn 文档不同,azure-docs-powershell 存储库中的 Azure PowerShell 内容支持多个受支持的版本。 有关支持的版本的详细信息,请参阅 Azure PowerShell 支持生命周期。
如果文章引用预览模块中的 cmdlet,则必须显式安装该模块,除非已安装 AzPreview 模块。 这是因为,只有一般可用(GA)模块才包含在 Az PowerShell 模块。
重要
请勿在文章中使用来自 AzureRM PowerShell 模块的命令。 AzureRM 已弃用。
先决条件
始终先满足 Azure 服务先决条件,然后遵循 Azure PowerShell 和 Azure Cloud Shell 说明进行操作。 例如,“你必须具有 Microsoft.Authorization/roleAssignments/write
权限才能完成本教程中的说明”应该排在第一位。
如果所有命令都与 Cloud Shell 不兼容,请指示用户在本地安装 Az PowerShell 模块。 请在 H2 先决条件部分中加入以下文本。
- This tutorial requires that you run Azure PowerShell locally:
- [Install the latest version of the Az PowerShell module](/powershell/azure/install-azure-powershell).
- Connect to your Azure account using the
[Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount) cmdlet.
段落中语法元素的格式化
按照 PowerShell-Docs 样式指南 和 编辑检查清单,在 Azure PowerShell 文档中格式化命令语法元素。
在段落中提及 cmdlet 名称时,请勿链接到 cmdlet 文档。 相反,用反引号将 cmdlet 名称括起来,这是内联代码 ('') 的样式。 在页面底部添加参考部分。 在引用部分列出 cmdlet 名称,并链接到其关联的参考文章。 例如:
This is an example of using the `Connect-AzAccount` and `Get-AzVM` cmdlets within a
paragraph.
## References
- [Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount)
- [Get-AzVM](/powershell/module/az.compute/get-azvm)
注释
不要在超链接的方括号内设置文本的格式。 有关链接到 Azure PowerShell 内容的详细信息,请参阅链接到其他文档。
参数顺序
Azure PowerShell cmdlet 的参数应按 cmdlet 帮助定义的顺序显示。 cmdlet 可以通过多种方式提供所需的参数。 执行该操作时,请遵循要演示的用法的参数集。 Connect-AzAccount
是具有多种调用方法的 cmdlet 示例。
变量
避免在多个代码块之间重用变量。
读者可能会在不同时间段完成文章的步骤。 如果变量设置不正确,在代码块中使用变量可能会导致错误。 如果必须跨步骤使用变量,请明确说明在后续步骤中重复使用变量。
为新资源随机分配密码
如果要创建具有与之关联的密码的资源,则不要使用硬编码的密码。 将密码签入源代码管理(甚至示例)是一种安全风险。
如果文章中的 Azure 资源需要纯文本密码,请使用 Read-Host
允许用户定义其密码。 MaskInput 参数可防止在 PowerShell 历史记录中记录密码。
$password = Read-Host 'Enter a Password' -MaskInput
避免命名冲突
某些 Azure 资源(如 Azure 容器注册表和 Key Vault)具有与域名关联的资源。 这些资源必须具有全局唯一的名称。 因此,当需要唯一性时,请使用随机值作为名称的一部分。 否则,当多个用户运行这些资源时,脚本无法创建所需的资源。 随机性不会阻止冲突,但可以缓解冲突。
使用 Get-Random
将随机数添加到名称中,例如:
$newAcrName = "myacr-$(Get-Random)"
交互式代码片段
何时使用交互式代码片段
如果 Cloud Shell 支持文章中的每个 Azure PowerShell 命令,请使用 azurepowershell-interactive
标记代码块,以将打开 Cloud Shell 按钮添加到代码片段:
```azurepowershell-interactive
Get-AzResourceGroup | Select-Object -Property ResourceGroupName, Location
```
何时不使用交互式代码片段
如果文章包含azurepowershell-interactive
在 Cloud Shell 中不起作用的 Azure PowerShell 命令,请不要使用 。 仅使用 azurepowershell
。 例如,Cloud Shell 不支持 Install-AzAksCliTool
cmdlet:
Install-AzAksCliTool
如果将 Cloud Shell 功能命令与在 Cloud Shell 中不起作用的命令混合使用,当只有一些命令起作用时,可能会让客户感到沮丧。 相反,请坚持在所有代码块中使用 azurepowershell
语言标记,以避免混淆。
由于用户已在登录到 Cloud Shell 时进行身份验证,因此不要对仅包含 azurepowershell-interactive
的代码块使用 Connect-AzAccount
标记。 请改用 azurepowershell
语言标记。
将 AzureRM 更新到 Az PowerShell 模块
有关如何将使用 AzureRM PowerShell 模块的命令更新到 Az PowerShell 模块的信息,请参阅将 Azure PowerShell 从 AzureRM 迁移到 Az。