Partilhar via

Persista dados de trabalho e de tarefas no Azure Storage utilizando a biblioteca Batch File Conventions para .NET.

Uma tarefa em execução no Lote do Azure pode produzir dados de saída quando é executada. Os dados de saída da tarefa geralmente precisam ser armazenados para recuperação por outras tarefas no trabalho, no aplicativo cliente que executou o trabalho ou em ambos. As tarefas gravam dados de saída no sistema de arquivos de um nó de computação em lote, mas todos os dados no nó são perdidos quando ele é reconfigurado ou quando o nó sai do pool. As tarefas também podem ter um período de retenção de arquivos, após o qual os arquivos criados pela tarefa são excluídos. Por esses motivos, é importante manter a saída das tarefas de que necessitarás mais tarde num armazenamento de dados, como o Armazenamento do Azure.

Para obter opções de conta de armazenamento em lote, consulte Contas em lote e Contas de armazenamento do Azure.

Pode persistir dados de tarefas do Azure Batch utilizando a biblioteca de Convenções de Arquivo para .NET. A biblioteca de Convenções de Arquivo simplifica o processo de armazenar e recuperar dados resultantes de tarefas no Armazenamento do Azure. Você pode usar a biblioteca de File Conventions no código tanto da tarefa quanto do cliente. No modo de tarefa, use a biblioteca para persistir arquivos. No modo cliente, use a biblioteca para listar e recuperar arquivos. Seu código de tarefa também pode recuperar a saída de tarefas upstream usando a biblioteca, como em um cenário de dependências de tarefas .

Para recuperar ficheiros de saída com a biblioteca Convenções de Ficheiros, localize os ficheiros associados a um trabalho ou tarefa. Você não precisa saber os nomes ou locais dos arquivos. Em vez disso, você pode listar os arquivos por ID e finalidade. Por exemplo, liste todos os arquivos intermediários para uma determinada tarefa. Ou obtenha um arquivo de visualização para um determinado trabalho.

A partir da versão 2017-05-01, a API do serviço em lote suporta a persistência de dados de saída no Armazenamento do Azure para tarefas e tarefas do gestor de tarefas que são executadas em pools criados com a configuração de máquina virtual (VM). Você pode armazenar a saída a partir do código que cria uma tarefa. Este método é uma alternativa para a biblioteca File Conventions. Pode modificar as suas aplicações cliente de processamento em lote para manter a saída sem precisar atualizar a aplicação na qual a sua tarefa está a correr. Para obter mais informações, consulte persistir dados de tarefas no Armazenamento do Azure com a API do Batch service.

Casos de uso de bibliotecas

Azure Batch fornece várias maneiras de persistir a saída de tarefas. Use a biblioteca de Convenções de Arquivo quando quiser:

  • Modifique o código do aplicativo que sua tarefa está executando para persistir arquivos.
  • Transmita dados para o Armazenamento do Azure enquanto a tarefa ainda está em execução.
  • Grave os dados dos pools.
  • Localize e baixe arquivos de saída de tarefas por ID ou finalidade em seu aplicativo cliente ou outras tarefas.
  • Exiba a saída da tarefa no portal do Azure.

Para outros cenários, convém considerar uma abordagem diferente. Para obter mais informações sobre outras opções, consulte Persistir saída de trabalho e tarefa para o Armazenamento do Azure.

O que é o padrão Batch File Conventions?

O padrão Batch File Conventions fornece um esquema de nomenclatura para os contêineres de destino e caminhos de blob nos quais seus arquivos de saída são gravados. Os arquivos persistentes no armazenamento do Azure que seguem o padrão são automaticamente visíveis no portal do Azure.

A biblioteca de Convenções de Arquivos para .NET nomeia automaticamente seus contêineres de armazenamento e arquivos de saída de tarefas de acordo com o padrão. A biblioteca também fornece métodos para consultar arquivos de saída no Armazenamento do Azure. Você pode consultar por ID de trabalho, ID de tarefa ou finalidade.

Se você estiver desenvolvendo com uma linguagem diferente do .NET, você mesmo poderá implementar o padrão Convenções de Arquivo em seu aplicativo. Para obter mais informações, consulte Implementar o padrão Batch File Conventions.

