使用 Azure CLI 管理 Batch 资源Manage Batch resources with Azure CLI

Azure CLI 是 Azure 的命令行体验,用于管理 Azure 资源。The Azure CLI is Azure's command-line experience for managing Azure resources. 它可以在 macOS、Linux 和 Windows 上使用。It can be used on macOS, Linux, and Windows. Azure CLI 经过了优化,可从命令行管理 Azure 资源。The Azure CLI is optimized for managing and administering Azure resources from the command line. 可以使用 Azure CLI 管理 Azure Batch 帐户,以及管理池、作业、任务等资源。You can use the Azure CLI to manage your Azure Batch accounts and to manage resources such as pools, jobs, and tasks. 对于通过 Batch API、Azure 门户和 Batch PowerShell cmdlet 执行的任务,许多都可以使用 Azure CLI 来编写脚本。With the Azure CLI, you can script many of the same tasks you carry out with the Batch APIs, Azure portal, and Batch PowerShell cmdlets.

本文概述如何将 Azure CLI 2.0 版与 Batch 配合使用。This article provides an overview of using Azure CLI version 2.0 with Batch. 请参阅 Azure CLI 入门,大致了解如何将 CLI 与 Azure 配合使用。See Get started with the Azure CLI for an overview of using the CLI with Azure.

设置 Azure CLISet up the Azure CLI

若要在本地安装 Azure CLI,请执行安装 Azure CLI 中概述的步骤。To install the Azure CLI locally, follow the steps outlined in Install the Azure CLI.

Tip

建议经常更新 Azure CLI 安装,利用服务更新和增强功能。We recommend that you update your Azure CLI installation frequently to take advantage of service updates and enhancements.

命令帮助Command help

在每个命令后面追加 -h 即可在 Azure CLI 中显示该命令的帮助文本。You can display help text for every command in the Azure CLI by appending -h to the command. 忽略任何其他选项。Omit any other options. 例如:For example:

  • 若要获取 az 命令的帮助,请输入:az -hTo get help for the az command, enter: az -h
  • 若要获取 CLI 中所有 Batch 命令的列表,请使用: az batch -hTo get a list of all Batch commands in the CLI, use: az batch -h
  • 若要获取有关创建 Batch 帐户的帮助,请输入: az batch account create -hTo get help on creating a Batch account, enter: az batch account create -h

如有疑问,请使用 -h 命令行选项获取有关任何 Azure CLI 命令的帮助。When in doubt, use the -h command-line option to get help on any Azure CLI command.

另请参阅 Azure CLI 参考文档,详细了解适用于 Batch 的 Azure CLI 命令Additionally, refer to the Azure CLI reference documentation for details about Azure CLI commands for Batch.

登录并进行身份验证Log in and authenticate

若要将 Azure CLI 与 Batch 配合使用,需登录并进行身份验证。To use the Azure CLI with Batch, you need to log in and authenticate. 请执行两个简单的步骤:There are two simple steps to follow:

  1. 登录到 Azure。Log into Azure. 登录到 Azure 即可访问 Azure Resource Manager 命令,包括 Batch Management 服务命令。Logging into Azure gives you access to Azure Resource Manager commands, including Batch Management service commands.
  2. 登录到 Batch 帐户。Log into your Batch account. 登录到 Batch 帐户即可访问 Batch 服务命令。Logging into your Batch account gives you access to Batch service commands.

登录 AzureLog in to Azure

可以通过多种不同的方式登录到 Azure,详见使用 Azure CLI 登录There are a few different ways to log into Azure, described in detail in Log in with Azure CLI:

  1. 以交互方式登录Log in interactively. 从命令行自行运行 Azure CLI 命令时,请以交互方式登录。Log in interactively when you are running Azure CLI commands yourself from the command line.
  2. 使用服务主体登录Log in with a service principal. 从脚本或应用程序运行 Azure CLI 命令时,请使用服务主体登录。Log in with a service principal when you are running Azure CLI commands from a script or an application.

本文的目的是介绍如何以交互方式登录到 Azure。For the purposes of this article, we show how to log into Azure interactively. 在命令行中键入 az loginType az login on the command line:

# Log in to Azure China and authenticate interactively.
az cloud set -n AzureChinaCloud
az login

az login 命令返回一个可用于身份验证的令牌,如下所示。The az login command returns a token that you can use to authenticate, as shown here. 请按提供的说明打开网页,并将令牌提交到 Azure:Follow the instructions provided to open a web page and submit the token to Azure:

登录 Azure

“示例 shell 脚本”部分中列出的示例也演示了如何以交互方式登录到 Azure,从而启动 Azure CLI 会话。The examples listed in the Sample shell scripts section also show how to start your Azure CLI session by logging into Azure interactively. 登录后,即可调用命令来处理 Batch Management 资源,包括 Batch 帐户、密钥、应用程序包和配额。Once you have logged in, you can call commands to work with Batch Management resources, including Batch accounts, keys, application packages, and quotas.

