Partilhar via

Armazenar de forma persistente dados de trabalhos e tarefas no Azure Storage com a biblioteca Batch File Conventions para .NET

Uma tarefa a correr no Azure Batch 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 escrevem dados de saída para o sistema de ficheiros de um nó de processamento em lote, mas todos os dados no nó são perdidos quando é reimaginado 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 estas razões, é importante guardar a saída da tarefa que irá precisar mais tarde num armazenamento de dados, como Azure Storage.

Para opções de contas de armazenamento em Batch, veja contas Batch e contas Azure Storage.

Pode persistir dados de tarefas de Azure Batch usando a biblioteca File Conventions para .NET. A biblioteca File Conventions simplifica o processo de armazenar e recuperar dados de saída de tarefas no Azure Storage. 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. O seu código de tarefa também pode recuperar a saída de tarefas ascendentes usando a biblioteca, como num cenário de dependências de tarefas.

Para recuperar ficheiros de saída com a biblioteca de Convenções de Ficheiros, localize os ficheiros de uma tarefa ou trabalho. 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 Batch suporta dados de saída persistentes para o Azure Storage para tarefas e tarefas do gestor de trabalhos que correm em pools criados com a configuração de máquina virtual (VM). Podes persistir a saída dentro 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 mais informações, consulte Persistir dados de tarefas no Azure Storage com a API de serviço Batch.

Casos de uso de bibliotecas

O Azure Batch fornece múltiplas formas de persistir a saída de tarefas. Use a biblioteca de Convenções de Ficheiros quando quiser:

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

Para outros cenários, convém considerar uma abordagem diferente. Para mais informações sobre outras opções, consulte Persistir a saída de trabalhos e tarefas para o Azure Storage.

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 ficheiros que foram persistidos no armazenamento do Azure e que seguem o padrão são automaticamente visíveis no portal do Azure.

A biblioteca de Convenções de Ficheiros para .NET nomeia automaticamente os seus contentores de armazenamento e ficheiros de saída de tarefas de acordo com o padrão. A biblioteca também fornece métodos para consultar ficheiros de saída no Azure Storage. Você pode consultar por ID de trabalho, ID de tarefa ou finalidade.

Se estiver a desenvolver com uma linguagem diferente de .NET, pode implementar o padrão de Convenções de Ficheiros na sua aplicação. Para obter mais informações, consulte Implementar o padrão Batch File Conventions.

Para persistir dados de saída no Azure Storage usando a biblioteca de Convenções de Ficheiros, primeiro ligue uma conta Azure Storage à sua conta Batch.

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

Dados de saída persistentes

Pode persistir dados de saída de trabalhos e tarefas com a biblioteca File Conventions. Primeiro, crie um contentor no Azure Storage. Depois, guarda a saída no contentor. Use a biblioteca cliente Azure Storage para .NET no seu código de tarefa para carregar o resultado da tarefa no contentor.

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

Todos os resultados dos trabalhos e das tarefas mantidos na biblioteca de Convenções de Arquivos são armazenados no mesmo contentor. Se um grande número de tarefas tentar armazenar ficheiros ao mesmo tempo, podem ser impostos limites de capacidade do Azure Storage. 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 para Azure Storage, crie primeiro um contentor 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 contentor pode ser descoberto pelo portal Azure e pelos métodos de recuperação descritos neste artigo.

Normalmente, cria um contêiner na sua aplicação cliente, que cria os 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 termina o seu trabalho, chama o TaskOutputStorage. Método SaveAsync . Esta etapa guarda a saída para o Azure Storage.

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.

Especifica que tipo de saídas listar quando consulta o Batch mais tarde. 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 aparece um ficheiro output no portal 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 resultados dos trabalhos

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 filmes, pode persistir o filme totalmente renderizado como resultado do trabalho. Quando o seu trabalho estiver concluído, a sua aplicação cliente pode listar e obter os resultados do 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 as categorias de saída como as de pré-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, pode ser necessário persistir ficheiros de log, ou stdout.txt e stderr.txt. A biblioteca File Conventions fornece o TaskOutputStorage. SaveTrackedAsync método para persistir esses tipos de arquivos. Monitorize as atualizações para um ficheiro no nó a um intervalo especificado com SaveTrackedAsync. Em seguida, persista essas atualizações no Azure Storage.

O exemplo seguinte utiliza SaveTrackedAsync para atualizar stdout.txt em Azure Storage 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, pode ter código que descarrega dados do Azure Storage e depois realiza 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 se executa em cada nó do pool. Este programa fornece a interface de comando e controlo entre o nó e o serviço Batch. A chamada Task.Delay é necessária no final deste bloco using. A chamada garante que o agente do nó tem tempo para libertar o conteúdo do standard para o stdout.txt ficheiro 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 ativas o rastreamento de ficheiros com SaveTrackedAsync, apenas acréscimos ao ficheiro rastreado são armazenados no Azure Storage. Use este método apenas para rastrear ficheiros de log não rotativos, ou outros ficheiros que sejam escritos com operações de anexação ao final do ficheiro.

Recuperar dados de saída

Para recuperar ficheiros de saída para uma tarefa ou tarefa específica, não precisas de saber o caminho no Azure Storage, nem os nomes dos ficheiros. Em vez disso, você pode solicitar arquivos de saída por tarefa ou ID de trabalho.

O seguinte exemplo de código 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();
    }
}

Ver ficheiros de saída no portal Azure

Se os seus ficheiros de saída de tarefas usarem o padrão Convenções de Ficheiros em Lote, pode visualizar os ficheiros no portal Azure.

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

Para que os ficheiros de saída sejam automaticamente exibidos no portal Azure, deve:

  1. Liga uma conta Azure Storage à tua conta Batch.
  2. Siga as convenções de nomenclatura pré-definidas para contentores e ficheiros do Azure Storage. Se usar a biblioteca Convenções de Ficheiros para persistir a sua saída, os seus ficheiros são persistidos de acordo com o padrão Convenções de Ficheiros.

Para visualizar ficheiros de saída de tarefas e registos no portal do Azure:

  1. Inicie sessão no portal Azure.
  2. Vá à tarefa para a qual quer ver o resultado.
  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 Azure Batch no GitHub. Esta solução do Visual Studio mostra como usar a biblioteca Azure Batch File Conventions para persistir a saída da tarefa para armazenamento durável. Para executar o exemplo, siga estes passos:

  1. Abrir o projeto em Visual Studio 2019.
  2. Adicione as credenciais da sua conta de Batch e Azure Storage a AccountSettings.settings no projeto Microsoft.Azure.Batch.Samples.Common.
  3. Crie a solução. Ainda não executes a solução.
  4. Se solicitado, restaure todos os pacotes NuGet.
  5. Carregue um pacote de aplicação para PersistOutputsTask através do portal do Azure.
    1. Inclua o PersistOutputsTask.exe executável e as suas 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 Batch File Conventions para .NET

A biblioteca Batch File Conventions para .NET está disponível em 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 Convenções de Ficheiros está disponível no GitHub.

Próximos passos

  • Last updated on