Para persistir os dados de saída no Armazenamento do Azure usando a biblioteca de Convenções de Arquivo, primeiro vincule uma conta de Armazenamento do Azure à sua conta Batch.

  1. Inicie sessão no portal Azure.
  2. Procure e selecione Lote na barra de pesquisa.
  3. Selecione a conta de lote a ser vinculada ao Armazenamento do Azure.
  4. Na página Conta de lote, em Configurações, selecione Conta de armazenamento.
  5. Se você ainda não tiver uma conta de Armazenamento do Azure associada à sua conta de lote, selecione Conta de Armazenamento (Nenhuma).
  6. Selecione a conta de Armazenamento do Azure a ser usada. Para obter o melhor desempenho, use uma conta na mesma região que a conta Batch.

Guardar dados de saída

Pode guardar dados de saída de trabalhos e tarefas com a biblioteca de Convenções de Arquivo. Primeiro, crie um contêiner no Armazenamento do Azure. Em seguida, salve a saída no contêiner. Utilize a biblioteca cliente do Armazenamento do Azure para .NET no seu código de tarefa para carregar a saída da tarefa no contentor.

Para obter mais informações sobre como trabalhar com contêineres e blobs no Armazenamento do Azure, consulte Introdução ao armazenamento de Blobs do Azure usando .NET.

Todas as saídas de trabalho e tarefa persistidas com a biblioteca de Convenções de Arquivo são armazenadas no mesmo contêiner. Se um grande número de tarefas tentar persistir arquivos ao mesmo tempo, os limites de limitação do Armazenamento do Azure poderão ser impostos. Para obter mais informações, consulte Lista de verificação de desempenho e escalabilidade para armazenamento de Blob.

Criar contêiner de armazenamento

Para persistir a saída da tarefa no Armazenamento do Azure, primeiro crie um contêiner chamando CloudJob. PrepareOutputStorageAsync. Esse método de extensão usa um objeto CloudStorageAccount como parâmetro. O método cria um contêiner nomeado de acordo com o padrão File Conventions. O conteúdo do contêiner pode ser descoberto pelo portal do Azure e pelos métodos de recuperação descritos neste artigo.

Normalmente, crie um contêiner em seu aplicativo cliente, que cria seus pools, trabalhos e tarefas. Por exemplo:

CloudJob job = batchClient.JobOperations.CreateJob(
    "myJob",
    new PoolInformation { PoolId = "myPool" });

// Create reference to the linked Azure Storage account
CloudStorageAccount linkedStorageAccount =
    new CloudStorageAccount(myCredentials, true);

// Create the blob storage container for the outputs
await job.PrepareOutputStorageAsync(linkedStorageAccount);

Armazenar resultados de tarefas

Depois de criar seu contêiner de armazenamento, as tarefas podem salvar a saída no contêiner usando TaskOutputStorage. Esta classe está disponível na biblioteca File Conventions.

No código da tarefa, crie um objeto TaskOutputStorage . Quando a tarefa concluir o seu trabalho, chame o método TaskOutputStorage.SaveAsync. Esta etapa grava a saída no Armazenamento do Azure.

CloudStorageAccount linkedStorageAccount = new CloudStorageAccount(myCredentials);
string jobId = Environment.GetEnvironmentVariable("AZ_BATCH_JOB_ID");
string taskId = Environment.GetEnvironmentVariable("AZ_BATCH_TASK_ID");

TaskOutputStorage taskOutputStorage = new TaskOutputStorage(
    linkedStorageAccount, jobId, taskId);

/* Code to process data and produce output file(s) */

await taskOutputStorage.SaveAsync(TaskOutputKind.TaskOutput, "frame_full_res.jpg");
await taskOutputStorage.SaveAsync(TaskOutputKind.TaskPreview, "frame_low_res.jpg");

O kind parâmetro do TaskOutputStorage.O método SaveAsync categoriza os arquivos persistentes. Há quatro tipos TaskOutputKind predefinidos: TaskOutput, TaskPreview, TaskLoge TaskIntermediate. Você também pode definir categorias personalizadas de saída.

