Persistir dados de tarefa e trabalho no Armazenamento do Microsoft Azure com a biblioteca de Convenções de Arquivo em Lotes para .NET

  • Artigo

Uma tarefa em execução em lote do Azure pode produzir dados de saída quando ele é executado. Com frequência, os dados de saída precisam ser armazenados para a recuperação por outras tarefas no trabalho, o aplicativo cliente que executou o trabalho, ou ambos. As tarefas gravam dados de saída no sistema de arquivos de um nó de computação do Lote, mas todos os dados no nó serão perdidos quando ele for reimaginado ou quando o nó deixar o pool. As tarefas também podem ter um período de retenção de arquivo, após o qual os arquivos criados pela tarefa são excluídos. Por esses motivos, é importante manter a saída da tarefa que você vai precisar posteriormente para um repositório de dados, como o Armazenamento do Azure.

Para opções de conta de armazenamento do Lote, confira Contas do Lote e contas do Armazenamento do Azure.

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

Para recuperar arquivos de saída com a biblioteca convenções de arquivo, localize os arquivos de um trabalho ou tarefa. Você não precisa saber os nomes nem os 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 obter um arquivo de visualização para um determinado trabalho.

Começando com a versão de 01/05/2017, a API de serviço de Lote dá suporte a manter dados de saída para o Armazenamento do Azure para tarefas e tarefas do gerenciador de trabalho que são executadas em pools criados com a configuração de máquina virtual. Você pode persistir a saída de dentro do código que cria uma tarefa. Esse método é uma alternativa à biblioteca convenções de arquivo. Você pode modificar seus aplicativos cliente em Lotes para manter a saída sem necessidade de atualizar o aplicativo que sua tarefa está executando. Para obter mais informações, consulte Manter dados de tarefa no Armazenamento do Azure com a API de serviço em Lote.

Casos de uso da biblioteca

Lote do Azure fornece várias maneiras de persistir a saída da tarefa. Use a biblioteca convenções de arquivo quando quiser:

  • Modificar o código do aplicativo que sua tarefa está executando para persistir arquivos.
  • Transmitir dados para o Armazenamento do Azure enquanto a tarefa ainda está em execução.
  • Persistir dados de pools.
  • Localizar e baixar arquivos de saída de tarefas por ID ou por finalidade para o aplicativo cliente ou outras tarefas.
  • Você desejar exibir a saída da tarefa no portal do Azure.

Para outros cenários, talvez você queira considerar uma abordagem diferente. Para obter mais informações sobre outras opções, confira Manter trabalho e saída de tarefa no Armazenamento do Azure.

O que é o padrão Convenções do Arquivo em Lote?

O padrão Convenções de Arquivo em Lote fornece um esquema de nomenclatura para os contêineres de destino e os caminhos de blob nos quais os arquivos de saída são gravados. Arquivos persistentes no armazenamento do Azure que seguem o padrão são automaticamente exibíveis no portal do Azure.

A biblioteca Convenções de Arquivo para .NET nomeia automaticamente seus contêineres de armazenamento e os arquivos de saída de tarefa 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 da tarefa ou finalidade.

Se você estiver desenvolvendo com uma linguagem que não .NET, poderá implementar o padrão de Convenções de Arquivo você mesmo em seu aplicativo. Para obter mais informações, consulte Implementar o padrão de convenções de arquivo de lote.

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

  1. Entre no portal do Azure.
  2. Na barra de pesquisa, pesquise e selecione Lote.
  3. Selecione a conta do Lote para vincular com o Azure Armazenamento.
  4. Na página conta do Lote, em Configurações, selecione Conta de armazenamento.
  5. Se você ainda não tiver uma conta de armazenamento do Azure associada à sua conta do Lote, clique em conta de armazenamento (nenhuma).
  6. Selecione a conta de Armazenamento do Azure a ser usada. Para melhor desempenho, use uma conta na mesma região que a conta do Lote.

Manter os dados de saída

Você pode persistir dados de saída de tarefa e trabalho com a biblioteca convenções de arquivo. primeiramente, crie um contêiner no Armazenamento do Azure Em seguida, salve a saída no contêiner. Use a biblioteca de cliente do Armazenamento do Azure para .NET em seu código de tarefa para carregar a saída da tarefa para o contêiner.

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 o .NET.

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

Criar um contêiner de armazenamento

Para manter 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 chamado de acordo com o padrão convenções de arquivo. O conteúdo do contêiner é descoberto pelo portal do Azure e os 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 saídas de tarefas

