Сохранение данных заданий и задач в службе хранилища Azure с помощью библиотеки соглашений о пакетных файлах для .NET

Статья
06/01/2023

Задача, выполняемая пакетной службой Azure, может генерировать выходные данные при запуске. Выходные данные задачи часто требуется хранить, чтобы их могли получать другие задачи в задании и (или) клиентское приложение, которое выполняет это задание. Задачи записывают выходные данные в файловую систему вычислительного узла пакетной службы. При этом все данные на узле удаляются при пересоздании образа или исключении узла из пула. Задачи могут также иметь срок хранения файла, по истечении которого созданные задачей файлы удаляются. Поэтому важно хранить выходные данные задачи, которые понадобятся вам позднее для использования с хранилищем данных, например службой хранилища Azure.

Параметры учетной записи хранения в пакетной службе см. в статье Учетные записи пакетной службы и учетные записи хранения Azure.

Данные задач можно сохранять из пакетной службы Azure с помощью библиотеки соглашений об именовании файлов .NET. Библиотека соглашений об именовании файлов упрощает процесс сохранения и извлечения выходных данных задачи в службе хранилища Azure. Вы можете использовать библиотеку соглашений об именовании файлов как в задаче, так и в клиентском коде. В режиме задачи используйте библиотеку для сохранения файлов. В режиме клиента используйте библиотеку для вывода списка и извлечения файлов. Код задачи также может получать выходные данные вышестоящих задач с использованием библиотеки, как, например, в сценарии зависимостей задач.

Чтобы получить выходные файлы с помощью библиотеки соглашений об именовании файлов, найдите файлы для задания или задачи. Имена файлов или их расположение знать не нужно. Вместо этого можно перечислить файлы по идентификатору и назначению. Например, выведите список всех промежуточных файлов для данной задачи. или получите файл предварительной версии для конкретного задания.

Начиная с версии 2017-05-01, API пакетной службы поддерживает сохранение выходных данных в службе хранилища Azure для обычных задач и задач диспетчера заданий, которые выполняются в пулах, созданных с конфигурацией виртуальной машины (ВМ). Выходные данные можно сохранить в коде, создающем задачу. Этот метод является альтернативой библиотеке соглашений об именовании файлов. Клиентские приложения пакетной службы можно изменить для сохранения выходных данных без необходимости обновления приложения, в котором выполняется ваша задача. Дополнительные сведения можно найти в разделе Сохранение данных задачи в службе хранилища Azure с помощью API пакетной службы.

Библиотека — варианты использования

Пакетная служба Azure предоставляет несколько способов сохранения выходных данных задач. Используйте библиотеку соглашений об именовании файлов, если вы хотите:

Изменить код для приложения, в котором выполняется ваша задача, для сохранения файлов.
Обеспечить потоковую передачу данных в службу хранилища Azure, пока выполняется задача.
Сохранить данные из пулов.
Найти и скачать выходные файлы задачи по идентификатору или назначению в клиентском приложении или других задачах.
Просмотр выходных данных задачи на портале Azure.

Для других сценариев вам вероятно следует рассмотреть другой подход. Дополнительные сведения о других способах приведены в статьеСохранение выходных данных заданий и задач в службе хранилища Azure.

Что из себя представляет стандарт соглашений о пакетных файлах?

Стандарт соглашений о пакетных файлах предоставляет схему именования путей к целевым контейнерам и большим двоичным объектам, в которые записываются выходные файлы. Файлы, сохраненные в хранилище Azure и соответствующие стандарту, автоматически отображаются на портале Azure.

Библиотека соглашений об именовании файлов .NET автоматически именует ваши контейнеры хранилища и выходные файлы задач в соответствии со стандартом. Библиотека также предоставляет методы для запроса выходных файлов в службе хранилища Azure. Запросы можно выполнять по идентификатору задания, идентификатору задачи или назначению.

При работе на языке, отличном от .NET, можно самостоятельно реализовать в приложении стандарт соглашений об именовании файлов. Дополнительные сведения см. в разделе Реализация стандарта соглашений по пакетным файлам.

Установление связи с учетной записью хранения Azure

Для сохранения выходных данных в службе хранилища Azure с помощью библиотеки соглашений об именовании файлов необходимо связать учетную запись хранения Azure с учетной записью пакетной службы.

