Share via

Taakgegevens behouden in Azure Storage met de Batch-service-API

  • Artikel

Een taak die in Azure Batch wordt uitgevoerd, kan uitvoergegevens produceren wanneer deze wordt uitgevoerd. Taakuitvoergegevens moeten vaak worden opgeslagen voor het ophalen door andere taken in de taak, de clienttoepassing die de taak heeft uitgevoerd, of beide. Taken schrijven uitvoergegevens naar het bestandssysteem van een Batch-rekenknooppunt, maar alle gegevens op het knooppunt gaan verloren wanneer de installatiekopie opnieuw wordt gemaakt of wanneer het knooppunt de pool verlaat. Taken kunnen ook een bewaarperiode voor bestanden hebben, waarna bestanden die door de taak zijn gemaakt, worden verwijderd. Om deze redenen is het belangrijk om taakuitvoer te behouden die u later nodig hebt voor een gegevensarchief zoals Azure Storage.

Zie Batch-accounts en Azure Storage-accounts voor opties voor opslagaccounts in Batch.

De Batch-service-API ondersteunt persistente uitvoergegevens naar Azure Storage voor taken en jobbeheertaken die worden uitgevoerd op pools met configuratie van virtuele machines. Wanneer u een taak toevoegt, kunt u een container in Azure Storage opgeven als de bestemming voor de uitvoer van de taak. De Batch-service schrijft vervolgens uitvoergegevens naar die container wanneer de taak is voltooid.

Wanneer u de Batch-service-API gebruikt om taakuitvoer te behouden, hoeft u de toepassing die de taak uitvoert, niet te wijzigen. In plaats daarvan kunt u, met enkele wijzigingen in uw clienttoepassing, de uitvoer van de taak behouden vanuit dezelfde code waarmee de taak wordt gemaakt.

Belangrijk

Het behouden van taakgegevens naar Azure Storage met de Batch-service-API werkt niet met pools die vóór 1 februari 2018 zijn gemaakt.

Wanneer gebruik ik de Batch-service-API om taakuitvoer te behouden?

Azure Batch biedt meer dan één manier om taakuitvoer te behouden. Het gebruik van de Batch-service-API is een handige benadering die het meest geschikt is voor deze scenario's:

  • U wilt code schrijven om taakuitvoer vanuit uw clienttoepassing te behouden, zonder de toepassing te wijzigen die door uw taak wordt uitgevoerd.
  • U wilt uitvoer van Batch-taken en jobbeheertaken behouden in pools die zijn gemaakt met de configuratie van de virtuele machine.
  • U wilt uitvoer behouden naar een Azure Storage-container met een willekeurige naam.
  • U wilt uitvoer behouden naar een Azure Storage-container met de naam volgens de standaard Batch-bestandsconventies.

Als uw scenario verschilt van de hierboven genoemde scenario's, moet u mogelijk een andere benadering overwegen. De Batch-service-API biedt bijvoorbeeld momenteel geen ondersteuning voor streaming-uitvoer naar Azure Storage terwijl de taak wordt uitgevoerd. Als u uitvoer wilt streamen, kunt u overwegen de Batch File Conventions-bibliotheek te gebruiken die beschikbaar is voor .NET. Voor andere talen moet u uw eigen oplossing implementeren. Zie Taak- en taakuitvoer behouden naar Azure Storage voor meer informatie over andere opties.

Een container maken in Azure Storage

Als u taakuitvoer naar Azure Storage wilt behouden, moet u een container maken die fungeert als de bestemming voor uw uitvoerbestanden. Maak de container voordat u uw taak uitvoert, bij voorkeur voordat u uw taak verzendt, met behulp van de juiste Azure Storage-clientbibliotheek of SDK. Zie de Documentatie voor Azure Storage voor meer informatie over Azure Storage-API's.

Als u bijvoorbeeld uw toepassing in C# schrijft, gebruikt u de Azure Storage-clientbibliotheek voor .NET. In het volgende voorbeeld ziet u hoe u een container maakt:

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

Uitvoerbestanden voor taakuitvoer opgeven