Depois de criar o contêiner de armazenamento, as tarefas podem salvar a saída no contêiner usando TaskOutputStorage. Essa classe está disponível na biblioteca convenções de arquivo.

No código da tarefa, crie um objeto TaskOutputStorage. Quando a tarefa concluir o trabalho, chame o método TaskOutputStorageSaveAsync Esta etapa salva 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 parâmetro kind do método TaskOutputStorage.SaveAsync categoriza os arquivos mantidos. Há quatro tipos predefinidos de TaskOutputKind: TaskOutput, TaskPreview, TaskLog e TaskIntermediate.. Você também pode definir as categorias personalizadas da saída.

Especifique que tipo de saídas listar ao consultar o Lote mais tarde. Em outras palavras, ao listar as saídas de uma tarefa, você pode filtrar a lista em um dos tipos de saída. Por exemplo, filtre para "Mostre-me a saída de pré-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 o local no portal do Azure em que um arquivo de saída é exibido. Os arquivos na categoria TaskOutput estão em Arquivos de saída da tarefa. Os arquivos na categoria TaskLog estão em Logs de tarefas.

Armazenar saídas de trabalhos

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

Armazene a saída de trabalho chamando o método JobOutputStorageSaveAsync. 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 o tipo TaskOutputKind para saídas de tarefa, você usa o parâmetro JobOutputKind para categorizar os arquivos mantidos de um trabalho. Posteriormente, você pode listar um tipo específico de saída. O tipo JobOutputKind inclui as categorias de saída e pré-visualizações das categorias. O tipo também dá suporte à criação de categorias personalizadas.

Armazenar logs de tarefas

Talvez você também precise persistir arquivos que são atualizados durante a execução de uma tarefa. Por exemplo, talvez seja necessário persistir arquivos de log ou stdout.txt e stderr.txt. A biblioteca de Convenções de Arquivo em Lote do Azure fornece o método TaskOutputStorageSaveTrackedAsync. Acompanhe as atualizações em um arquivo no nó em um intervalo especificado com SaveTrackedAsync. Em seguida, mantenha essas atualizações no Armazenamento do Azure.

O exemplo a seguir usa o 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 faça. Por exemplo, você pode ter código que baixa dados do Armazenamento do Azure e executa uma transformação ou um cálculo neles. Você pode quebrar a linha desse código em um bloco usingpara atualizar periodicamente um arquivo com SaveTrackedAsync.

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

Quando você habilita o acompanhamento de arquivo com SaveTrackedAsync, apenas acréscimos ao arquivo rastreado acompanhado são mantidos no Armazenamento do Azure. Use esse método somente para acompanhar arquivos de log não rotativos ou outros arquivos que são 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 Azure Armazenamento ou nomes de arquivo. Em vez disso, você pode solicitar os arquivos de saída pela ID de tarefa ou trabalho.

O código de exemplo a seguir itera pelas 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 de Convenções de Arquivo do 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 atender aos seguintes requisitos:

Para arquivos de saída exibirem automaticamente no portal do Azure, você deve:

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

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

  1. Entre no portal do 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 código do Lote do Azure no GitHub. Essa solução do Visual Studio demonstra como usar a biblioteca de Convenções de Arquivo de Lote do Azure para persistir a saída da tarefa para o armazenamento durável. Para executar o exemplo, siga estas etapas:

  1. Abra o projeto no Visual Studio 2019.
  2. Adicione suas credenciais de conta do Lote e do Armazenamento do Azure a AccountSettings.settings no projeto Microsoft.Azure.Batch.Samples.Common.
  3. Compile a solução. Não execute a solução ainda.
  4. Restaure todos os pacotes NuGet, se solicitado.
  5. Use o portal do Azure para carregar um pacote de aplicativos para PersistOutputsTask.
    1. Inclua o PersistOutputsTask.exe executável e seus dependentes no .zip pacote.
    2. De definir a ID do aplicativo como PersistOutputsTask.
    3. De definir a versão do pacote de aplicativos como 1.0.
  6. Selecione Iniciar para executar o projeto.
  7. Quando solicitado a selecionar a tecnologia de persistência a ser usada, insira 1. Essa opção executa o exemplo usando a biblioteca Convenções de Arquivo para persistir a saída da tarefa.

Obter a biblioteca Convenções de Arquivo em Lote para .NET

A biblioteca Convenções de Arquivo em Lote para .NET está disponível em NuGet. A biblioteca amplia as classes CloudJob e CloudTask com novos métodos. Para obter mais informações, consulte a referência para a biblioteca Convenções de Arquivo para documentação de referência.

O código-fonte da biblioteca convenções de arquivo está disponível no GitHub.

Próximas etapas