Crie consultas para listar recursos em lote de forma eficiente

A maioria dos aplicativos de Lote do Azure faz monitoramento ou outras operações que consultam o serviço de Lote. Essas consultas de lista geralmente acontecem em intervalos regulares. Por exemplo, antes de verificar se há tarefas em fila em um trabalho, você deve obter dados sobre cada tarefa nesse trabalho. Reduzir a quantidade de dados que o serviço em lote retorna para consultas melhora o desempenho do seu aplicativo. Este artigo explica como criar e executar essas consultas de forma eficiente. Pode criar consultas filtradas para trabalhos em lote, tarefas, nós de computação e outros recursos com o Azure. Compute.Batch biblioteca.

Especificar um nível de detalhe

Pode haver milhares de entidades, como trabalhos, tarefas e nós de computação em um aplicativo de lote de produção. Para cada consulta feita sobre os recursos, uma quantidade potencialmente grande de dados vai do serviço Batch para seu aplicativo. Limite quantos itens e quais informações sua consulta retorna para melhorar o desempenho.

Este fragmento de código da API Azure.Compute.Batch lista cada tarefa associada a um trabalho, juntamente com todas as propriedades de cada tarefa.

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

Aplique um nível de detalhe à sua consulta para listar informações de forma mais eficiente. Passe as cadeias filter, select e expand ao método BatchClient.GetTasks. Esse trecho retorna apenas as propriedades de ID, linha de comando e informações de nó de computação de tarefas concluídas.

// 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" });

Neste cenário de exemplo, se houver milhares de tarefas no trabalho, os resultados da segunda consulta normalmente são retornados mais rapidamente do que da primeira consulta. Para mais informações sobre o uso dos parâmetros filter, select e expand com os Azure. API Compute.Batch, veja a secção Consulta eficiente em Azure. Compute.Batch.

Usar cadeias de caracteres de consulta

Podes usar o Azure. Compute.Batch e Batch REST para reduzir o número de itens que uma consulta devolve e a quantidade de informação que a consulta devolve para cada item. Há três tipos de cadeia de caracteres de consulta que você pode usar para restringir sua consulta: $filter, $select e $expand.

Para a API Azure.Compute.Batch, consulte a referência BatchClient para o método list cujos parâmetros filter, select e expand pretende utilizar. Revise também a secção Consultas eficientes em Azure. Compute.Batch.

Para a API REST em lote, consulte a referência da API REST em lote. Localiza a referência da lista para o recurso que desejas consultar. Em seguida, revise a seção Parâmetros de Por exemplo, consulte os parâmetros de URI para Pool - List. Veja também como fazer consultas em lote eficientes com a CLI do Azure.

Filtro

A $filter cadeia de caracteres de expressão reduz o número de itens retornados. Por exemplo, você pode listar apenas as tarefas em execução para um trabalho ou listar apenas os nós de computação que estão prontos para executar tarefas.

Essa cadeia de caracteres consiste em uma ou mais expressões, com uma expressão que consiste em um nome de propriedade, operador e valor. As propriedades que podem ser especificadas são específicas para cada tipo de entidade que você consulta, assim como os operadores com suporte para cada propriedade. Várias expressões podem ser combinadas usando os operadores and lógicos e or.

Este exemplo lista apenas as tarefas de renderização em execução: (state eq 'running') and startswith(id, 'renderTask').

Selecione

A $select cadeia de caracteres de expressão limita os valores de propriedade que são retornados para cada item. Você especifica uma lista de nomes de propriedades separados por vírgulas e somente esses valores de propriedade são retornados para os itens nos resultados da consulta. Você pode especificar qualquer uma das propriedades para o tipo de entidade que está consultando.

Este exemplo especifica que apenas três valores de propriedade devem ser retornados para cada tarefa: id, state, stateTransitionTime.

Expandir

A $expand cadeia de caracteres de expressão reduz o número de chamadas de API necessárias para obter determinadas informações. Você pode usar essa cadeia de caracteres para obter mais informações sobre cada item com uma única chamada de API. Esse método ajuda a melhorar o desempenho reduzindo as chamadas de API. Utilize uma $expand string em vez de obter a lista de entidades e solicitar informações sobre cada item da lista.

Semelhante ao $select, $expand controla se determinados dados são incluídos nos resultados da consulta de lista. Quando todas as propriedades são necessárias e nenhuma string de seleção é especificada, $expanddeve ser usado para obter informações estatísticas. Se uma string select for usada para obter um subconjunto de propriedades, ela stats poderá ser especificada na string select e $expand não precisará ser especificada.

Os usos suportados desta string incluem a listagem de trabalhos, cronogramas, tarefas e pools. Atualmente, a cadeia de caracteres suporta apenas informações estatísticas.

Este exemplo especifica que as informações estatísticas devem ser retornadas para cada item da lista: stats.

Regras para filtrar, selecionar e expandir cadeias de caracteres

• Certifique-se de que os nomes das propriedades nas cadeias de filtro, seleção e expansão se apresentem como na Batch REST API. Esta regra aplica-se mesmo quando usas Azure. Compute.Batch ou um dos outros SDKs do Batch.
• Todos os nomes de propriedade diferenciam maiúsculas de minúsculas, mas os valores de propriedade não diferenciam maiúsculas de minúsculas.
• As cadeias de caracteres de data/hora podem ser um de dois formatos e devem ser precedidas de 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'
• As cordas booleanas são ou true ou false.
• Se uma propriedade ou operador inválido for especificado, ocorrerá um 400 (Bad Request) erro.

