Dela via

Spara uppgiftsdata till Azure Storage med Batch-tjänst-API:et

  • Artikel

En uppgift som körs i Azure Batch kan generera utdata när den körs. Uppgiftsutdata måste ofta lagras för hämtning av andra uppgifter i jobbet, klientprogrammet som körde jobbet eller båda. Uppgifter skriver utdata till filsystemet för en Batch-beräkningsnod, men alla data på noden går förlorade när de återskapas eller när noden lämnar poolen. Aktiviteter kan också ha en kvarhållningsperiod för filer, varefter filer som skapats av aktiviteten tas bort. Därför är det viktigt att spara aktivitetsutdata som du behöver senare i ett datalager, till exempel Azure Storage.

Alternativ för lagringskonton i Batch finns i Batch-konton och Azure Storage-konton.

Batch-tjänst-API:et stöder lagring av utdata till Azure Storage för uppgifter och jobbhanteraraktiviteter som körs på pooler med Virtual Machine Configuration. När du lägger till en aktivitet kan du ange en container i Azure Storage som mål för aktivitetens utdata. Batch-tjänsten skriver sedan utdata till containern när uppgiften är klar.

När du använder Batch-tjänst-API:et för att spara aktivitetsutdata behöver du inte ändra programmet som aktiviteten körs i. Med några ändringar i klientprogrammet kan du i stället spara aktivitetens utdata från samma kod som skapar uppgiften.

Viktigt!

Att bevara uppgiftsdata till Azure Storage med Batch-tjänst-API:et fungerar inte med pooler som skapats före den 1 februari 2018.

När använder jag Batch-tjänst-API:et för att spara aktivitetsutdata?

Azure Batch tillhandahåller mer än ett sätt att spara aktivitetsutdata. Att använda Batch-tjänst-API:et är en praktisk metod som passar bäst för dessa scenarier:

  • Du vill skriva kod för att spara aktivitetsutdata från klientprogrammet, utan att ändra programmet som aktiviteten körs i.
  • Du vill spara utdata från Batch-uppgifter och jobbhanteraraktiviteter i pooler som skapats med konfigurationen av den virtuella datorn.
  • Du vill spara utdata till en Azure Storage-container med ett godtyckligt namn.
  • Du vill spara utdata till en Azure Storage-container med namnet enligt Standard för Batch-filkonventioner.

Om ditt scenario skiljer sig från de som anges ovan kan du behöva överväga en annan metod. Batch-tjänst-API:et stöder till exempel för närvarande inte strömmande utdata till Azure Storage medan uppgiften körs. Om du vill strömma utdata bör du överväga att använda batchfilkonventionsbiblioteket som är tillgängligt för .NET. För andra språk måste du implementera din egen lösning. Mer information om andra alternativ finns i Behåll jobb- och uppgiftsutdata till Azure Storage.

Skapa en container i Azure Storage

Om du vill spara aktivitetsutdata till Azure Storage måste du skapa en container som fungerar som mål för utdatafilerna. Skapa containern innan du kör uppgiften, helst innan du skickar jobbet, med hjälp av lämpligt Azure Storage-klientbibliotek eller SDK. Mer information om Azure Storage-API:er finns i Azure Storage-dokumentationen.

Om du till exempel skriver ditt program i C# använder du Azure Storage-klientbiblioteket för .NET. I följande exempel visas hur du skapar en container:

CloudBlobContainer container = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
await container.CreateIfNotExists();

Ange utdatafiler för aktivitetsutdata

Om du vill ange utdatafiler för en aktivitet skapar du en samling OutputFile-objekt och tilldelar den till egenskapen CloudTask.OutputFiles när du skapar uppgiften. Du kan använda en signatur för delad åtkomst (SAS) eller hanterad identitet för att autentisera åtkomsten till containern.

Använda en signatur för delad åtkomst

När du har skapat containern hämtar du en signatur för delad åtkomst (SAS) med skrivåtkomst till containern. En SAS ger delegerad åtkomst till containern. SAS beviljar åtkomst med en angiven uppsättning behörigheter och under ett angivet tidsintervall. Batch-tjänsten behöver en SAS med skrivbehörighet för att skriva aktivitetsutdata till containern. Mer information om SAS finns i Använda signaturer för delad åtkomst (SAS) i Azure Storage.

