Microsoft.Azure.Batch.Conventions.Files 4.0.0

Azure Batch 文件约定

This is a library based on conventions for saving and retrieving Azure Batch task output files.

目的

When you run a task in Azure Batch, the files created by that task are on the compute node where the task ran. As long as the compute node remains up, and within the file retention time of the task, you can retrieve those files via the Batch API. However, if you need the files to remain available even if the compute node is taken down (for example, as part of a pool resize), or after the retention time has expired, you must persist these files to a durable store.

此库封装了一个用于在Azure Blob存储中持久化工作量和任务输出的约定。这允许客户端代码轻松找到给定工作或任务的输出，允许通过ID和用途列出或检索这些输出。例如，客户端可以使用库来请求“列出任务7的所有中间文件”或“获取“我的电影”作业的缩略图预览”，无需了解名称或位置。

使用JobOutputKind和TaskOutputKind类型对持久化文件进行分类为“输出”、“预览”等。对于作业输出文件，预定义的类型是“JobOutput”和“JobPreview”；对于任务输出文件，“TaskOutput”、“TaskPreview”、“TaskLog”和“TaskIntermediate”。您也可以根据您的流程定义自定义类型。

先决条件

该库使用与您的Batch账户链接的Azure存储账户。如果您没有链接的存储账户，您可以使用Azure门户配置一个。

用法

库旨在在任务代码和客户端代码中使用 - 在任务代码中用于持久化文件，在客户端代码中用于列出和检索它们。

在任务代码中持久化文件

要从任务代码中持久化文件，请使用带有作业输出容器URL的JobOutputStorage和TaskOutputStorage构造函数，并调用SaveAsync方法

var linkedStorageAccount = new CloudStorageAccount(/* credentials */);
var jobId = Environment.GetEnvironmentVariable("AZ_BATCH_JOB_ID");
var taskId = Environment.GetEnvironmentVariable("AZ_BATCH_TASK_ID");

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

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

请注意，作业的所有输出文件，包括任务输出，都存储在同一个容器中。这意味着如果大量任务同时在同一时间尝试持久化文件，可能会执行存储节流限制。

在客户端代码中列出和检索文件

要从客户端代码访问持久文件，您必须配置客户端以使用链接的存储账户的详细信息。然后使用带有CloudStorageAccount的JobOutputStorage和TaskOutputStorage构造函数或CloudJob和CloudTask上的扩展方法。

var job = await batchClient.JobOperations.GetJobAsync(jobId);
var jobOutputStorage = job.OutputStorage(linkedStorageAccount);

var jobOutputBlob = jobOutputStorage.ListOutputs(JobOutputKind.JobOutput)
                                    .SingleOrDefault()
                                    as CloudBlockBlob;

if (jobOutputBlob != null)
{
    await jobOutputBlob.DownloadToFileAsync("movie.mp4", FileMode.Create);
}

约定

约定库定义了Azure Blob存储中的输出存储的路径。作业的所有输出，包括任务输出，都存储在同一个容器中。在该容器内，输出按类型存储，并且（对于任务输出）按任务ID存储。本节描述了作业输出容器名称和作业输出容器内路径的约定。

作业输出容器名称

作业输出容器名称根据以下规则形成

• 将作业ID规范化为小写。 (由于ID中允许的字母集合有限，此规范的本地化问题不大。)
• 如果将“job-”前缀添加到规范化ID会使容器名称有效，则使用该名称。
• 否则
  • 计算规范化ID的SHA1哈希值，并以40个字符的十六进制字符串表示。
  • 将规范化ID中所有下划线和冒号以及一个或多个连字符的序列替换为单个连字符，然后移除任何前导或尾随连字符。
  • 如果结果字符串为空，请使用字符串“job”。
  • 如果结果字符串超过15个字符，则将其截断到15个字符。如果截断导致随后的连字符，请移除它。
  • 容器名称是字符串“job-”，后跟截断的ID，后跟连字符，后跟哈希。

例如，如果作业ID是MyTerrificJob，则容器名称是job-myterrificjob，因为这是一个有效的容器名称。如果作业ID是my-_EVEN_MORE_-terrific-job，则不得使用job-my-_even_more_-terrific-job，因为它不是有效的容器名称，因此我们应用此算法

• my-_even_more_-terrific-job（全部小写）的SHA1哈希为68b05a7d8aa6aa65b9a6892c667a6c406a16ad65。
• 将连字符和下划线替换为单个连字符的小写ID给出my-even-more-terrific-job。没有要删除的前导或尾随连字符。
• 截断到15个字符给出我们my-even-more-te。再次，没有前导或尾随连字符要删除。
• 容器最终名称为 job-my-even-more-te-68b05a7d8aa6aa65b9a6892c667a6c406a16ad65。

该算法背后的目的是确保作业获得有效且唯一的容器名称，同时在尽可能的情况下保持人类可读性，通过使用作业ID，在其他情况下包括基于作业ID的前缀。

blob路径

容器内的blob路径取决于输出是存储为作业输出还是任务输出。

作业输出存储为 "${kind}/{filename}"。例如，如果文件 "out/mergeresults.txt" 被存储在 JobOutputKind.JobOutput 下，那么其在容器中的路径是 "$JobOutput/out/mergeresults.txt"。

任务输出存储为 "{taskid}/${kind}/{filename}"。例如，来自任务 "analysis-309" 的文件 "analytics.log" 被存储在 TaskOutputKind.TaskLog 下，那么其在容器中的路径是 "analysis-309/$TaskLog/analytics.log"。

此结构背后的目的是为了使客户端能够根据其类型轻松地定位输出 - 例如，“列出作业的主要输出”或“列出分析-309任务的日志文件”。