Als u uitvoerbestanden voor een taak wilt opgeven, maakt u een verzameling OutputFile-objecten en wijst u deze toe aan de eigenschap CloudTask.OutputFiles wanneer u de taak maakt. U kunt een SAS (Shared Access Signature) of beheerde identiteit gebruiken om toegang tot de container te verifiëren.

Een Shared Access Signature gebruiken

Nadat u de container hebt gemaakt, haalt u een SAS (Shared Access Signature) op met schrijftoegang tot de container. Een SAS biedt gedelegeerde toegang tot de container. De SAS verleent toegang met een opgegeven set machtigingen en gedurende een opgegeven tijdsinterval. De Batch-service heeft een SAS met schrijfmachtigingen nodig om taakuitvoer naar de container te schrijven. Zie Shared Access Signatures (SAS) gebruiken in Azure Storage voor meer informatie over SAS.

Wanneer u een SAS krijgt met behulp van de Azure Storage-API's, retourneert de API een SAS-tokentekenreeks. Deze tokentekenreeks bevat alle parameters van de SAS, inclusief de machtigingen en het interval waarvoor de SAS geldig is. Als u de SAS wilt gebruiken voor toegang tot een container in Azure Storage, moet u de SAS-tokentekenreeks toevoegen aan de resource-URI. De resource-URI, samen met het toegevoegde SAS-token, biedt geverifieerde toegang tot Azure Storage.

In het volgende voorbeeld ziet u hoe u een alleen-schrijven-SAS-tokentekenreeks voor de container opvragen en vervolgens de SAS toevoegt aan de container-URI:

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

string containerSasUrl = container.Uri.AbsoluteUri + containerSasToken;

In het volgende C#-codevoorbeeld wordt een taak gemaakt waarmee willekeurige getallen naar een bestand met de naam output.txtworden geschreven. In het voorbeeld wordt een uitvoerbestand gemaakt dat output.txt naar de container moet worden geschreven. In het voorbeeld worden ook uitvoerbestanden gemaakt voor logboekbestanden die overeenkomen met het bestandspatroon std*.txt (bijvoorbeeldstdout.txt enstderr.txt). Voor de container-URL is de SAS vereist die eerder is gemaakt voor de container. De Batch-service gebruikt de SAS om toegang tot de container te verifiëren.

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

Notitie

Als u dit voorbeeld met Linux gebruikt, moet u de backslashes wijzigen in slashes.

Beheerde identiteit gebruiken

In plaats van een SAS te genereren en door te geven met schrijftoegang tot de container naar Batch, kan een beheerde identiteit worden gebruikt om te verifiëren met Azure Storage. De identiteit moet worden toegewezen aan de Batch-pool en moet ook de Storage Blob Data Contributor roltoewijzing hebben waar de container naar moet worden geschreven. De Batch-service kan vervolgens worden verteld om de beheerde identiteit te gebruiken in plaats van een SAS om toegang tot de container te verifiëren.

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

Een bestandspatroon opgeven voor overeenkomende

Wanneer u een uitvoerbestand opgeeft, kunt u de eigenschap OutputFile.FilePattern gebruiken om een bestandspatroon op te geven dat overeenkomt. Het bestandspatroon kan overeenkomen met nul bestanden, één bestand of een set bestanden die door de taak worden gemaakt.

De eigenschap FilePattern ondersteunt standaard jokertekens van het bestandssysteem, zoals * (voor niet-recursieve overeenkomsten) en ** (voor recursieve overeenkomsten). In het bovenstaande codevoorbeeld wordt bijvoorbeeld het bestandspatroon opgegeven dat niet recursief overeenkomt std*.txt met:

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

Als u één bestand wilt uploaden, geeft u een bestandspatroon op zonder jokertekens. In het bovenstaande codevoorbeeld wordt bijvoorbeeld het bestandspatroon opgegeven dat overeenkomt met output.txt:

filePattern: @"output.txt"

Een uploadvoorwaarde opgeven

