Criar consultas para listar recursos do Batch de forma eficiente
A maioria das aplicações Azure Batch monitorização ou outras operações que consultam o serviço Batch. Estas consultas de lista ocorrem frequentemente em intervalos regulares. Por exemplo, antes de poder verificar a existência de tarefas em fila numa tarefa, tem de obter dados sobre todas as tarefas nessa tarefa. Reduzir a quantidade de dados que o serviço Batch devolve para consultas melhora o desempenho da sua aplicação. Este artigo explica como criar e executar essas consultas de forma eficiente. Pode criar consultas filtradas para tarefas do Batch, tarefas, nós de computação e outros recursos com a biblioteca .NET do Batch .
Nota
O serviço Batch fornece suporte de API para os cenários comuns de contagem de tarefas numa tarefa e contagem de nós de computação no conjunto do Batch. Pode chamar as operações Obter Contagens de Tarefas e Contagens de Nós do Conjunto de Listas em vez de utilizar uma consulta de lista. No entanto, estas operações mais eficientes devolvem informações mais limitadas que podem não estar atualizadas. Para obter mais informações, veja Contar tarefas e nós de computação por estado.
Especificar um nível de detalhe
Podem existir milhares de entidades, como trabalhos, tarefas e nós de computação numa aplicação batch de produção. Para cada consulta que fizer sobre os recursos, uma quantidade potencialmente grande de dados vai do serviço Batch para a sua aplicação. Limite quantos itens e que informações a consulta devolve para melhorar o desempenho.
Este fragmento de código da API .NET do Batch lista todas as tarefas associadas a uma tarefa, juntamente com todas as propriedades de cada tarefa.
// Get a collection of all of the tasks and all of their properties for job-001
IPagedEnumerable<CloudTask> allTasks =
batchClient.JobOperations.ListTasks("job-001");
Aplique um nível de detalhe à consulta para listar informações de forma mais eficiente. Forneça um objeto ODATADetailLevel ao método JobOperations.ListTasks . Este fragmento devolve apenas as propriedades de informações de ID, linha de comandos e nó de computação de tarefas concluídas.
// Configure an ODATADetailLevel specifying a subset of tasks and
// their properties to return
ODATADetailLevel detailLevel = new ODATADetailLevel();
detailLevel.FilterClause = "state eq 'completed'";
detailLevel.SelectClause = "id,commandLine,nodeInfo";
// Supply the ODATADetailLevel to the ListTasks method
IPagedEnumerable<CloudTask> completedTasks =
batchClient.JobOperations.ListTasks("job-001", detailLevel);
Neste cenário de exemplo, se existirem milhares de tarefas na tarefa, os resultados da segunda consulta são normalmente devolvidos mais rapidamente do que na primeira consulta. Para obter mais informações sobre como utilizar ODATADetailLevel quando lista itens com a API .NET do Batch, veja a secção Consulta eficiente no Batch .NET.
Importante
Recomendamos vivamente que forneça sempre um ODATADetailLevel objeto à sua lista de API .NET para obter a eficiência máxima e o desempenho da sua aplicação. Ao especificar um nível de detalhe, pode ajudar a reduzir os tempos de resposta do serviço Batch, melhorar a utilização da rede e minimizar a utilização da memória por aplicações cliente.
Utilizar cadeias de consulta
Pode utilizar as APIs REST do Batch .NET e do Batch para reduzir o número de itens devolvidos por uma consulta e a quantidade de informações que a consulta devolve para cada item. Existem três tipos de cadeia de consulta que pode utilizar para restringir a consulta: $filter, $select e $expand.
Para a API .NET do Batch, veja as propriedades classe ODATADetailLevel. Reveja também a secção Consulta eficiente no Batch .NET.
Para a API REST do Batch, veja a referência da API REST do Batch. Localize a referência de Lista para o recurso que pretende consultar. Em seguida, reveja a secção Parâmetros do URI para obter detalhes sobre $filter, $selecte $expand. Por exemplo, veja os parâmetros URI para Conjunto - Lista. Veja também como fazer consultas eficientes do Batch com a CLI do Azure.
Nota
Ao construir qualquer um dos três tipos de cadeia de consulta, tem de garantir que os nomes de propriedades e maiúsculas/minúsculas correspondem aos dos respetivos equivalentes de elementos da API REST. Por exemplo, ao trabalhar com a classe .NET CloudTask , tem de especificar o estado em vez de Estado, mesmo que a propriedade .NET seja CloudTask.State. Para obter mais informações, veja os mapeamentos de propriedades entre as APIs .NET e REST.
Filtro
A $filter cadeia de expressão reduz o número de itens devolvidos. Por exemplo, pode listar apenas as tarefas em execução para uma tarefa ou listar apenas os nós de computação que estão prontos para executar tarefas.
Esta cadeia consiste numa ou mais expressões, com uma expressão que consiste num nome de propriedade, operador e valor. As propriedades que podem ser especificadas são específicas para cada tipo de entidade que consulta, assim como os operadores que são suportados para cada propriedade. Várias expressões podem ser combinadas com os operadores lógicos and e or.
Este exemplo lista apenas as tarefas de composição em execução: (state eq 'running') and startswith(id, 'renderTask').
Selecione
A $select cadeia de expressão limita os valores de propriedade que são devolvidos para cada item. Especifique uma lista de nomes de propriedades separados por vírgulas e apenas esses valores de propriedade são devolvidos para os itens nos resultados da consulta. Pode especificar qualquer uma das propriedades do tipo de entidade que está a consultar.
Este exemplo especifica que apenas devem ser devolvidos três valores de propriedade para cada tarefa: id, state, stateTransitionTime.
Expandir
A $expand cadeia de expressão reduz o número de chamadas à API necessárias para obter determinadas informações. Pode utilizar esta cadeia para obter mais informações sobre cada item com uma única chamada à API. Este método ajuda a melhorar o desempenho ao reduzir as chamadas à API. Utilize uma $expand cadeia em vez de obter a lista de entidades e pedir informações sobre cada item de lista.
Semelhante a $select, $expand controla se determinados dados estão incluídos nos resultados da consulta de lista. Quando todas as propriedades são necessárias e não é especificada nenhuma cadeia de carateres selecionada, $expandtem de ser utilizada para obter informações de estatísticas. Se for utilizada uma cadeia de carateres selecionada para obter um subconjunto de propriedades, stats pode ser especificada na cadeia de seleção e $expand não precisa de ser especificada.
As utilizações suportadas desta cadeia incluem a listagem de tarefas, agendas de tarefas, tarefas e conjuntos. Atualmente, a cadeia só suporta informações de estatísticas.
Este exemplo especifica que as informações das estatísticas devem ser devolvidas para cada item na lista: stats.
Regras para filtrar, selecionar e expandir cadeias
- Certifique-se de que os nomes das propriedades no filtro, selecione e expanda cadeias são apresentados como aparecem na API REST do Batch . Esta regra aplica-se mesmo quando utiliza o Batch .NET ou um dos outros SDKs do Batch.
- Todos os nomes de propriedades são sensíveis a maiúsculas e minúsculas, mas os valores de propriedade não são sensíveis a maiúsculas e minúsculas.
- As cadeias de data/hora podem ser um de dois formatos e têm de ser precedidas com
DateTime.- Exemplo de formato W3C-DTF:
creationTime gt DateTime'2011-05-08T08:49:37Z' - Exemplo de formato RFC 1123:
creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
- Exemplo de formato W3C-DTF:
- As cadeias booleanas são
trueoufalse. - Se for especificada uma propriedade ou operador inválido, resultará um
400 (Bad Request)erro.
Consulta eficiente no Batch .NET
Na API .NET do Batch , a classe ODATADetailLevel fornece filtro, seleciona e expande cadeias para operações de lista. A ODataDetailLevel classe tem três propriedades de cadeia pública. Pode especificar estas propriedades no construtor ou definir as propriedades diretamente no objeto. Em seguida, transmita o ODataDetailLevel objeto como um parâmetro para as várias operações de lista, como ListPools, ListJobs e ListTasks.
- ODATADetailLevel.FilterClause: limite o número de itens devolvidos.
- ODATADetailLevel.SelectClause: especifique que valores de propriedade são devolvidos com cada item.
- ODATADetailLevel.ExpandClause: obtenha dados para todos os itens numa única chamada à API em vez de chamadas separadas para cada item.
O fragmento de código seguinte utiliza a API .NET do Batch para consultar o serviço Batch de forma eficiente para obter as estatísticas de um conjunto específico de conjuntos. O utilizador do Batch tem conjuntos de teste e de produção. Os IDs do conjunto de testes são prefixados com "teste" e os IDs do conjunto de produção são prefixados com "prod". myBatchClient é uma instância inicializada corretamente da classe BatchClient .
// First we need an ODATADetailLevel instance on which to set the filter, select,
// and expand clause strings
ODATADetailLevel detailLevel = new ODATADetailLevel();
// We want to pull only the "test" pools, so we limit the number of items returned
// by using a FilterClause and specifying that the pool IDs must start with "test"
detailLevel.FilterClause = "startswith(id, 'test')";
// To further limit the data that crosses the wire, configure the SelectClause to
// limit the properties that are returned on each CloudPool object to only
// CloudPool.Id and CloudPool.Statistics
detailLevel.SelectClause = "id, stats";
// Specify the ExpandClause so that the .NET API pulls the statistics for the
// CloudPools 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 (CloudPool.Statistics)
detailLevel.ExpandClause = "stats";
// Now get our collection of pools, minimizing the amount of data that is returned
// by specifying the detail level that we configured above
List<CloudPool> testPools =
await myBatchClient.PoolOperations.ListPools(detailLevel).ToListAsync();
Dica
Uma instância de ODATADetailLevel configurada com cláusulas Select e Expand também pode ser transmitida para métodos Get adequados, como PoolOperations.GetPool, para limitar a quantidade de dados devolvidos.
Mapeamentos da API REST do Batch para .NET
Os nomes de propriedades no filtro, selecione e expanda cadeias têm de refletir as respetivas contrapartes da API REST, tanto no nome como no caso. As tabelas abaixo fornecem mapeamentos entre os homólogos da API .NET e REST.
Mapeamentos para cadeias de filtro
- Métodos de lista .NET: cada um dos métodos da API .NET nesta coluna aceita um objeto ODATADetailLevel como um parâmetro.
- Pedidos de lista REST: cada página da API REST listada nesta coluna contém uma tabela com as propriedades e operações permitidas nas cadeias de filtro. Pode utilizar estes nomes de propriedades e operações ao construir uma cadeia ODATADetailLevel.FilterClause .
Mapeamentos para cadeias de carateres selecionadas
- Tipos de .NET do Batch: tipos de API .NET do Batch.
- Entidades da API REST: cada página nesta coluna contém uma ou mais tabelas que listam os nomes de propriedades da API REST do tipo. Estes nomes de propriedades são utilizados quando constrói cadeias de carateres selecionadas . Utiliza estes mesmos nomes de propriedade quando constrói uma cadeia ODATADetailLevel.SelectClause .
Exemplo: construir uma cadeia de filtro
Para construir uma cadeia de filtro para ODATADetailLevel.FilterClause, localize a página da API REST correspondente. As propriedades selecionáveis e os operadores suportados estão na primeira tabela de várias linhas. Por exemplo, para obter todas as tarefas cujo código de saída não era zero, selecione Listar as tarefas associadas a uma tarefa para a cadeia de propriedade aplicável e operadores permitidos:
| Propriedade | Operações permitidas | Tipo |
|---|---|---|
executionInfo/exitCode |
eq, ge, gt, le , lt |
Int |
A cadeia de filtro relacionada é:
(executionInfo/exitCode lt 0) or (executionInfo/exitCode gt 0)
Exemplo: construir uma cadeia de carateres selecionar
Para construir ODATADetailLevel.SelectClause, localize a página da API REST correspondente para a entidade que está a listar. As propriedades selecionáveis e os operadores suportados estão na primeira tabela de várias linhas. Por exemplo, para obter apenas o ID e a linha de comandos de cada tarefa numa lista, consulte Obter informações sobre uma tarefa:
| Propriedade | Tipo | Notas |
|---|---|---|
id |
String |
The ID of the task. |
commandLine |
String |
The command line of the task. |
A cadeia de seleção relacionada é:
id, commandLine
Exemplos de código
Consultas de lista eficientes
O projeto de exemplo EfficientListQueries mostra o quão eficiente é que a consulta de lista afeta o desempenho da aplicação. Esta aplicação de consola C# cria e adiciona um grande número de tarefas a uma tarefa. Em seguida, a aplicação faz várias chamadas para o método JobOperations.ListTasks e transmite objetos ODATADetailLevel . Estes objetos são configurados com diferentes valores de propriedade para variar a quantidade de dados a devolver. Este exemplo produz um resultado semelhante a:
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...
O exemplo mostra que pode reduzir consideravelmente os tempos de resposta das consultas ao limitar as propriedades e o número de itens devolvidos. Pode encontrar este e outros projetos de exemplo no repositório azure-batch-samples no GitHub.
Biblioteca BatchMetrics
O seguinte projeto de exemplo batchMetrics demonstra como monitorizar eficientemente Azure Batch progresso da tarefa com a API do Batch.
Este exemplo inclui um projeto de biblioteca de classes .NET, que pode incorporar nos seus próprios projetos. Também existe um programa de linha de comandos simples para fazer exercício e demonstrar a utilização da biblioteca.
A aplicação de exemplo no projeto demonstra estas operações:
- Selecionar atributos específicos para transferir apenas as propriedades de que precisa
- Filtrar em tempos de transição de estado para transferir apenas alterações desde a última consulta
Por exemplo, o seguinte método é apresentado na biblioteca BatchMetrics. Devolve um ODATADetailLevel que especifica que apenas as id propriedades e state devem ser obtidas para as entidades que são consultadas. Também especifica que apenas as entidades cujo estado foi alterado desde o parâmetro especificado DateTime devem ser devolvidas.
internal static ODATADetailLevel OnlyChangedAfter(DateTime time)
{
return new ODATADetailLevel(
selectClause: "id, state",
filterClause: string.Format("stateTransitionTime gt DateTime'{0:o}'", time)
);
}
Passos seguintes
- Maximize Azure Batch utilização de recursos de computação com tarefas de nós simultâneas. Alguns tipos de cargas de trabalho podem beneficiar da execução de tarefas paralelas em nós de computação maiores (mas menos). Veja o cenário de exemplo no artigo para obter detalhes sobre tal cenário.
- Monitorizar soluções do Batch ao contar tarefas e nós por estado