Criar consultas para listar recursos do Lote com eficiência

  • Artigo

A maioria dos aplicativos do lote do Azure faz o 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 poder verificar as tarefas em fila em um trabalho, você deve obter dados em cada tarefa nesse trabalho. Reduzir a quantidade de dados que o serviço de lote retorna para consultas melhora o desempenho do aplicativo. Este artigo explica como criar e executar essas consultas da forma mais eficiente. Crie consultas filtradas para trabalhos em lotes, tarefas, nós de computação e outros recursos com a biblioteca .net do Lote.

Observação

O serviço de Lote fornece suporte de API para o cenário comum de tarefas de contagem em um trabalho e contagem de nós de computação no pool do Lote. Em vez de usar uma consulta de lista para elas, você pode chamar as operações Obter Contagens de Tarefas e Listar Contagens de Nós do Pool. No entanto, essas operações mais eficientes retornam 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

Em um aplicativo do Lote de produção, as entidades, como trabalhos, tarefas e nós de computação, podem chegar a milhares. Para cada consulta que você faz sobre os recursos, uma quantidade potencialmente grande de dados vai do serviço de lote para seu aplicativo. Limite o número de itens e as informações que sua consulta retorna para melhorar o desempenho.

Esse snippet de código da API .NET do Lote lista todas as tarefas associadas a um trabalho, bem como 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 com mais eficiência. Você faz isso fornecendo um objeto ODATADetailLevel ao método JobOperations.ListTasks. Este snippet de código retorna apenas a ID, a linha de comando e as propriedades de informações do nó de computação das 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 do exemplo, se houver milhares de tarefas no trabalho, os resultados da segunda consulta serão retornados normalmente muito mais rapidamente do que os da primeira. Para obter mais informações sobre como usar o ODATADetailLevel Ao listar itens com a API .net do lote, consulte a seção Consulta eficiente em .NET do Lote.

Importante

Recomendamos que você sempre forneça um objeto ODATADetailLevel para as chamadas de lista da API .NET para garantir a máxima eficiência e desempenho de seu aplicativo. Ao especificar um nível de detalhe, você ajuda a reduzir os tempos de resposta do serviço Lote, a melhorar a utilização da rede e a minimizar o uso da memória por aplicativos clientes.

Teste as cadeias de consulta

Você pode usar as APIs .NET do Lote e REST do Lote para reduzir a quantidade de itens que uma consulta retorna e quantas informações a consulta retorna para cada item. Há três tipos de cadeia de caracteres de consulta que podem ser usadas para restringir a consulta: $Filter, $Selecte $Expand.

Para a API .NET do lote, consulte as Propriedades da classe ODATADetailLevel. Examine também a seção Consultas eficientes no .NET do lote.

Para a API REST do lote, consulte a Referência da API REST do lote. Localize a referência de lista para o recurso que deseja consultar. Em seguida, examine a seção de Parâmetros de URI para obter detalhes sobre $filter, $select e $expand. Por exemplo, consulte os Parâmetros de URI para Pool - Lista. Veja também Como fazer consultas de lote eficientes com a CLI do Azure.

Observação

Ao criar qualquer um dos três tipos de cadeias de caracteres de consulta, você deve garantir que os nomes de propriedade e caso correspondam aos seus equivalentes de elemento da API REST. Por exemplo, ao trabalhar com a classe CloudTask do .NET, você deve especificar state em vez de State, mesmo que a propriedade .NET seja CloudTask.State. Consulte as tabelas abaixo para ver mapeamentos de propriedade entre o .NET e APIs REST.

Filtrar

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

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

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

Selecionar

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

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

Expanda

A cadeia de caracteres $expand 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 à API. Esse método ajuda a melhorar o desempenho, reduzindo as chamadas de API. Use uma cadeia de caracteres $expand em vez de obter a lista de entidades e solicitar informações sobre cada item de lista.

Assim como a $select, a $expand controla se determinados dados são incluídos nos resultados da consulta de lista. Quando todas as propriedades forem necessárias e nenhuma cadeia de seleção tiver sido especificada, $expandterá que ser usada para obter informações estatísticas. Se uma cadeia de caracteres select for usada para obter um subconjunto de propriedades, stats poderá ser especificado na cadeia select e a $expand não precisará ser especificada.

Os usos com suporte dessa cadeia de caracteres incluem listar trabalhos, agendas de trabalho, tarefas e pools. Atualmente, a cadeia de caracteres dá suporte apenas a informações de estatísticas.

Esse exemplo especifica que as informações de estatística devem ser retornadas para cada item na lista: stats.

Especificações das cadeias de caracteres filter, select e expand

  • Verifique se os nomes das propriedades nas cadeias de caracteres filter, select e expand aparecem como na API REST do Lote. Essa regra se aplica mesmo ao usar o .net do Lote ou um dos outros SDKs do lote.
  • Todos os nomes de propriedade diferenciam maiúsculas de minúsculas, mas valores de propriedade não diferenciam maiúsculas de minúsculas.
  • As cadeias de caracteres de data/hora podem ter um dos dois formatos e devem ser precedidas por 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 cadeias de caracteres boolianas são true ou false.
  • Se uma propriedade ou operador inválido for especificado, o resultado será um erro 400 (Bad Request) .

Consulta eficiente no .NET de Lote

