使用適用於 .NET 的 Batch 檔案慣例程式庫將作業和工作輸出保存到 Azure 儲存體

發行項
06/01/2023

在 Azure Batch 中執行的工作，可能會在執行時產生輸出資料。工作輸出的資料通常需要加以儲存，才能供作業中的其他工作、執行作業的用戶端應用程式 (或兩者) 擷取。工作會將輸出資料寫入 Batch 計算節點的檔案系統，但當它重新安裝映像，或當節點離開集區時，節點上的所有資料都會遺失。工作可能也會有檔案保留期，在此期間之後，會將工作所建立的檔案刪除。基於這些理由，請務必將您稍後需要的工作輸出保存至資料存放區，例如 Azure 儲存體。

如需 Batch 中的儲存體帳戶選項，請參閱 Batch 帳戶與 Azure 儲存體帳戶。

您可以使用適用於 .NET 的 File Conventions 程式庫，以保存 Azure Batch 的工作資料。 File Conventions 程式庫會簡化 Azure 儲存體中，儲存和擷取工作輸出資料的程序。您可以在工作和用戶端程式碼中，使用 File Conventions 程式庫。在工作模式中，使用程式庫保存檔案。在用戶端模式中，使用程式庫列出或擷取檔案。您的工作程式碼也可以使用程式庫擷取上游工作的輸出，例如工作相依性案例。

若要使用 File Conventions 程式庫擷取輸出檔案，請尋找作業或工作的檔案。您不需要知道檔案的名稱或位置。但您可以依識別碼和用途列出檔案。例如，列出指定工作所有的中繼檔案。或者，取得指定作業的預覽檔案。

從 2017-05-01 版開始，Batch 服務 API 針對使用虛擬機器 (VM) 設定建立的集區，支援在該集區上執行工作和作業管理員工作，保存輸出資料至 Azure 儲存體。您可以從建立工作的程式碼內部保存輸出。此方法是 File Conventions 程式庫的替代方法。您可以修改 Batch 用戶端應用程式以保存輸出，而不需要更新您的工作正在執行的應用程式。如需詳細資訊，請參閱使用 Batch 服務 API 將工作資料保存到 Azure 儲存體。

程式庫使用案例

Azure Batch 提供多種方式來保存工作輸出。您要執行下列動作時，請使用 File Conventions 程式庫：

為保存檔案，修改工作目前執行的應用程式程式碼。
當工作仍在執行中時，將資料串流至 Azure 儲存體。
保存集區的資料。
在用戶端應用程式或其他工作中，依識別碼或用途尋找或下載工作輸出檔案。
在 Azure 入口網站中檢視工作輸出。

如果是其他案例，不妨考慮不同的方法。如需其他選項的詳細資訊，請參閱保存作業和工作輸出至 Azure 儲存體。

Batch 檔案慣例標準是什麼？

Batch 檔案慣例標準提供目的地容器的命名配置，以及寫入輸出檔案的 blob 路徑。您可以在 Azure 入口網站中自動檢視保存至 Azure 儲存體符合標準的檔案。

適用於 .NET 的 File Conventions 程式庫會根據標準，自動命名儲存體容器和工作輸出檔案。程式庫也提供方法，在 Azure 儲存體中查詢輸出檔案。您可以依作業識別碼、工作識別碼或用途查詢。

如果您要使用 .NET 之外的語言開發，您可以在應用程式中實作 File Conventions 標準。如需詳細資訊，請參閱實作 Batch 檔案慣例標準。

連結 Azure 儲存體帳戶

若要使用 File Conventions 程式庫來保存輸出資料至 Azure 儲存體，您必須先連結 Azure 儲存體帳戶與 Batch 帳戶。

登入 Azure 入口網站。
在搜尋列中搜尋並選取 [Batch]。
選取要連結 Azure 儲存體的 Batch 帳戶。
在 [Batch 帳戶] 頁面上的 [設定] 底下，選取 [儲存體帳戶]。
如果您還沒有 Batch 帳戶相關的 Azure 儲存體帳戶，請選取 [儲存體帳戶 (無)]。
選取要使用的 Azure 儲存體帳戶。若要獲得最佳效能，請使用和 Batch 帳戶位於相同區域中的帳戶。

保存輸出資料

您可以使用 File Conventions 程式庫保存作業和工作輸出資料。首先，在 Azure 儲存體中建立容器。然後，儲存輸出至容器。在您的工作程式碼中使用適用於 .NET 的 Azure 儲存體用戶端程式庫，將工作輸出上傳到容器中。

如需在 Azure 儲存體中使用容器和 Blob 的詳細資訊，請參閱以 .NET 開始使用 Azure Blob 儲存體。

使用檔案慣例程式庫保存的所有作業和工作輸出，都會儲存在相同容器中。如果有大量的工作同時嘗試保存檔案，系統可能強制執行 Azure 儲存體節流限制。如需詳細資訊，請參閱 Blob 儲存體的效能和可擴縮性檢查清單。

建立儲存體容器