De eigenschap OutputFileUploadOptions.UploadCondition staat voorwaardelijke uploading van uitvoerbestanden toe. Een veelvoorkomend scenario is het uploaden van één set bestanden als de taak slaagt en een andere set bestanden als deze mislukt. U kunt bijvoorbeeld alleen uitgebreide logboekbestanden uploaden wanneer de taak mislukt en wordt afgesloten met een niet-nul-afsluitcode. Op dezelfde manier kunt u resultatenbestanden alleen uploaden als de taak slaagt, omdat deze bestanden mogelijk ontbreken of onvolledig zijn als de taak mislukt.

In het bovenstaande codevoorbeeld wordt de eigenschap UploadCondition ingesteld op TaskCompletion. Deze instelling geeft aan dat het bestand moet worden geüpload nadat de taken zijn voltooid, ongeacht de waarde van de afsluitcode.

uploadCondition: OutputFileUploadCondition.TaskCompletion

Zie de enum OutputFileUploadCondition voor andere instellingen.

Disambiguate bestanden met dezelfde naam

De taken in een taak kunnen bestanden met dezelfde naam produceren. En worden bijvoorbeeld stdout.txt stderr.txt gemaakt voor elke taak die in een taak wordt uitgevoerd. Omdat elke taak in een eigen context wordt uitgevoerd, conflicteren deze bestanden niet op het bestandssysteem van het knooppunt. Wanneer u echter bestanden van meerdere taken uploadt naar een gedeelde container, moet u bestanden met dezelfde naam ondubbelzinnig maken.

De OutputFileBlobContainerDestination.Met de padeigenschap geeft u de doel-blob of virtuele map voor uitvoerbestanden op. U kunt de eigenschap Path gebruiken om de blob of virtuele map een naam te geven, zodat uitvoerbestanden met dezelfde naam uniek zijn genoemd in Azure Storage. Het gebruik van de taak-id in het pad is een goede manier om unieke namen te garanderen en eenvoudig bestanden te identificeren.

Als de eigenschap FilePattern is ingesteld op een jokertekenexpressie, worden alle bestanden die overeenkomen met het patroon geüpload naar de virtuele map die is opgegeven door de eigenschap Path . Als de container mycontainerbijvoorbeeld , de taak-id is mytasken het bestandspatroon is ..\std*.txt, zijn de absolute URI's voor de uitvoerbestanden in Azure Storage vergelijkbaar met:

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

Als de eigenschap FilePattern is ingesteld op overeenkomst met één bestandsnaam, wat betekent dat deze geen jokertekens bevat, geeft de waarde van de eigenschap Path de volledig gekwalificeerde blobnaam op. Als u verwacht dat naamgeving conflicteert met één bestand uit meerdere taken, neemt u de naam van de virtuele map op als onderdeel van de bestandsnaam om deze bestanden niet eenduidig te maken. Stel bijvoorbeeld de eigenschap Pad in om de taak-id, het scheidingsteken (meestal een slash) en de bestandsnaam op te nemen:

path: taskId + @"/output.txt"

De absolute URI's voor de uitvoerbestanden voor een reeks taken zijn vergelijkbaar met:

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

Zie De blobs in een container weergeven voor meer informatie over virtuele mappen in Azure Storage.

Veel uitvoerbestanden

Wanneer een taak talloze uitvoerbestanden opgeeft, kunnen er limieten worden opgelegd door de Azure Batch-API. Het is raadzaam om uw taken klein te houden en het aantal uitvoerbestanden laag te houden.

Als u limieten tegenkomt, kunt u overwegen het aantal uitvoerbestanden te verminderen door bestandspatronen te gebruiken of bestandscontainers zoals tar of zip te gebruiken om de uitvoerbestanden samen te voegen. U kunt ook koppelen of andere methoden gebruiken om uitvoergegevens te behouden (zie Taak- en taakuitvoer behouden).

Fouten bij het uploaden van bestanden vaststellen

Als het uploaden van uitvoerbestanden naar Azure Storage mislukt, wordt de taak verplaatst naar de status Voltooid en taskExecutionInformation .De eigenschap FailureInformation is ingesteld. Bekijk de eigenschap FailureInformation om te bepalen welke fout is opgetreden. Hier volgt bijvoorbeeld een fout die optreedt bij het uploaden van bestanden als de container niet kan worden gevonden:

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