登录到 Batch 帐户Log in to your Batch account

若要使用 Azure CLI 来管理 Batch 资源(例如池、作业和任务),需登录到 Batch 帐户并进行身份验证。To use the Azure CLI to manage Batch resources, such as pools, jobs, and tasks, you need to log into your Batch account and authenticate. 若要登录到 Batch 服务,请使用 az batch account login 命令。To log in to the Batch service, use the az batch account login command.

可以使用两个选项对 Batch 帐户进行身份验证:You have two options for authenticating against your Batch account:

  • 使用 Azure Active Directory (Azure AD) 身份验证By using Azure Active Directory (Azure AD) authentication

    将 Azure CLI 与 Batch 配合使用时,通过 Azure AD 进行身份验证是默认设置,建议用于大多数方案。Authenticating with Azure AD is the default when you use the Azure CLI with Batch, and recommended for most scenarios.

    如上一部分所述,以交互方式登录到 Azure 时,系统会缓存凭据,因此 Azure CLI 可以使用这些相同的凭据将你登录到 Batch 帐户。When you log in to Azure interactively, as described in the previous section, your credentials are cached, so the Azure CLI can log you in to your Batch account using those same credentials. 如果通过服务主体登录到 Azure,也会使用这些凭据登录到 Batch 帐户。If you log in to Azure using a service principal, those credentials are also used to log in to your Batch account.

    Azure AD 的优势是提供基于角色的访问控制 (RBAC)。An advantage of Azure AD is that it offers role-based access control (RBAC). 使用 RBAC 时,用户的访问权限取决于分配给他们的角色,而不是是否拥有帐户密钥。With RBAC, a user's access depends on their assigned role, rather than whether or not they possess the account keys. 可以管理 RBAC 角色而不是帐户密钥,让 Azure AD 负责访问权限和身份验证。Instead of managing account keys, you can manage RBAC roles, and let Azure AD handle access and authentication.

    若要使用 Azure AD 登录到 Batch 帐户,请调用 az batch account login 命令:To log in to your Batch account using Azure AD, call the az batch account login command:

    az batch account login -g myresource group -n mybatchaccount
    
  • 使用“共享密钥”身份验证By using Shared Key authentication

    “共享密钥”身份验证通过帐户访问密钥对适用于 Batch 服务的 Azure CLI 命令进行身份验证。Shared Key authentication uses your account access keys to authenticate Azure CLI commands for the Batch service.

    若要通过创建 Azure CLI 脚本来自动调用 Batch 命令,则可使用“共享密钥”身份验证或 Azure AD 服务主体。If you are creating Azure CLI scripts to automate calling Batch commands, you can use either Shared Key authentication, or an Azure AD service principal. 在某些方案中,使用“共享密钥”身份验证可能比创建服务主体简单。In some scenarios, using Shared Key authentication may be simpler than creating a service principal.

    若要使用“共享密钥”身份验证登录,请在命令行中包括 --shared-key-auth 选项:To log in using Shared Key authentication, include the --shared-key-auth option on the command line:

    az batch account login -g myresourcegroup -n mybatchaccount --shared-key-auth
    

“示例 shell 脚本”部分中列出的示例演示了如何在使用 Azure AD 和共享密钥的情况下,通过 Azure CLI 登录到 Batch 帐户。The examples listed in the Sample shell scripts section show how to log into your Batch account with the Azure CLI using both Azure AD and Shared Key.

使用 Azure Batch CLI 扩展命令Use Azure Batch CLI extension commands

通过安装 Azure Batch CLI 扩展,可以在不编写代码的情况下,使用 Azure CLI 来运行端到端的 Batch 作业。By installing the Azure Batch CLI extension, you can use the Azure CLI to run Batch jobs end-to-end without writing code. 可以执行扩展支持的 Batch 命令,以便使用 JSON 模板通过 Azure CLI 来创建池、作业和任务。Batch commands supported by the extension allow you to use JSON templates to create pools, jobs, and tasks with the Azure CLI. 也可使用扩展 CLI 命令将作业输入文件上传到与 Batch 帐户关联的 Azure 存储帐户,以及从其下载作业输出文件。You can also use the extension CLI commands to upload job input files to the Azure Storage account associated with the Batch account, and download job output files from it. 有关详细信息,请参阅使用 Azure Batch CLI 模板和文件传输For more information, see Use Azure Batch CLI templates and file transfer.

脚本示例Script examples

请参阅 CLI 脚本示例,了解用于完成常规任务的 Batch。See the CLI script examples for Batch to accomplish common tasks. 这些示例涵盖在用于 Batch 的 Azure CLI 中提供的许多命令,这些命令用于创建和管理帐户、池、作业和任务。These examples cover many of the commands available in the Azure CLI for Batch to create and manage accounts, pools, jobs, and tasks.