Especifique que tipo de saídas listar mais tarde quando consultar o Batch. Em seguida, ao listar as saídas de uma tarefa, você pode filtrar um dos tipos de saída. Por exemplo, filtre para "Dê-me a saída de visualização para a tarefa 109". Para obter mais informações, consulte Recuperar dados de saída.

O tipo de saída também determina onde um arquivo de saída aparece no portal do Azure. Os arquivos na categoria TaskOutput estão em Arquivos de saída de tarefa. Os arquivos na categoria TaskLog estão em Logs de tarefas.

Armazenar saídas de trabalho

Você também pode armazenar as saídas associadas a um trabalho inteiro. Por exemplo, na tarefa de fusão de um trabalho de renderização de filme, pode-se persistir o filme totalmente renderizado como um resultado do trabalho. Quando o trabalho for concluído, o aplicativo cliente poderá listar e recuperar as saídas para o trabalho. Seu aplicativo cliente não precisa consultar as tarefas individuais.

Armazene a saída do trabalho chamando o JobOutputStorage. SaveAsync método. Especifique o JobOutputKind e o nome do arquivo. Por exemplo:

CloudJob job = new JobOutputStorage(acct, jobId);
JobOutputStorage jobOutputStorage = job.OutputStorage(linkedStorageAccount);

await jobOutputStorage.SaveAsync(JobOutputKind.JobOutput, "mymovie.mp4");
await jobOutputStorage.SaveAsync(JobOutputKind.JobPreview, "mymovie_preview.mp4");

Assim como acontece com o tipo TaskOutputKind para saídas de tarefas, use o tipo JobOutputKind para categorizar os arquivos persistentes de um trabalho. Mais tarde, você pode listar um tipo específico de saída. O tipo JobOutputKind inclui tanto categorias de saída quanto de visualização. O tipo também suporta a criação de categorias personalizadas.

Armazenar logs de tarefas

Também pode ser necessário persistir os arquivos que são atualizados durante a execução de uma tarefa. Por exemplo, talvez seja necessário persistir os arquivos de log ou stdout.txt e stderr.txt. A biblioteca File Conventions fornece o TaskOutputStorage. SaveTrackedAsync método para persistir esses tipos de arquivos. Rastreie atualizações de um arquivo no nó em um intervalo de tempo especificado com SaveTrackedAsync. Em seguida, persista essas atualizações no Armazenamento do Azure.

O exemplo a seguir usa SaveTrackedAsync para atualizar stdout.txt no Armazenamento do Azure a cada 15 segundos durante a execução da tarefa:

TimeSpan stdoutFlushDelay = TimeSpan.FromSeconds(3);
string logFilePath = Path.Combine(
    Environment.GetEnvironmentVariable("AZ_BATCH_TASK_DIR"), "stdout.txt");

// The primary task logic is wrapped in a using statement that sends updates to
// the stdout.txt blob in Storage every 15 seconds while the task code runs.
using (ITrackedSaveOperation stdout =
        await taskStorage.SaveTrackedAsync(
        TaskOutputKind.TaskLog,
        logFilePath,
        "stdout.txt",
        TimeSpan.FromSeconds(15)))
{
    /* Code to process data and produce output file(s) */

    // We are tracking the disk file to save our standard output, but the
    // node agent may take up to 3 seconds to flush the stdout stream to
    // disk. So give the file a moment to catch up.
     await Task.Delay(stdoutFlushDelay);
}

Substitua a seção Code to process data and produce output file(s) comentada por qualquer código que sua tarefa normalmente faz. Por exemplo, você pode ter um código que baixa dados do Armazenamento do Azure e, em seguida, executa transformações ou cálculos. Você pode encapsular esse código em um using bloco para atualizar periodicamente um arquivo com SaveTrackedAsync.

O agente de nó é um programa que é executado em cada nó do pool. Este programa fornece a interface de comando e controle entre o nó e o serviço Batch. No final deste bloco using, a chamada Task.Delay é necessária. A chamada garante que o agente do nó tenha tempo para liberar o conteúdo do padrão para o stdout.txt arquivo no nó. Sem esse atraso, é possível perder os últimos segundos da saída de dados. Talvez você não precise desse atraso para todos os arquivos.