Войдите на портал Azure.
Найдите и выберите Пакетную службу в строке поиска.
Выберите учетную запись пакетной службы, которую вы хотите связать со службой хранилища Azure.
На странице учетной записи пакетной службы в разделе Параметры выберите опцию Учетная запись хранения.
Если у вас еще нет учетной записи хранения Azure, связанной с учетной записью пакетной службы, выберите Учетная запись хранения (None).
Выберите учетную запись службы хранилища Azure, которую вы будете использовать. Для обеспечения высокой производительности используйте учетную запись в одном регионе с учетной записью пакетной службы.

Сохранение выходных данных

Выходные данные заданий и задач можно сохранять с помощью библиотеки соглашений об именовании файлов. Сначала создайте контейнер в службе хранилища Azure. Затем сохраните выходные данные в контейнере. Для отправки выходных данных задачи в контейнер используйте клиентскую библиотеку службы хранилища Azure для .NET в коде задачи.

Дополнительные сведения о работе с контейнерами и большими двоичными объектами в службе хранилища Azure см. в разделе Приступая к работе со службой хранилища больших двоичных объектов Azure с помощью .NET.

Все выходные данные заданий и задач, сохраненные с помощью библиотеки соглашений об именовании файлов, хранятся в одном и том же контейнере. Если большое число задач попытаются одновременно сохранить файлы, могут быть применены ограничения для регулирования количества запросов к службе хранилища Azure. Дополнительные сведения приведены в статье Производительность и контрольный список масштабируемости службы хранилища BLOB-объектов.

Создание контейнера хранилища

Для сохранения выходных данных задачи в службе хранилища Azure сначала создайте контейнер путем вызова CloudJob.PrepareOutputStorageAsync. Этот метод расширения принимает объект CloudStorageAccount в качестве параметра. Этот метод создает контейнер с именем в соответствии со стандартом соглашений об именовании файлов. Содержимое контейнера можно обнаружить с помощью портала Azure и методов извлечения, описанных в этой статье.

Обычно контейнер создается в клиентском приложении, которое создает пулы, задания и задачи. Пример:

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

Хранение выходных данных задач

После создания контейнера хранилища задачи могут сохранять выходные данные в контейнере с помощью TaskOutputStorage. Этот класс доступен в библиотеке соглашений об именовании файлов.

В коде задачи создайте объект TaskOutputStorage. Когда задача завершит свою работу, вызовите метод TaskOutputStorage.SaveAsync. Этот шаг позволит сохранить выходные данные в службе хранилища 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");

Параметр kind метода TaskOutputStorage. SaveAsync классифицирует сохраненные файлы. Существует четыре стандартных типа TaskOutputKind: TaskOutput, TaskPreview, TaskLog и TaskIntermediate.. Также можно определить пользовательские категории выходных данных.

Укажите тип выходных данных для перечисления при запросе пакетной службы позже. Затем при выводе списка выходных данных их можно отфильтровать по одному из типов выходных данных. Например, отфильтруйте следующим образом: "Предоставить выходные данные предварительной версии для задачи 109". Дополнительные сведения приведены в разделе Извлечение выходных данных.

Тип выходных данных также определяет, где отображается выходной файл на портале Azure. Файлы в категории TaskOutput находятся в выходных файлах задачи. Файлы в категории TaskLog находятся в журналах задачи.

Хранения выходных данных заданий

Вы также можете хранить выходные данные, связанные со всем заданием. Например, для задачи слияния в задании отрисовки фильма можно сохранить полностью отрисованный фильм в качестве выходных данных задания. Когда задание будет завершено, клиентское приложение может вывести список и извлечь выходные данные для этого задания. Клиентскому приложению не нужно запрашивать отдельные задачи.

Для сохранения выходных данных задания используйте вызов метода JobOutputStorage.SaveAsync. Укажите JobOutputKind и имя файла. Пример:

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");

Как и с типом TaskOutputKind для выходных данных задачи, используйте тип JobOutputKind, чтобы классифицировать сохраняемые файлы задания. Позже вы можете получить список определенных типов выходных данных. Тип JobOutputKind включает в себя категории выходных данных и предварительной версии. Этот тип также поддерживает создание пользовательских категорий.

Хранение журналов задач

Также может потребоваться сохранить файлы, которые обновляются во время выполнения задачи. Например, может потребоваться сохранить файлы журнала или stdout.txt и stderr.txt. Для сохранения этих типов файлов библиотека соглашений об именовании файлов предоставляет метод TaskOutputStorage.SaveTrackedAsync. Отслеживайте обновления файла на узле через заданный интервал с помощью SaveTrackedAsync. Затем сохраните эти обновления в службе хранилища Azure.