När du får en SAS med hjälp av Azure Storage-API:erna returnerar API:et en SAS-tokensträng. Den här tokensträngen innehåller alla parametrar i SAS, inklusive behörigheter och det intervall som SAS är giltigt för. Om du vill använda SAS för att komma åt en container i Azure Storage måste du lägga till SAS-tokensträngen i resurs-URI:n. Resurs-URI:n ger tillsammans med den tillagda SAS-token autentiserad åtkomst till Azure Storage.

I följande exempel visas hur du hämtar en skrivskyddad SAS-tokensträng för containern och lägger sedan till SAS i containerns URI:

string containerSasToken = container.GetSharedAccessSignature(new SharedAccessBlobPolicy()
{
    SharedAccessExpiryTime = DateTimeOffset.UtcNow.AddDays(1),
    Permissions = SharedAccessBlobPermissions.Write
});

string containerSasUrl = container.Uri.AbsoluteUri + containerSasToken;

I följande C#-kodexempel skapas en uppgift som skriver slumpmässiga tal till en fil med namnet output.txt. I exemplet skapas en utdatafil som output.txt ska skrivas till containern. Exemplet skapar också utdatafiler för alla loggfiler som matchar filmönstret std*.txt (t.ex.stdout.txt och stderr.txt). Container-URL:en kräver den SAS som skapades tidigare för containern. Batch-tjänsten använder SAS för att autentisera åtkomsten till containern.

new CloudTask(taskId, "cmd /v:ON /c \"echo off && set && (FOR /L %i IN (1,1,100000) DO (ECHO !RANDOM!)) > output.txt\"")
{
    OutputFiles = new List<OutputFile>
    {
        new OutputFile(
            filePattern: @"..\std*.txt",
            destination: new OutputFileDestination(
         new OutputFileBlobContainerDestination(
                    containerUrl: containerSasUrl,
                    path: taskId)),
            uploadOptions: new OutputFileUploadOptions(
            uploadCondition: OutputFileUploadCondition.TaskCompletion)),
        new OutputFile(
            filePattern: @"output.txt",
            destination: 
         new OutputFileDestination(new OutputFileBlobContainerDestination(
                    containerUrl: containerSasUrl,
                    path: taskId + @"\output.txt")),
            uploadOptions: new OutputFileUploadOptions(
            uploadCondition: OutputFileUploadCondition.TaskCompletion)),
}

Kommentar

Om du använder det här exemplet med Linux måste du ändra omvänt snedstreck till snedstreck.

Använda hanterad identitet

I stället för att generera och skicka en SAS med skrivåtkomst till containern till Batch kan en hanterad identitet användas för att autentisera med Azure Storage. Identiteten måste tilldelas till Batch-poolen och även ha rolltilldelningen Storage Blob Data Contributor för containern som ska skrivas till. Batch-tjänsten kan sedan uppmanas att använda den hanterade identiteten i stället för en SAS för att autentisera åtkomsten till containern.

CloudBlobContainer container = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
await container.CreateIfNotExists();

new CloudTask(taskId, "cmd /v:ON /c \"echo off && set && (FOR /L %i IN (1,1,100000) DO (ECHO !RANDOM!)) > output.txt\"")
{
    OutputFiles = new List<OutputFile>
    {
        new OutputFile(
            filePattern: @"..\std*.txt",
            destination: new OutputFileDestination(
         new OutputFileBlobContainerDestination(
                    containerUrl: container.Uri,
                    path: taskId,
                    identityReference: new ComputeNodeIdentityReference() { ResourceId = "/subscriptions/SUB/resourceGroups/RG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/identity-name"} })),
            uploadOptions: new OutputFileUploadOptions(
            uploadCondition: OutputFileUploadCondition.TaskCompletion))
    }
}

Ange ett filmönster för matchning

När du anger en utdatafil kan du använda egenskapen OutputFile.FilePattern för att ange ett filmönster för matchning. Filmönstret kan matcha noll filer, en enskild fil eller en uppsättning filer som skapas av uppgiften.