Consultas eficientes no Azure.Compute.Batch

No Azure. API Compute.Batch, os métodos de lista em BatchClient aceitam diretamente os parâmetros filter, select e expand:

• filter: Limite o número de itens devolvidos.
• select: Especifique quais os valores das propriedades que são devolvidos com cada item.
• expand: Recuperar os dados de todos os itens numa única chamada API em vez de chamadas separadas para cada item.

O seguinte excerto de código utiliza o Azure. Compute.Batch API para consultar eficientemente o serviço Batch para obter as estatísticas de um conjunto específico de pools. O utilizador do Batch tem pools de teste e produção. Os IDs do pool de testes são prefixados com "test" e os IDs do pool de produção são prefixados com "prod". myBatchClient é uma instância inicializada corretamente da classe 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);
}

Mapeamentos de REST em lote para API .NET

Os nomes de propriedade em cadeias de caracteres de filtro, seleção e expansão devem refletir as suas contrapartes da API REST, tanto no nome quanto na distinção entre maiúsculas e minúsculas. As tabelas abaixo fornecem mapeamentos entre as contrapartes da API .NET e REST.

Mapeamentos para cadeias de caracteres de filtro

• Métodos de lista do .NET: Cada um dos métodos da API do .NET nesta coluna aceita parâmetros de cadeia de carateres filter, select e expand.
• Solicitações de lista REST: cada página da API REST listada nesta coluna contém uma tabela com as propriedades e operações permitidas em cadeias de caracteres de filtro. Pode usar estes nomes de propriedades e operações quando constrói uma filter cadeia.

Mapeamentos para cadeias de caracteres selecionadas

• Tipos de Azure.Compute.Batch: Tipos da API Azure.Compute.Batch.
• Entidades da API REST: cada página nesta coluna contém uma ou mais tabelas que listam os nomes das propriedades da API REST para o tipo. Esses nomes de propriedade são usados quando você constrói cadeias de caracteres de seleção . Usas esses mesmos nomes de propriedades quando constróis uma select cadeia.

Exemplo: construir uma cadeia de caracteres de filtro

Para construir uma cadeia de filtro para o parâmetro de filter um método de lista, encontre a página correspondente da API REST. As propriedades selecionáveis e seus operadores suportados estão na primeira tabela de várias linhas. Por exemplo, para recuperar todas as tarefas cujo código de saída era diferente de zero, marque Listar as tarefas associadas a um trabalho para a cadeia de caracteres de propriedade aplicável e operadores permitidos:

A cadeia de caracteres de filtro relacionada é:

(executionInfo/exitCode lt 0) or (executionInfo/exitCode gt 0)

Exemplo: construir uma string de seleção

Para construir uma select cadeia, encontre a página da API REST correspondente para a entidade que está a listar. As propriedades selecionáveis e seus operadores suportados estão na primeira tabela de várias linhas. Por exemplo, para recuperar apenas a ID e a linha de comando de cada tarefa em uma lista, marque Obter informações sobre uma tarefa:

A seqüência de seleção relacionada é:

id, commandLine

Amostras de código

Consultas de lista eficientes

O projeto de exemplo EfficientListQueries mostra como a consulta de lista eficiente afeta o desempenho do aplicativo. Este aplicativo de console C# cria e adiciona um grande número de tarefas a um trabalho. Depois, a aplicação faz várias chamadas ao método BatchClient.GetTasks, passando diferentes valores de parâmetro de filter, select e expand para variar a quantidade de dados devolvidos. Este exemplo produz resultados semelhantes 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 você pode reduzir muito os tempos de resposta da consulta limitando as propriedades e o número de itens retornados. Você pode encontrar este e outros projetos de exemplo no repositório azure-batch-samples no GitHub.

Biblioteca BatchMetrics

O projeto de exemplo BatchMetrics a seguir demonstra como monitorar com eficiência o progresso do trabalho do Azure Batch usando a API Batch.

Este exemplo inclui um projeto de biblioteca de classes .NET, que você pode incorporar em seus próprios projetos. Há também um programa de linha de comando simples para exercitar e demonstrar o uso da biblioteca.

O aplicativo de exemplo dentro do projeto demonstra estas operações:

• Seleção de atributos específicos para baixar apenas as propriedades necessárias
• Filtrar os tempos de transição de estado para baixar apenas as alterações desde a última consulta

Por exemplo, o método a seguir aparece na biblioteca BatchMetrics. Retorna uma tupla contendo as cadeias select e filter, que especificam que apenas as propriedades id e state devem ser obtidas para as entidades consultadas e que apenas sejam devolvidas as entidades cujo estado tenha mudado desde o parâmetro DateTime especificado.

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

Próximos passos

• Maximize o uso de recursos de computação do Azure Batch com tarefas de nó simultâneas. Alguns tipos de cargas de trabalho podem se beneficiar da execução de tarefas paralelas em nós de computação maiores (mas menores). Confira o cenário de exemplo no artigo para obter detalhes sobre esse cenário.
• Monitore soluções em lote contando tarefas e nós por estado