Na API .NET do Lote, a classe ODATADetailLevel é usada para fornecimento de cadeias de caracteres filter, select e expand para as operações da lista. A classe ODataDetailLevel 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, você passa o objeto ODataDetailLevell como um parâmetro para as várias operações da lista, como ListPools, ListJobs e ListTasks.

O snippet de código abaixo usa a API de Lote .NET para consultar o serviço de Lote com eficiência a fim de obter as estatísticas de um conjunto específico de pools. O usuário de Lote tem grupos de teste e de produção. As IDs do pool de teste são prefixadas com "test", e as IDs do grupo de produção são prefixadas com "prod". O myBatchClient é uma instância devidamente inicializada 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 as cláusulas Select e Expand também pode ser passada para os devidos métodos Get, como PoolOperations.GetPool, para limitar a quantidade de dados retornados.

Mapeamentos REST Batch para API .NET

Os nomes de propriedade nas cadeias de caracteres de filtro, seleção e expansão devem refletir os seus equivalentes da API REST, no nome e no caso. As tabelas a seguir fornecem os mapeamentos entre os equivalentes API .NET e REST.

Mapeamentos para cadeias de caracteres de filtro

  • Métodos da lista .NET: cada um dos métodos da API .NET nesta coluna aceita um objeto ODATADetailLevel como parâmetro.
  • Solicitações da lista REST: cada página da API REST associada a essa coluna contém uma tabela especificando as propriedades e as operações permitidas nas cadeias de caracteres filter. Você pode usar esses nomes de propriedade e operações ao construir uma cadeia de caracteres ODATADetailLevel.FilterClause.
Métodos da lista .NET Solicitações da lista REST
CertificateOperations.ListCertificates Listar os certificados de uma conta
CloudTask.ListNodeFiles Listar os arquivos associados a uma tarefa
JobOperations.ListJobPreparationAndReleaseTaskStatus Listar o status das tarefas de preparação e liberação de trabalho para um determinado trabalho
JobOperations.ListJobs Listar os trabalhos em uma conta
JobOperations.ListNodeFiles Listar os arquivos em um nó
JobOperations.ListTasks Listar as tarefas associadas a um trabalho
JobScheduleOperations.ListJobSchedules Listar os cronogramas de trabalho em uma conta
JobScheduleOperations.ListJobs Listar os trabalhos associados a uma agenda de trabalho
PoolOperations.ListComputeNodes Listar os nós de computação em um pool
PoolOperations.ListPools Listar os pools em uma conta

Mapeamentos para cadeias de caracteres de seleção

  • Tipos .NET do Lote: Tipos de API .NET do Lote.
  • Entidades da API REST: cada página nesta coluna contém uma ou mais tabelas que listam os nomes de propriedade da API REST para o tipo. Esses nomes de propriedade são usados ao construir as cadeias de caracteres select . Você usa esses mesmos nomes de propriedade ao construir uma cadeia de caracteres ODATADetailLevel.SelectClause.
Tipos de Lote .NET Entidades da API REST
Certificado Obter informações sobre um certificado
CloudJob Obter informações sobre um trabalho
CloudJobSchedule Obter informações sobre uma agenda de trabalho
ComputeNode Obter informações sobre um nó
CloudPool Obter informações sobre um pool
CloudTask Obter informações sobre uma tarefa

Exemplo: construir uma cadeia de caracteres filter

Para construir uma cadeia de caracteres de filtro para ODATADetailLevel.FilterClause, localize a página da API REST correspondente. As propriedades selecionáveis e seus operadores com suporte estão na primeira tabela de várias linhas. Por exemplo, se quiser recuperar todas as tarefas cujo código de saída era diferente de zero, por exemplo, essa linha em Listar as tarefas associadas a um trabalho especificará a cadeia de caracteres da propriedade aplicável e os operadores permitidos:

Propriedade Operações permitidas Type
executionInfo/exitCode eq, ge, gt, le , lt Int

A cadeia de caracteres de filtro relacionada é:

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

Exemplo: construir uma cadeia de caracteres select

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 com suporte estão na primeira tabela de várias linhas. Por exemplo, para recuperar apenas a ID e a linha de comando para cada tarefa em uma lista, verifique Obter informações sobre uma tarefa:

Propriedade Type Observações
id String The ID of the task.
commandLine String The command line of the task.

A cadeia de caracteres Select relacionada é:

id, commandLine

Exemplos de código

Consultas de lista eficientes

O projeto de exemplo EfficientListQueries mostra como uma consulta de lista eficaz pode afetar o desempenho de um aplicativo. Esse aplicativo de console em 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 valores de propriedade diferentes para variar a quantidade de dados a serem retornados. Este exemplo produz uma saída 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...

Como mostrado nos exemplos, você pode diminuir muito os tempos de resposta da consulta limitando as propriedades e o número de itens retornados. Você pode encontrar esse e outros exemplos de projetos no repositório azure-batch-samples no GitHub.

Biblioteca BatchMetrics

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

Este exemplo inclui um projeto de biblioteca de classes do .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 no projeto demonstra as seguintes operações:

  • Selecionando atributos específicos para baixar somente as propriedades necessárias
  • Filtrando os tempos de transição do estado para baixar somente 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 propriedades id e state devem ser obtidas para as entidades consultadas. Também especifica que apenas as entidades cujo estado foi alterado desde o parâmetro DateTime especificado 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óximas etapas