若要將工作輸出保存到 Azure 儲存體，請先呼叫 CloudJob PrepareOutputStorageAsync 來建立容器。這個擴充方法會將 CloudStorageAccount 物件當作參數。此方法會根據 File Conventions 標準，建立命名的容器。容器的內容可透過 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 來儲存輸出至容器。此類別可在 File Conventions 程式庫中取得。

在您的工作程式碼中，建立 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");

TaskOutputStorage.SaveAsync 方法的 kind 參數會分類保存的檔案。有四個預先定義的 TaskOutputKind 類型：TaskOutput、TaskPreview、TaskLog 和 TaskIntermediate. 您也可以定義輸出的自訂類別。

稍後查詢 Batch 時，請指定要列出的輸出類型。接著，列出工作的輸出時，您可以篩選其中一個輸出類型。例如，篩選為「給我工作 109 的 preview 輸出」。如需詳細資訊，請參閱擷取輸出資料。

輸出類型也決定在 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。 File Conventions 程式庫提供 TaskOutputStorage.SaveTrackedAsync 方法來保存這些類型的檔案。使用 SaveTrackedAsync 在節點上定期追蹤檔案的更新。接著，保存這些更新至 Azure 儲存體。

下列範例在工作執行期間使用 SaveTrackedAsync，每 15 秒更新一次 Azure 儲存體中的 stdout.txt：

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 來更新檔案。

節點代理程式是在集區中每個節點上執行的程式。此程式提供節點與 Batch 服務間的命令和控制介面。此 using 區塊結尾需要 Task.Delay 呼叫。此呼叫確保節點代理程式有時間排清標準的內容至節點上的 stdout.txt 檔案。如果無此延遲，可能會遺漏最後幾秒的輸出。只有部分檔案需要此延遲。

當您使用 SaveTrackedAsync 啟用檔案追蹤時，只有附加到追蹤檔案的資料會保存到 Azure 儲存體。僅使用此方法追蹤非輪替記錄檔，或使用附加作業寫入檔案結尾的其他檔案。

擷取輸出資料

若要擷取特定工作或作業的輸出檔案，無須知道 Azure 儲存體的路徑或檔案名稱。相反地，您可以依據工作或作業識別碼要求輸出檔案。

下列範例程式碼會逐一查看作業的工作。接著，程式碼會列印工作輸出檔案的部分資訊。然後，程式碼會從 Azure 儲存體下載檔案。

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 入口網站中檢視輸出檔案

如果工作輸出檔案使用 Batch File Conventions 標準，您可以檢視 Azure 入口網站中的檔案。

若要讓您的輸出檔案顯示在入口網站中，您必須滿足下列需求：

若要輸出檔案在 Azure 入口網站中自動顯示，您必須：

連結 Azure 儲存體帳戶與 Batch 帳戶。
遵循 Azure 儲存體容器和檔案預先定義的命名慣例。檢閱所有定義的讀我檔案。如果您使用 File Conventions 程式庫保存輸出，您的檔案會根據 File Conventions 標準保存。

在 Azure 入口網站中檢視工作輸出檔案和記錄：

登入 Azure 入口網站。
移至您要檢視輸出的工作。
選取 [已儲存的輸出檔案] 或 [已儲存的記錄]。

程式碼範例

PersistOutputs 範例專案是 GitHub 上的其中一個 Azure Batch 程式碼範例。此 Visual Studio 解決方案示範如何使用 Azure Batch File Conventions 程式庫，保存工作輸出至耐久性儲存體。若要執行範例，請遵循下列步驟：

在 Visual Studio 2019 中開啟專案。
新增 Batch 和 Azure 儲存體帳戶的認證至 Microsoft.Azure.Batch.Samples.Common 專案中的 AccountSettings.settings。
建置方案。請暫時不要執行解決方案。
如果出現提示，請還原任何 NuGet 套件。
透過 Azure 入口網站上傳 PersistOutputsTask 的應用程式套件。
1. 在 .zip 套件中包含 PersistOutputsTask.exe 可執行檔和相依組件。
2. 將應用程式識別碼設為 PersistOutputsTask。
3. 將應用程式套件版本設為 1.0。
選取 [開始] 以執行專案。
系統提示您選取要使用的持續性技術時，請輸入 1。此選項會使用 File Conventions 程式庫執行範例，並保存工作輸出。

取得適用於 .NET 的 Batch 檔案慣例程式庫

您可以在 NuGet 取得適用於 .NET 的 Batch 檔案慣例程式庫。此程式庫添加新的方法來擴充 CloudJob 和 CloudTask 類別。如需詳細資訊，請參閱 File Conventions 程式庫參考文件。

GitHub 上提供 File Conventions 程式庫原始程式碼。

共用方式為

使用適用於 .NET 的 Batch 檔案慣例程式庫將作業和工作輸出保存到 Azure 儲存體

程式庫使用案例

Batch 檔案慣例標準是什麼？

連結 Azure 儲存體帳戶

保存輸出資料

建立儲存體容器

儲存工作輸出

儲存工作輸出

儲存工作記錄

擷取輸出資料

在 Azure 入口網站中檢視輸出檔案

程式碼範例

取得適用於 .NET 的 Batch 檔案慣例程式庫

下一步

意見反應

其他資源