Egenskapen FilePattern stöder standardtecken för filsystem, till exempel * (för icke-rekursiva matchningar) och ** (för rekursiva matchningar). Kodexemplet ovan anger till exempel filmönstret för att matcha std*.txt icke-rekursivt:

filePattern: @"..\std*.txt"

Om du vill ladda upp en enskild fil anger du ett filmönster utan jokertecken. Kodexemplet ovan anger till exempel det filmönster som ska matcha output.txt:

filePattern: @"output.txt"

Ange ett uppladdningsvillkor

Egenskapen OutputFileUploadOptions.UploadCondition tillåter villkorlig uppladdning av utdatafiler. Ett vanligt scenario är att ladda upp en uppsättning filer om uppgiften lyckas och en annan uppsättning filer om den misslyckas. Du kanske till exempel bara vill ladda upp utförliga loggfiler när uppgiften misslyckas och avslutas med en icke-nollavslutskod. På samma sätt kanske du bara vill ladda upp resultatfiler om uppgiften lyckas, eftersom filerna kanske saknas eller är ofullständiga om aktiviteten misslyckas.

Kodexemplet ovan anger egenskapen UploadCondition till TaskCompletion. Den här inställningen anger att filen ska laddas upp när aktiviteterna har slutförts, oavsett värdet för slutkoden.

uploadCondition: OutputFileUploadCondition.TaskCompletion

Andra inställningar finns i uppräkningen OutputFileUploadCondition .

Skilja filer med samma namn

Aktiviteterna i ett jobb kan skapa filer med samma namn. Till exempel stdout.txt och stderr.txt skapas för varje uppgift som körs i ett jobb. Eftersom varje aktivitet körs i sin egen kontext är dessa filer inte i konflikt med nodens filsystem. Men när du laddar upp filer från flera aktiviteter till en delad container måste du skilja filer med samma namn.

OutputFileBlobContainerDestination .Egenskapen Path anger målbloben eller den virtuella katalogen för utdatafiler. Du kan använda egenskapen Sökväg för att namnge bloben eller den virtuella katalogen på ett sådant sätt att utdatafiler med samma namn namnges unikt i Azure Storage. Att använda aktivitets-ID:t i sökvägen är ett bra sätt att säkerställa unika namn och enkelt identifiera filer.

Om egenskapen FilePattern är inställd på ett jokerteckenuttryck laddas alla filer som matchar mönstret upp till den virtuella katalog som anges av egenskapen Sökväg. Om containern till exempel är mycontainer, är mytaskaktivitets-ID och filmönstret är ..\std*.txt, kommer de absoluta URI:erna till utdatafilerna i Azure Storage att likna:

https://myaccount.blob.core.windows.net/mycontainer/mytask/stderr.txt
https://myaccount.blob.core.windows.net/mycontainer/mytask/stdout.txt

Om egenskapen FilePattern är inställd på att matcha ett enda filnamn, vilket innebär att den inte innehåller några jokertecken, anger värdet för egenskapen Sökväg det fullständigt kvalificerade blobnamnet. Om du förväntar dig att namngivningen ska vara i konflikt med en enskild fil från flera uppgifter ska du ta med namnet på den virtuella katalogen som en del av filnamnet för att skilja filerna åt. Ange till exempel egenskapen Sökväg så att den innehåller aktivitets-ID, avgränsartecken (vanligtvis ett snedstreck) och filnamnet:

path: taskId + @"/output.txt"

De absoluta URI:erna för utdatafilerna för en uppsättning aktiviteter liknar:

https://myaccount.blob.core.windows.net/mycontainer/task1/output.txt
https://myaccount.blob.core.windows.net/mycontainer/task2/output.txt

Mer information om virtuella kataloger i Azure Storage finns i Lista blobarna i en container.

Många utdatafiler

När en uppgift anger flera utdatafiler kan du stöta på begränsningar som införts av Azure Batch-API:et. Det är lämpligt att hålla dina uppgifter små och hålla antalet utdatafiler lågt.

Om du stöter på gränser kan du överväga att minska antalet utdatafiler genom att använda filmönster eller använda filcontainrar som tjära eller zip för att konsolidera utdatafilerna. Du kan också använda montering eller andra metoder för att bevara utdata (se Spara jobb och aktivitetsutdata).

