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. Você pode criar consultas filtradas para trabalhos em lote, tarefas, nós de computação e outros recursos com a biblioteca .NET em lote.

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 trecho de código da API .NET em lote lista todas as tarefas associadas 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
IPagedEnumerable<CloudTask> allTasks =
    batchClient.JobOperations.ListTasks("job-001");

Aplique um nível de detalhe à sua consulta para listar informações de forma mais eficiente. Forneça um objeto ODATADetailLevel para o método JobOperations.ListTasks . Esse trecho retorna apenas as propriedades de ID, linha de comando e informações de 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 houver milhares de tarefas no trabalho, os resultados da segunda consulta normalmente são retornados mais rapidamente do que da primeira consulta. Para obter mais informações sobre como usar ODATADetailLevel quando você lista itens com a API .NET em lote, consulte a seção Consulta eficiente no .NET em lote.

Usar cadeias de caracteres de consulta

Você pode usar as APIs Batch .NET e Batch REST para reduzir quantos itens uma consulta retorna e quantas informações a consulta retorna 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 .NET em lote, consulte as propriedades da classe ODATADetailLevel. Consulte também a seção Consulta eficiente no Batch .NET.

Para a API REST em lote, consulte a referência da API REST em lote. Localize a referência Lista para o recurso que você deseja consultar. Em seguida, revise a seção Parâmetros de URI para obter detalhes sobre $filter, $selecte $expand. 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. Use uma $expand cadeia de caracteres em vez de obter a lista de entidades e solicitar informações sobre cada item de lista.

Semelhante ao , $expand controla $selectse 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, $expand deve 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 dessa cadeia de caracteres incluem a listagem de trabalhos, agendas de trabalho, 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 em filtrar, selecionar e expandir cadeias de caracteres apareçam como aparecem na API REST em lote. Esta regra se aplica mesmo quando você usa o Batch .NET ou um dos outros SDKs de lote.
• 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 false.
• Se uma propriedade ou operador inválido for especificado, ocorrerá um 400 (Bad Request) erro.

Consulta eficiente no Batch .NET

Na API .NET em lote, a classe ODATADetailLevel fornece filtro, seleção e expansão de cadeias de caracteres para listar operações. A ODataDetailLevel classe tem três propriedades de cadeia de caracteres públicas. Você pode especificar essas propriedades no construtor ou definir as propriedades diretamente no objeto. Em seguida, passe 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 retornados.
• ODATADetailLevel.SelectClause: Especifique quais valores de propriedade são retornados com cada item.
• ODATADetailLevel.ExpandClause: Recupere dados para todos os itens em uma única chamada de API em vez de chamadas separadas para cada item.

O trecho de código a seguir usa a API .NET de lote para consultar o serviço de lote de forma eficiente para obter as estatísticas de um conjunto específico de pools. O usuário do lote 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 .

// 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();

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 suas contrapartes da API REST, tanto em nome quanto em 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 um objeto ODATADetailLevel como parâmetro.
• 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. Você pode usar esses nomes de propriedade e operações ao construir uma cadeia de caracteres ODATADetailLevel.FilterClause .

Mapeamentos para cadeias de caracteres selecionadas

• Tipos .NET em lote: tipos de API .NET em lote.
• 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 . Você usa esses mesmos nomes de propriedade quando constrói uma cadeia de caracteres ODATADetailLevel.SelectClause .

Exemplo: construir uma cadeia de caracteres de filtro

Para construir uma cadeia de caracteres de filtro para ODATADetailLevel.FilterClause, localize a página REST API correspondente. 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 ODATADetailLevel.SelectClause, localize a página da API REST correspondente para a entidade que você está listando. 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. Em seguida, o aplicativo faz várias chamadas para o método JobOperations.ListTasks e passa objetos ODATADetailLevel . Esses objetos são configurados com diferentes valores de propriedade para variar a quantidade de dados a serem retornados. 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. Ele retorna um ODATADetailLevel que especifica que somente as id propriedades e state devem ser obtidas para as entidades consultadas. Também especifica que apenas as entidades cujo estado foi alterado desde o parâmetro especificado DateTime devem ser retornadas.

internal static ODATADetailLevel OnlyChangedAfter(DateTime time)
{
    return new ODATADetailLevel(
        selectClause: "id, state",
        filterClause: string.Format("stateTransitionTime gt DateTime'{0:o}'", time)
    );
}

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