В приведенном ниже примере используется SaveTrackedAsync для обновления stdout.txt в службе хранилища Azure во время выполнения задачи через каждые 15 секунд:

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);
}

Замените раздел Code to process data and produce output file(s) с комментарием любым кодом, который обычно выполняет ваша задача. Например, вам может понадобиться код, который скачивает данные из службы хранилища Azure, а затем выполняет с ними операцию преобразования или вычисления. Этот код можно поместить в блок using, чтобы периодически обновлять файл с помощью SaveTrackedAsync.

Агент узла — это программа, которая запускается на каждом узле в пуле. Эта программа предоставляет интерфейс управления и контроля между узлом и пакетной службой. Вызов Task.Delay требуется в конце этого блока using. Вызов гарантирует, что у агента узла есть время для сброса содержимого стандарта в файл stdout.txt на узле. Без этой задержки вывод данных завершится на несколько секунд быстрее и, как результат, будет неполным. Эта задержка может потребоваться не для всех файлов.

При включении отслеживания файла с помощью метода SaveTrackedAsync в службе хранилища Azure будут сохраняться только данные, добавляемые в отслеживаемый файл. Данный метод следует использовать только для отслеживания не участвующих в ротации файлов журнала или других файлов, в конец которых с помощью операций добавления записываются данные.

Извлечение выходных данных

Для извлечения выходных файлов по определенной задаче или заданию вам не нужно знать путь в службу хранилища Azure или имена файлов. Вместо этого выходные файлы можно запрашивать по идентификатору задачи или задания.

В следующем примере кода итерация выполняется по задачам задания. Затем код выводит некоторые сведения о выходных файлах для соответствующей задачи. После этого код скачивает файлы из 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();
    }
}

Просмотр выходных файлов на портале Azure

Если выходные файлы задачи используют стандарт соглашений о пакетных файлах, можно просмотреть файлы на портале Azure.

Чтобы выходные файлы отображались на портале, необходимо выполнить следующие требования:

Для автоматического отображения выходных файлов на портале Azure необходимо следать следующее:

Свяжите учетную запись хранения Azure со своей учетной записью пакетной службы.
Соблюдайте предварительно определенные соглашения об именовании контейнеров и файлов службы хранилища Azure. Просмотрите файл README для всех определений. Если для сохранения выходных данных используется библиотека соглашений об именовании файлов, файлы сохраняются в соответствии со стандартом соглашений об именовании файлов.

Чтобы просмотреть выходные файлы и журналы задач на портале Azure, выполните следующие действия:

Войдите на портал Azure.
Перейдите к задаче, для которой требуется просмотреть выходные данные.
Выберите Сохраненные выходные файлы или Сохраненные журналы.

Пример кода

Пример проекта PersistOutputs — это один из примеров кода пакетной службы Azure на портале GitHub. Это решение Visual Studio демонстрирует использование библиотеки соглашений об именовании файлов пакетной службы Azure для сохранения выходных данных задачи в долговременном хранилище. Чтобы запустить пример приложения, выполните следующее.

Откройте проект в Visual Studio 2019.
Добавьте свои данные учетной записи пакетной службы и службы хранилища Azure в AccountSettings.settings в проекте Microsoft.Azure.Batch.Samples.Common.
Постройте решение. Пока не запускайте решение.
Восстановите необходимые пакеты NuGet в случае появления соответствующего запроса.
Передайте пакет приложения для PersistOutputsTask через портал Azure.
1. Включите исполняемый файл PersistOutputsTask.exe и его зависимые сборки в пакет .zip.
2. Задайте для идентификатора приложения значение PersistOutputsTask.
3. Задайте для версии пакета приложения значение 1.0.
Нажмите Пуск, чтобы запустить проект.
При появлении запроса на выбор используемой технологии сохранения введите 1. Этот параметр запускает пример с помощью библиотеки соглашений об именовании файлов для сохранения выходных данных задачи.

Получение библиотеки соглашений об именовании пакетных файлов для .NET

Библиотека соглашений об именовании пакетных файлов для .NET доступна в NuGet. Библиотека расширяет классы CloudJob и CloudTask новыми методами. Дополнительные сведения приведены в справочной документации по библиотеке соглашений об именовании файлов.

Исходный код библиотеки соглашений об именовании файлов доступен на GitHub.

Поделиться через