Diagnostisera filöverföringsfel

Om det inte går att ladda upp utdatafiler till Azure Storage flyttas aktiviteten till tillståndet Slutfört och TaskExecutionInformation.Egenskapen FailureInformation har angetts. Granska egenskapen FailureInformation för att fastställa vilket fel som uppstod. Här är till exempel ett fel som uppstår vid filuppladdning om containern inte kan hittas:

Category: UserError
Code: FileUploadContainerNotFound
Message: One of the specified Azure container(s) was not found while attempting to upload an output file

Vid varje filuppladdning skriver Batch två loggfiler till beräkningsnoden fileuploadout.txt och fileuploaderr.txt. Du kan undersöka loggfilerna för att lära dig mer om ett specifikt fel. I de fall där filuppladdningen aldrig gjordes, till exempel eftersom själva uppgiften inte kunde köras, så finns inte dessa loggfiler.

Diagnostisera prestanda för filuppladdning

Filloggarna fileuploadout.txt överför förlopp. Du kan undersöka den här filen om du vill veta mer om hur lång tid det tar att ladda upp filer. Tänk på att det finns många bidragande faktorer för att ladda upp prestanda, inklusive nodens storlek, annan aktivitet på noden vid tidpunkten för uppladdningen, om målcontainern finns i samma region som Batch-poolen, hur många noder som laddar upp till lagringskontot samtidigt och så vidare.

Använda Batch-tjänst-API:et med Standard för Batch-filkonventioner

När du bevarar aktivitetsutdata med Batch-tjänst-API:et kan du namnge målcontainern och blobarna som du vill. Du kan också välja att namnge dem enligt Standard för Batch-filkonventioner. Standard för filkonventioner bestämmer namnen på målcontainern och bloben i Azure Storage för en viss utdatafil baserat på namnen på jobbet och aktiviteten. Om du använder standarden Filkonventioner för namngivning av utdatafiler är dina utdatafiler tillgängliga för visning i Azure-portalen.

Om du utvecklar i C# kan du använda de metoder som är inbyggda i Batch File Conventions-biblioteket för .NET. Det här biblioteket skapar rätt namngivna containrar och blobsökvägar åt dig. Du kan till exempel anropa API:et för att hämta rätt namn på containern baserat på jobbnamnet:

string containerName = job.OutputStorageContainerName();

Du kan använda metoden CloudJobExtensions.GetOutputStorageContainerUrl för att returnera en URL för signatur för delad åtkomst (SAS) som används för att skriva till containern. Du kan sedan skicka denna SAS till konstruktorn OutputFileBlobContainerDestination .

Om du utvecklar på ett annat språk än C# måste du implementera filkonventionernas standard själv.

Kodexempel

Exempelprojektet PersistOutputs är ett av Azure Batch-kodexemplen på GitHub. Den här Visual Studio-lösningen visar hur du använder Batch-klientbiblioteket för .NET för att spara aktivitetsutdata till beständig lagring. Följ dessa steg för att köra exemplet:

  1. Öppna projektet i Visual Studio 2019.
  2. Lägg till autentiseringsuppgifterna för batch- och lagringskontot i Account Inställningar.settings i projektet Microsoft.Azure.Batch.Samples.Common.
  3. Skapa (men kör inte) lösningen. Återställ alla NuGet-paket om du uppmanas att göra det.
  4. Använd Azure-portalen för att ladda upp ett programpaket för PersistOutputsTask. PersistOutputsTask.exe Inkludera och dess beroende sammansättningar i .zip-paketet, ange program-ID:t till "PersistOutputsTask" och programpaketversionen till "1.0".
  5. Starta (kör) Projektet PersistOutputs .
  6. När du uppmanas att välja den beständighetsteknik som ska användas för att köra exemplet anger du 2 för att köra exemplet med hjälp av Batch-tjänst-API:et för att spara aktivitetsutdata.
  7. Om du vill kan du köra exemplet igen, ange 3 för att spara utdata med Batch-tjänst-API:et och även namnge målcontainern och blobsökvägen enligt filkonventionernas standard.

Nästa steg