Quando você habilita o controle de arquivos com SaveTrackedAsync, apenas os acréscimos ao arquivo rastreado são persistidos no Armazenamento do Azure. Use esse método apenas para rastrear arquivos de log não rotativos ou outros arquivos gravados com operações de acréscimo ao final do arquivo.

Recuperar dados de saída

Para recuperar arquivos de saída para uma tarefa ou trabalho específico, você não precisa saber o caminho no Armazenamento do Azure ou nomes de arquivo. Em vez disso, você pode solicitar arquivos de saída por tarefa ou ID de trabalho.

O código de exemplo a seguir itera através das tarefas de um trabalho. Em seguida, o código imprime algumas informações sobre os arquivos de saída para a tarefa. Em seguida, o código baixa os arquivos do AzureStorage.

foreach (CloudTask task in myJob.ListTasks())
{
    foreach (OutputFileReference output in
        task.OutputStorage(storageAccount).ListOutputs(
            TaskOutputKind.TaskOutput))
    {
        Console.WriteLine($"output file: {output.FilePath}");

        output.DownloadToFileAsync(
            $"{jobId}-{output.FilePath}",
            System.IO.FileMode.Create).Wait();
    }
}

Exibir arquivos de saída no portal do Azure

Se os arquivos de saída da tarefa usarem o padrão Convenções de Arquivo em Lote, você poderá exibir os arquivos no portal do Azure.

Para habilitar a exibição de seus arquivos de saída no portal, você deve satisfazer os seguintes requisitos:

Para que os arquivos de saída sejam exibidos automaticamente no portal do Azure, você deve:

  1. Vincule uma conta de Armazenamento do Azure à sua conta do Batch.
  2. Siga as convenções de nomenclatura predefinidas para contêineres e arquivos do Armazenamento do Azure. Consulte o LEIA-ME para verificar todas as definições. Se você usar a biblioteca de Convenções de Arquivo para manter sua saída, seus arquivos serão mantidos de acordo com o padrão Convenções de Arquivo.

Para exibir arquivos e logs de saída de tarefas no portal do Azure:

  1. Inicie sessão no portal Azure.
  2. Vá para a tarefa para a qual você deseja exibir a saída.
  3. Selecione Arquivos de saída salvos ou Logs salvos.

Exemplo de código

O projeto de exemplo PersistOutputs é um dos exemplos de Azure Batch no GitHub. Esta solução do Visual Studio mostra como usar a biblioteca Azure Batch File Conventions para guardar a saída das tarefas em armazenamento durável. Para executar o exemplo, siga estes passos:

  1. Abra o projeto no Visual Studio 2019.
  2. Adicione as suas credenciais de conta do Azure Batch e Armazenamento ao AccountSettings.settings no projeto Microsoft.Azure.Batch.Samples.Common.
  3. Crie a solução. Não execute a solução ainda.
  4. Se solicitado, restaure todos os pacotes NuGet.
  5. Carregue um pacote de aplicativo para PersistOutputsTask por meio do portal do Azure.
    1. Inclua o PersistOutputsTask.exe executável e seus assemblies dependentes no pacote .zip.
    2. Defina o ID do aplicativo como PersistOutputsTask.
    3. Defina a versão do pacote do aplicativo como 1.0.
  6. Selecione Iniciar para executar o projeto.
  7. Quando solicitado a selecionar a tecnologia de persistência a ser usada, digite 1. Esta opção executa o exemplo usando a biblioteca File Conventions para persistir a saída da tarefa.

Obtenha a biblioteca de convenções de arquivo em lote para .NET

A biblioteca Batch File Conventions para .NET está disponível no NuGet. A biblioteca estende as classes CloudJob e CloudTask com novos métodos. Para obter mais informações, consulte a documentação de referência da biblioteca File Conventions.

O código-fonte da biblioteca File Conventions está disponível no GitHub.

Próximos passos

  • Last updated on