创建可高效列出 Batch 资源的查询

大多数 Azure Batch 应用程序执行监视或查询 Batch 服务的其他操作。此类列表查询通常定期发生。例如，必须先获取该作业中所有任务的数据，然后才能查看该作业中排队的任务。减少 Batch 服务为查询返回的数据量可提升应用程序的性能。本文介绍如何以有效的方式创建和执行此类查询。可以使用 Azure.Compute.Batch 库为 Batch 作业、任务、计算节点和其他资源创建筛选查询。

注意

Batch 服务为作业中的任务计数以及 Batch 池中的计算节点计数这类常见方案提供 API 支持。可以调用获取任务计数和列出池节点计数操作，而不是使用列表查询。但是，这些更高效的操作会返回更有限的信息，这些信息可能不是最新的。有关详细信息，请参阅按状态分类统计任务和计算节点。

指定详细信息级别

生产型 Batch 应用程序可包含成千上万个作业、任务和计算节点等实体。对于有关资源的每个查询，可能会从 Batch 服务向应用程序传输大量数据。限制查询返回的项数和信息类型，以提升性能。

此Azure.Compute.Batch API 代码片段列出了与某个作业关联的所有任务，以及每个任务的所有属性。

// Get a collection of all of the tasks and all of their properties for job-001
AsyncPageable<BatchTask> allTasks = batchClient.GetTasksAsync("job-001");

为你的查询应用细节级别，以更高效地列出信息。将 filter、select 和 expand 字符串传递给 BatchClient.GetTasks 方法。此代码片段仅返回已完成任务的 ID、命令行和计算节点信息属性。

// Specify filter and select strings to return only a subset of tasks and their properties.
AsyncPageable<BatchTask> completedTasks = batchClient.GetTasksAsync(
    jobId: "job-001",
    filter: "state eq 'completed'",
    select: new[] { "id", "commandLine", "nodeInfo" });

在此示例方案中，如果作业中存在数以千计的任务，则通常情况下，第二个查询的结果的返回速度将快于第一个查询。有关在 Azure.Compute.Batch API 中使用 filter、select 和 expand 参数的详细信息，请参阅 Azure.Compute.Batch 中的高效查询部分。

重要

强烈建议始终向 .NET API 列表调用提供 filter、select 和（如果适当）expand 字符串，以最大程度地提高应用程序的效率和性能。指定详细程度有助于缩短 Batch 服务响应时间、提高网络利用率，以及最大程度减少客户端应用程序的内存使用量。

使用查询字符串

可以使用 Azure。Compute.Batch 和 Batch REST API，以减少查询返回的项数，以及每个项的查询返回的信息量。可以使用三种查询字符串类型来缩小查询范围：$filter、$select 和 $expand。

对于 Azure.Compute.Batch API，请参阅 BatchClient 参考文档，查找包含您要使用的 filter、select 和 expand 参数的 list 方法。另请参阅Azure.Compute.Batch 中的高效查询部分。

有关 Batch REST API，请参阅 Batch REST API 参考。找到您要查询的资源的列表引用。然后，查看“URI 参数”部分，了解关于、$filter 和 $select 的详细信息。例如，请参阅池 - 列表的 URI 参数。另请参阅如何使用 Azure CLI 进行高效的 Batch 查询。

注意

构造三种查询字符串之一时，必须确保属性名称和大小写与相应的 REST API 元素相匹配。例如，使用 .NET BatchTask 类时，必须指定 state而不是 State，即使.NET属性为 BatchTask.State。有关详细信息，请参阅 .NET 和 REST API 之间的属性映射。

筛选器

$filter 表达式字符串用于减少返回的项数。例如，可以只列出某个作业的正在运行的任务，或者只列出已准备好运行任务的计算节点。

此字符串包含一个或多个表达式，其中一个表达式包含属性名称、运算符和值。能够指定哪些属性取决于所查询的每个实体类型，每个属性所支持的运算符也是这样。可以使用逻辑运算符 and 和 or 将多个表达式组合到一起。

此示例仅列出正在运行的呈现任务：(state eq 'running') and startswith(id, 'renderTask')。

选择

$select 表达式字符串用于限制针对每个项返回的属性值。可以指定以逗号分隔的属性名称列表，并且仅针对查询结果中的项返回这些属性值。可以指定所查询的实体类型的任意属性。

