Beibehalten von Auftrags- und Taskdateien in Azure Storage mit der Batch-Dateikonventionenbibliothek für .NET

  • Artikel

Eine in Azure Batch ausgeführte Aufgabe kann während der Ausführung Ausgabedaten erzeugen. Oft müssen Aufgabenausgabedaten gespeichert werden, damit sie von anderen Aufgaben des Auftrags, von der Clientanwendung, die den Auftrag ausgeführt hat, oder von beiden abgerufen werden können. Aufgaben schreiben Ausgabedaten in das Dateisystem eines Batch-Computeknotens, doch alle Daten im Knoten gehen verloren, wenn ein Reimaging ausgeführt wird oder der Knoten den Pool verlässt. Außerdem können Aufgaben eine Vermerkdauer für Dateien aufweisen, nach der die von der Aufgabe erstellten Dateien gelöscht werden. Aus diesen Gründen es ist wichtig, Aufgabenausgaben, die Sie später benötigen, in einem Datenspeicher wie Azure Storage beizubehalten.

Informationen zu den Optionen für Speicherkonten in Batch finden Sie unter Batch-Konten und Azure Storage-Konten.

Mithilfe der Dateikonventionenbibliothek für .NET können Sie Taskdaten aus Azure Batch speichern. Die Dateikonventionenbibliothek vereinfacht den Vorgang des Speicherns und Abrufens von Taskausgabendaten in Azure Storage. Sie können die Dateikonventionenbibliothek sowohl im Task- als auch im Clientcode verwenden. Verwenden Sie die Bibliothek im Taskmodus, um Dateien dauerhaft zu speichern. Verwenden Sie die Bibliothek im Clientmodus, um Dateien auflisten und abrufen zu können. Ihr Taskcode kann die Bibliothek auch zum Abrufen der Ausgaben von vorgelagerten Tasks verwenden, z. B. in einem Szenario mit Taskabhängigkeiten.

Um Ausgabedateien mit der Dateikonventionenbibliothek abzurufen, suchen Sie die Dateien für einen Auftrag oder Task. Sie müssen die Namen oder Speicherorte der Dateien nicht kennen. Stattdessen können Sie die Dateien nach ID und Zweck auflisten. Listen Sie beispielsweise alle Zwischendateien für eine bestimmte Aufgabe auf. Sie können auch eine Vorschaudatei für einen bestimmten Auftrag abrufen.

Ab Version 1.5.2017 unterstützt die Batch-Dienst-API das Beibehalten von Ausgabedaten in Azure Storage für Tasks und Auftrags-Manager-Tasks, die auf Pools ausgeführt werden, die mit der Konfiguration des virtuellen Computers (VM) erstellt wurden. Sie können die Ausgabe mithilfe des Codes beibehalten, der eine Aufgabe erstellt. Diese Methode ist eine Alternative zur Dateikonventionenbibliothek. Sie können Ihre Batch Client-Anwendungen ändern, um die Ausgabe beizubehalten, ohne die Anwendung aktualisieren zu müssen, die ihr Task ausführt. Weitere Informationen finden Sie unter Beibehalten von Taskdateien mithilfe der Batch-Dienst-API in Azure Storage.

Anwendungsfälle der Bibliothek

Azure Batch bietet mehrere Möglichkeiten zum Beibehalten der Taskausgabe. Verwenden Sie die Dateikonventionenbibliothek, wenn Sie Folgendes durchführen möchten:

  • Ändern des Codes für die Anwendung, die von Ihrem Task ausgeführt wird, um Dateien dauerhaft zu speichern.
  • Streamen von Daten in Azure Storage , während der Task noch ausgeführt wird.
  • Beibehalten von Daten aus Pools.
  • Suchen und Herunterladen von Taskausgabedateien in Ihrer Clientanwendung oder anderen Tasks nach ID oder Zweck.
  • Anzeigen der Taskausgabe im Azure-Portal.

Für andere Szenarien sollten Sie einen anderen Ansatz in Betracht ziehen. Weitere Informationen zu anderen Optionen finden Sie unter Beibehalten von Auftrags- und Taskausgaben in Azure Storage.

Was ist der Batch-Dateikonventionenstandard?