用于创建资源的 JSON 文件JSON files for resource creation

创建 Batch 资源(如池和作业)时,可以指定包含新资源配置的 JSON 文件,而无需将资源的参数作为命令行选项传递。When you create Batch resources like pools and jobs, you can specify a JSON file containing the new resource's configuration instead of passing its parameters as command-line options. 例如:For example:

az batch pool create my_batch_pool.json

尽管只使用命令行选项即可创建大多数 Batch 资源,但某些功能需要指定 JSON 格式的包含资源详细信息的文件。While you can create most Batch resources using only command-line options, some features require that you specify a JSON-formatted file containing the resource details. 例如,若要指定启动任务的资源文件,必须使用 JSON 文件。For example, you must use a JSON file if you want to specify resource files for a start task.

若要查看创建资源所需的 JSON 语法,请参阅 Batch REST API 参考文档。To see the JSON syntax required to create a resource, refer to the Batch REST API reference documentation. REST API 参考中的每个“添加资源类型”主题都包含用于创建该资源的示例 JSON 脚本。Each "Add resource type" topic in the REST API reference contains sample JSON scripts for creating that resource. 可以将这些示例 JSON 脚本用作模板,以便将 JSON 文件与 Azure CLI 配合使用。You can use those sample JSON scripts as templates for JSON files to use with the Azure CLI. 例如,若要查看用于创建池的 JSON 语法,请参阅向帐户添加池For example, to see the JSON syntax for pool creation, refer to Add a pool to an account.

如需用于指定 JSON 文件的示例脚本,请参阅使用 Batch 运行作业和任务For a sample script that specifies a JSON file, see Run a job and tasks with Batch.

Note

如果在创建资源时指定 JSON 文件,则会忽略在命令行上为该资源指定的任何其他参数。If you specify a JSON file when you create a resource, any other parameters that you specify on the command line for that resource are ignored.

适用于 Batch 资源的高效查询Efficient queries for Batch resources

每个 Batch 资源类型都支持 list 命令,该命令可查询 Batch 帐户并列出该类型的资源。Each Batch resource type supports a list command that queries your Batch account and lists resources of that type. 例如,可以列出帐户中的池以及作业中的任务:For example, you can list the pools in your account and the tasks in a job:

az batch pool list
az batch task list --job-id job001

通过 list 操作查询 Batch 服务时,可以指定一个 OData 子句,以便限制返回的数据量。When you query the Batch service with a list operation, you can specify an OData clause to limit the amount of data returned. 由于所有筛选发生在服务器端,因此只会返回请求的数据。Because all filtering occurs server-side, only the data you request crosses the wire. 执行 list 操作时,使用这些子句可以节省带宽(因而节省了时间)。Use these clauses to save bandwidth (and therefore time) when you perform list operations.

下表介绍 Batch 服务支持的 OData 子句:The following table describes the OData clauses supported by the Batch service:

子句Clause 说明Description
--select-clause [select-clause] 返回每个实体的属性子集。Returns a subset of properties for each entity.
--filter-clause [filter-clause] 仅返回与指定的 OData 表达式匹配的实体。Returns only entities that match the specified OData expression.
--expand-clause [expand-clause] 通过单个基础 REST 调用获取实体信息。Obtains the entity information in a single underlying REST call. expand 子句目前仅支持 stats 属性。The expand clause currently supports only the stats property.

如需演示如何使用 OData 子句的示例脚本,请参阅使用 Batch 运行作业和任务For a sample script that shows how to use an OData clause, see Run a job and tasks with Batch.

若要详细了解如何使用 OData 子句执行高效的列表查询,请参阅高效查询 Azure Batch 服务For more information on performing efficient list queries with OData clauses, see Query the Azure Batch service efficiently.

故障排除提示Troubleshooting tips

排查 Azure CLI 问题时,可以参考以下提示:The following tips may help when you are troubleshooting Azure CLI issues:

  • 使用 -h 获取任何 CLI 命令的 帮助文本Use -h to get help text for any CLI command
  • 使用 -v-vv 显示详细的命令输出。Use -v and -vv to display verbose command output. 包括 -vv 标志时,Azure CLI 显示实际的 REST 请求和响应。When the -vv flag is included, the Azure CLI displays the actual REST requests and responses. 使用这些开关可以方便地显示完整的错误输出。These switches are handy for displaying full error output.
  • 可以使用 --json 选项查看 JSON 格式的命令输出You can view command output as JSON with the --json option. 例如, az batch pool show pool001 --json 以 JSON 格式显示 pool001 的属性。For example, az batch pool show pool001 --json displays pool001's properties in JSON format. 然后,可以复制并修改此输出,以便在 --json-file 中使用(请参阅本文前面的“JSON 文件”)。You can then copy and modify this output to use in a --json-file (see JSON files earlier in this article).

后续步骤Next steps