此示例指定每项任务只应返回三个属性值：id, state, stateTransitionTime。

展开

$expand 表达式字符串用于减少获取特定信息所需的 API 调用数。可以使用此字符串通过单个 API 调用获取有关每个项的详细信息。此方法通过减少 API 调用来帮助提升性能。使用 $expand 字符串，而不是获取实体列表并请求有关每个列表项的信息。

与 $select 类似，$expand 用于控制是否将某些数据包括在列表查询结果中。当所有属性都是必需属性且未指定 select 字符串时，必须使用 $expand 来获取统计信息。如果使用了 select 字符串来获取属性的子集，则可在 select 字符串中指定 stats，不需指定 $expand。

此字符串支持用于列出作业、作业计划、任务和池。目前，此字符串仅支持统计信息。

此示例指定应为列表中的每个项返回统计信息：stats。

筛选、选择和扩展字符串的规则

请确保 filter、select 和 expand 字符串中显示的属性名称以同样的方式显示在 Batch REST API 中。即使您使用 Azure.Compute.Batch 或其他 Batch SDK 之一，此规则也同样适用。
所有属性名称均区分大小写，但属性值不区分大小写。
日期/时间字符串可以采用两种格式中的一种，并且必须在前面加上 DateTime。
- W3C-DTF 格式示例：creationTime gt DateTime'2011-05-08T08:49:37Z'
- RFC 1123 格式示例：creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
布尔值字符串为 true 或 false。
如果指定了无效的属性或运算符，则会导致 400 (Bad Request) 错误。

在 Azure.Compute.Batch 中高效查询

在 Azure.Compute.Batch API 中，BatchClient 上的列表方法可直接接受 filter、select 和 expand 参数：

filter：限制返回的项目数。
select：指定每个项返回的属性值。
expand：检索单个 API 调用中的所有项的数据，而不是针对每个项的单独调用。

以下代码片段使用Azure。Compute.Batch API，用于高效查询 Batch 服务，以获取特定池集的统计信息。 Batch 用户既有测试池又有生产池。测试池 ID 具有“test”前缀，生产池 ID 具有“prod”前缀。 myBatchClient 是正确初始化的 BatchClient 类实例。

// Pull only the "test" pools, and limit the data crossing the wire by selecting only
// the Id and Statistics properties. Use expand="stats" so the .NET API pulls the
// statistics for the BatchPools in a single underlying REST API call. Note that we
// use the pool's REST API element name "stats" here as opposed to "Statistics" as it
// appears in the .NET API (BatchPool.Statistics).
List<BatchPool> testPools = new List<BatchPool>();
await foreach (BatchPool pool in myBatchClient.GetPoolsAsync(
    filter: "startswith(id, 'test')",
    select: new[] { "id", "stats" },
    expand: new[] { "stats" }))
{
    testPools.Add(pool);
}

提示

也可以将相同的filter参数selectexpand传递给相应的 Get 方法（如 BatchClient.GetPool），以限制返回的数据量。

批量 REST 到 .NET API 映射

filter、select 和 expand 字符串中的属性名称必须与其 REST API 对应项一致，无论是名称还是大小写。下表提供了 .NET 和 REST API 的对应项之间的映射。

过滤字符串的映射

.NET列表方法：此列中每个.NET API 方法都接受 filter、select 和 expand 字符串参数。
REST 列表请求：此列中列出的每个 REST API 页面都包含一个表，其中包含 filter 字符串中允许的属性和操作。构造 filter 字符串时，可以使用这些属性名称和操作。

.NET 列表方法	REST 列表请求
BatchAccountResource.GetBatchAccountCertificates	列出帐户中的证书
BatchClient.GetTaskFiles	列出与任务关联的文件
BatchClient.GetJobPreparationAndReleaseTaskStatuses	列出作业准备任务状态以及作业发布任务状态
BatchClient.GetJobs	列出帐户中的作业
BatchClient.GetNodeFiles	列出节点上的文件
BatchClient.GetTasks	列出与作业关联的任务
BatchClient.GetJobSchedules	列出帐户中的作业计划
BatchClient.GetJobsFromSchedule	列出与作业计划关联的作业
BatchClient.GetNodes	列出池中的计算节点
BatchClient.GetPools	列出帐户中的池