Der Batch-Dateikonventionenstandard bietet ein Benennungsschema für die Zielcontainer und Blob-Pfade, in dem die Ausgabedateien geschrieben werden. Dateien, die im Azure-Speicher gespeichert sind und dem Standard entsprechen, sind automatisch im Azure-Portal sichtbar.

Die Dateikonventionenbibliothek für .NET benennt Ihre Speichercontainer und Taskausgabedateien automatisch entsprechend dem Standard. Die Bibliothek stellt auch Methoden zum Abfragen von Ausgabedateien in Azure Storage bereit. Sie können Abfragen nach Auftrags-ID, Aufgaben-ID oder Zweck ausführen.

Wenn Sie mit einer anderen Sprache als .NET entwickeln, können Sie den Dateikonventionenstandard selbst in Ihrer Anwendung implementieren. Weitere Informationen finden Sie unter Implementieren des Batch-Konventionenstandards.

Um Ausgabedaten in Azure Storage mithilfe der Dateikonventionenbibliothek beizubehalten, verknüpfen Sie zuerst ein Azure Storage-Konto mit ihrem Batch-Konto.

  1. Melden Sie sich beim Azure-Portal an.
  2. Suchen Sie in der Suchleiste nach Batch, und wählen Sie die Option aus.
  3. Wählen Sie das Batch-Konto aus, das mit Azure Storage verknüpft werden soll.
  4. Wählen Sie auf der Batch-Kontoseite unter Einstellungen die Option Speicherkonto aus.
  5. Wenn Sie noch kein dem Batch-Konto zugeordnetes Azure Storage-Konto haben, wählen Sie Speicherkonto (Kein) aus.
  6. Wählen Sie das zu verwendende Azure Storage-Konto aus. Um eine optimale Leistung zu erzielen, verwenden Sie ein Konto in derselben Region wie das Batch-Konto.

Beibehalten von Ausgabedateien

Sie können Auftrags- und Taskausgabedaten mit der Dateikonventionenbibliothek beibehalten. Erstellen Sie zuerst einen Container in Azure Storage. Speichern Sie dann die Ausgabe im Container. Verwenden der Azure Storage-Clientbibliothek für .NET in Ihrem Taskcode zum Hochladen der Taskausgabe auf den Container.

Weitere Informationen zum Arbeiten mit Containern und Blobs in Azure Storage finden Sie unter Erste Schritte mit Azure Blob Storage in .NET.

Alle Auftrags-und Taskausgaben, die mit der Bibliothek beibehalten werden, werden im gleichen Container gespeichert. Wenn eine große Anzahl von Tasks gleichzeitig versucht, Dateien zu speichern, werden ggf. die Drosselungslimits von Azure Storage erzwungen. Weitere Informationen finden Sie unter Checkliste zur Leistung und Skalierbarkeit von Blob Storage.

Erstellen eines Speichercontainers

Wenn Sie eine Taskausgabe in Azure Storage beibehalten möchten, müssen Sie zunächst einen Container durch Aufrufen von CloudJob.PrepareOutputStorageAsync erstellen. Diese Erweiterungsmethode akzeptiert ein CloudStorageAccount-Objekt als Parameter. Die Methode erstellt einen gemäß dem Dateikonventionenstandard benannten Container. Der Inhalt des Containers kann vom Azure-Portal und den in diesem Artikel beschriebenen Abrufmethoden entdeckt werden.

Erstellen Sie in der Regel einen Container in Ihrer Clientanwendung, die Ihre Pools, Aufträge und Tasks erstellt. Beispiel:

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

Speichern von Taskausgaben

Nach dem Erstellen Ihres Speichercontainers können Tasks die Ausgabe mit TaskOutputStorage im Container speichern. Diese Klasse ist in der Dateikonventionenbibliothek verfügbar.

Erstellen Sie in Ihrem Taskcode ein TaskOutputStorage-Objekt. Rufen Sie nach Ausführung des Tasks die TaskOutputStorage.SaveAsync-Methode auf. In diesem Schritt wird die Ausgabe in Azure Storage gespeichert.

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