Bij het uploaden van bestanden schrijft Batch twee logboekbestanden naar het rekenknooppunt en fileuploadout.txt fileuploaderr.txt. U kunt deze logboekbestanden bekijken voor meer informatie over een specifieke fout. In gevallen waarin het uploaden van het bestand nooit is geprobeerd, bijvoorbeeld omdat de taak zelf niet kon worden uitgevoerd, bestaan deze logboekbestanden niet.

Prestaties van het uploaden van bestanden diagnosticeren

De voortgang van het fileuploadout.txt uploaden van bestanden wordt in logboeken opgeslagen. U kunt dit bestand bekijken voor meer informatie over hoe lang het uploaden van bestanden duurt. Houd er rekening mee dat er veel factoren zijn die bijdragen aan het uploaden van prestaties, waaronder de grootte van het knooppunt, andere activiteiten op het knooppunt op het moment van uploaden, of de doelcontainer zich in dezelfde regio bevindt als de Batch-pool, hoeveel knooppunten tegelijkertijd naar het opslagaccount worden geüpload, enzovoort.

De Batch-service-API gebruiken met de standaard Batch-bestandsconventies

Wanneer u taakuitvoer persistent maakt met de Batch-service-API, kunt u uw doelcontainer en blobs een naam geven zoals u dat wilt. U kunt er ook voor kiezen om ze een naam te geven volgens de standaard batchbestandsconventies. De standaard bestandsconventies bepaalt de namen van de doelcontainer en blob in Azure Storage voor een bepaald uitvoerbestand op basis van de namen van de taak en taak. Als u de standaard bestandsconventies gebruikt voor het benoemen van uitvoerbestanden, zijn uw uitvoerbestanden beschikbaar voor weergave in Azure Portal.

Als u in C# ontwikkelt, kunt u de methoden gebruiken die zijn ingebouwd in de Batch File Conventions-bibliotheek voor .NET. Met deze bibliotheek worden de juiste containers en blobpaden voor u gemaakt. U kunt bijvoorbeeld de API aanroepen om de juiste naam voor de container op te halen, op basis van de taaknaam:

string containerName = job.OutputStorageContainerName();

U kunt de methode CloudJobExtensions.GetOutputStorageContainerUrl gebruiken om een SAS-URL (Shared Access Signature) te retourneren die wordt gebruikt om naar de container te schrijven. U kunt deze SAS vervolgens doorgeven aan de constructor OutputFileBlobContainerDestination .

Als u in een andere taal dan C# ontwikkelt, moet u de standaard bestandsconventies zelf implementeren.

Voorbeeld van code

Het persistOutputs-voorbeeldproject is een van de Azure Batch-codevoorbeelden op GitHub. Deze Visual Studio-oplossing laat zien hoe u de Batch-clientbibliotheek voor .NET gebruikt om taakuitvoer naar duurzame opslag te behouden. Voer de volgende stappen uit om het voorbeeld uit te voeren:

  1. Open het project in Visual Studio 2019.
  2. Voeg de referenties van uw Batch- en Opslagaccount toe aan Account Instellingen.settings in het project Microsoft.Azure.Batch.Samples.Common.
  3. Bouw de oplossing (maar voer deze niet uit). Herstel nu alle NuGet-pakketten als hierom wordt gevraagd.
  4. Gebruik Azure Portal om een toepassingspakket te uploaden voor PersistOutputsTask. Neem de PersistOutputsTask.exe en de afhankelijke assembly's op in het .zip-pakket, stel de toepassings-id in op PersistentOutputsTask en de versie van het toepassingspakket op 1.0.
  5. Start (voer) het project PersistOutputs uit .
  6. Wanneer u wordt gevraagd om de persistentietechnologie te kiezen die moet worden gebruikt voor het uitvoeren van het voorbeeld, voert u 2 in om het voorbeeld uit te voeren met behulp van de Batch-service-API om taakuitvoer te behouden.
  7. Voer indien gewenst het voorbeeld opnieuw uit, voer 3 in om uitvoer te behouden met de Batch-service-API, en geef ook de doelcontainer en het blobpad een naam op volgens de standaard bestandsconventies.

Volgende stappen