选择的字符串映射

Azure。Compute.Batch 类型：Azure。Compute.Batch API 类型。
REST API 实体：此列中的每一页都包含一个或多个表，其中列出了类型的 REST API 属性名称。在构造 select 字符串时使用这些属性名称。构造 select 字符串时，请使用这些相同的属性名称。

Azure.Compute.Batch 类型	REST API 实体
批处理作业	获取有关作业的信息
批处理作业调度	获取有关作业计划的信息
批处理节点	获取有关节点的信息
批处理池	获取有关池的信息
批处理任务	获取有关任务的信息

示例：构造过滤器字符串

若要为列表方法 filter 的参数构造筛选器字符串，请查找相应的 REST API 页。可选择属性及其支持的运算符位于第一个多行表中。例如，若要检索其退出代码不为零的所有任务，可查看列出与作业相关联的任务，以了解相应的属性字符串以及允许的运算符：

属性	允许的操作	类型
`executionInfo/exitCode`	`eq, ge, gt, le , lt`	`Int`

示例：构造 select 字符串

若要构造 select 字符串，请查找要列出的实体的相应 REST API 页。可选择属性及其支持的运算符位于第一个多行表中。例如，若要仅检索列表中每项任务的 ID 和命令行，请查看获取有关任务的信息：

属性	类型	注释
`id`	`String`	`The ID of the task.`
`commandLine`	`String`	`The command line of the task.`

代码示例

高效列表查询

EfficientListQueries 示例项目显示了高效的列表查询对应用程序性能的影响。此 C# 控制台应用程序创建大量的任务并将其添加到作业。然后，应用程序对 BatchClient.GetTasks 方法进行多次调用，并传递不同的 filter参数 select值， expand 以改变要返回的数据量。此示例生成类似于如下输出：

Adding 5000 tasks to job jobEffQuery...
5000 tasks added in 00:00:47.3467587, hit ENTER to query tasks...

4943 tasks retrieved in 00:00:04.3408081 (ExpandClause:  | FilterClause: state eq 'active' | SelectClause: id,state)
0 tasks retrieved in 00:00:00.2662920 (ExpandClause:  | FilterClause: state eq 'running' | SelectClause: id,state)
59 tasks retrieved in 00:00:00.3337760 (ExpandClause:  | FilterClause: state eq 'completed' | SelectClause: id,state)
5000 tasks retrieved in 00:00:04.1429881 (ExpandClause:  | FilterClause:  | SelectClause: id,state)
5000 tasks retrieved in 00:00:15.1016127 (ExpandClause:  | FilterClause:  | SelectClause: id,state,environmentSettings)
5000 tasks retrieved in 00:00:17.0548145 (ExpandClause: stats | FilterClause:  | SelectClause: )

Sample complete, hit ENTER to continue...

示例显示了限制返回的属性和项数可以大幅缩短查询响应时间。可以在 GitHub 的 azure-batch-samples 存储库中查找此项目和其他示例项目。

BatchMetrics 库

下列 BatchMetrics 示例项目演示了如何使用 Batch API 有效地监视 Azure Batch 作业进度。

此示例包括一个 .NET 类库项目，可将其合并到自己的项目中。还有一个简单的命令行程序，可用于练习和演示库的用途。

项目中的示例应用程序演示了以下操作：

选择特定属性即可只下载所需属性
若只下载自上次查询以来发生更改的内容，可针对状态转换时间进行筛选

例如，以下方法会显示在 BatchMetrics 库中。它返回一个元组，其中包含 select 和 filter 字符串，用于指定对于所查询的实体，仅应获取 id 和 state 属性，并且仅返回自指定的 DateTime 参数以来状态已发生更改的实体。

return (
    Filter: string.Format("stateTransitionTime gt DateTime'{0:o}'", time),
    Select: new[] { "id", "state" });

后续步骤

通过并发节点任务最大限度提高 Azure Batch 计算资源的使用量。在数量较少但规模更大的计算节点上执行并行任务适合某些类型的工作负载。若需详细了解此类方案，请查看文章中的示例方案。
通过统计不同状态下的任务和节点来监控 Batch 解决方案

Last updated on 2026-06-12