Der kind-Parameter der TaskOutputStorage. SaveAsync-Methode kategorisiert beibehaltene Dateien. Es gibt vier vordefinierte TaskOutputKind-Typen: TaskOutput, TaskPreview, TaskLog und TaskIntermediate.. Sie können auch benutzerdefinierte Kategorien der Ausgabe definieren.

Geben Sie an, welche Art von Ausgaben beim späteren Abfragen von Batch aufgeführt werden soll. Beim Auflisten der Ausgaben für einen Task können Sie dann nach einem der Ausgabetypen filtern. Filtern Sie beispielsweise nach „Ich hätte gern die Vorschau-Ausgabe für Task 109.“ Weitere Informationen finden Sie unter Abrufen von Ausgabedaten.

Die Art der Ausgabe bestimmt auch, wo eine Ausgabedatei im Azure-Portal angezeigt wird. Dateien in der Kategorie TaskOutput befinden sich unter Taskausgabedateien. Dateien in der Kategorie TaskLog befinden sich unter Taskprotokolle.

Speichern von Auftragsausgaben

Sie können auch die Ausgaben speichern, die einem gesamten Auftrag zugeordnet sind. Beispielsweise können Sie im Zusammenführungstask eines Filmrenderauftrags den vollständig gerenderten Film als Ausgabe des Auftrags beibehalten. Nach Abschluss des Auftrags kann Ihre Clientanwendung die Ausgaben für den Auftrag auflisten und abrufen. Ihre Clientanwendung muss die einzelnen Aufgaben nicht abfragen.

Speichern Sie die Ausgabe des Auftrags durch Aufrufen der JobOutputStorage.SaveAsync-Methode. Geben Sie JobOutputKind und den Dateinamen an. Beispiel:

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

Ähnlich wie beim Typ TaskOutputKind für Taskausgaben verwenden Sie den Typ JobOutputKind, um die beibehaltenen Dateien eines Auftrags zu kategorisieren. Später können Sie einen bestimmten Ausgabetyp auflisten. Der JobOutputKind-Typ enthält sowohl die Ausgabe- als auch die Vorschaukategorien. Der Typ unterstützt auch das Erstellen benutzerdefinierter Kategorien.

Speichern von Taskprotokollen

Möglicherweise müssen Sie auch Dateien beibehalten, die während der Ausführung eines Tasks aktualisiert werden. Beispielsweise müssen Sie möglicherweise Protokolldateien oder stdout.txt und stderr.txt beibehalten. Die Dateikonventionenbibliothek stellt die TaskOutputStorage.SaveTrackedAsync-Methode bereit, um diese Arten von Dateien beizubehalten. Verfolgen Sie Updates einer Datei auf dem Knoten in einem angegebenen Intervall mit SaveTrackedAsync nach. Speichern Sie diese Updates dann dauerhaft in Azure Storage.

Im folgenden Beispiel wird SaveTrackedAsync verwendet, um stdout.txt während der Ausführung des Tasks alle 15 Sekunden in Azure Storage zu aktualisieren:

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

Ersetzen Sie den kommentierten Abschnitt Code to process data and produce output file(s) durch den üblichen Code Ihres Tasks. Unter Umständen verfügen Sie beispielsweise über Code, der Daten aus Azure Storage herunterlädt und Transformationen oder Berechnungen mit diesen Daten durchführt. Sie können diesen Code mit einem using-Block umschließen, um eine Datei regelmäßig mit SaveTrackedAsync zu aktualisieren.

Der Knoten-Agent ist ein Programm, das auf jedem Knoten im Pool ausgeführt wird. Dieses Programm stellt die Befehls- und Steuerungsschnittstelle zwischen dem Knoten und dem Batch-Dienst bereit. Der Task.Delay-Aufruf ist am Ende dieses using-Blocks erforderlich. Der Aufruf stellt sicher, dass der Knoten-Agent Zeit hat, die Standardinhalte in die stdout.txt-Datei auf dem Knoten zu leeren. Ohne diese Verzögerung gehen unter Umständen die letzten Sekunden der Ausgabe verloren. Möglicherweise benötigen Sie diese Verzögerung nicht für alle Dateien.

Wenn Sie die Dateinachverfolgung mit SaveTrackedAsync aktivieren, werden nur Anfügungen der nachverfolgten Datei in Azure Storage beibehalten. Verwenden Sie diese Methode nur zum Nachverfolgen von nicht rotierenden Protokolldateien oder anderen Dateien, die mit Anhängevorgängen an das Ende einer Datei geschrieben werden.

Abrufen der Ausgabedateien

Um Ausgabedateien für einen bestimmten Task oder Auftrag abzurufen, müssen Sie den Pfad in Azure Storage oder Dateinamen nicht kennen. Sie können stattdessen Ausgabedateien nach Task- oder Auftrags-ID anfordern.

Der folgende Beispielcode durchläuft die Tasks eines Auftrags. Als Nächstes gibt der Code einige Informationen zu den Ausgabedateien für den Task aus. Anschließend lädt der Code die Dateien aus Azure Storage herunter.

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

Anzeigen von Ausgabedateien im Azure-Portal

Wenn Sie den Batch-Dateikonventionenstandard verwenden, können Sie die Dateien im Azure-Portal anzeigen.

Um die Anzeige Ihrer Ausgabedateien im Portal zu aktivieren, müssen die folgenden Voraussetzungen erfüllt sein:

Damit Ausgabedateien automatisch im Azure-Portal angezeigt werden, müssen Sie Folgendes tun:

  1. Verknüpfen Sie ein Azure Storage-Konto mit Ihrem Batch-Konto.
  2. Befolgen Sie die vordefinierten Namenskonventionen für Azure Storage-Container und -Dateien. Lesen Sie die INFODATEI für alle Definitionen. Wenn Sie die Dateikonventionenbibliothek zur Beibehaltung Ihrer Ausgabe verwenden, werden Ihre Dateien entsprechend dem Dateikonventionenstandard beibehalten.

So zeigen Sie Taskausgabedateien und -protokolle im Azure-Portal an:

  1. Melden Sie sich beim Azure-Portal an.
  2. Wechseln Sie zu dem Task, für den Sie die Ausgabe anzeigen möchten.
  3. Wählen Sie entweder Gespeicherte Ausgabedateien oder Gespeicherte Protokolle aus.

Codebeispiel

Das Beispielprojekt PersistOutputs ist eines der Azure Batch-Codebeispiele auf GitHub. Diese Visual Studio-Projektmappe veranschaulicht, wie die Azure Batch-Dateikonventionenbibliothek verwendet werden kann, um die Taskausgabe in dauerhaftem Speicher beizubehalten. Gehen Sie folgendermaßen vor, um das Beispiel auszuführen:

  1. Öffnen Sie das Projekt in Visual Studio 2019.
  2. Fügen Sie die Anmeldeinformationen für Ihr Batch- und Azure Storage-Konto zu AccountSettings.settings im Microsoft.Azure.Batch.Samples.Common-Projekt hinzu.
  3. Erstellen Sie die Projektmappe. Führen Sie die Lösung noch nicht aus.
  4. Stellen Sie NuGet-Pakete wieder her, wenn Sie dazu aufgefordert werden.
  5. Laden Sie im Azure-Portal ein Anwendungspaket für PersistOutputsTask hoch.
    1. Schließen Sie die ausführbare Datei PersistOutputsTask.exe und ihre abhängigen Assemblys in das ZIP-Paket ein.
    2. Legen Sie die Anwendungs-ID auf PersistOutputsTask fest.
    3. Legen Sie die Anwendungspaketversion auf 1.0 fest.
  6. Wählen Sie Starten aus, um das Projekt auszuführen.
  7. Wenn Sie aufgefordert werden, die zu verwendende Persistenztechnologie auszuwählen, geben Sie 1 ein. Diese Option führt das Beispiel mithilfe der Dateikonventionenbibliothek aus, um die Taskausgabe dauerhaft zu speichern.

Abrufen der Batch-Dateikonventionenbibliothek für .NET

Die Batch-Dateikonventionenbibliothek für .NET finden Sie unter NuGet. Die Bibliothek erweitert die Klassen CloudJob und CloudTask durch neue Methoden. Weitere Informationen finden Sie in der Referenzdokumentation zur Dateikonventionenbibliothek.

Der Quellcode der Dateikonventionenbibliothek ist auf GitHub verfügbar.

Nächste Schritte