Rendere persistenti i dati delle attività in Archiviazione di Azure con l'API del servizio BatchPersist task data to Azure Storage with the Batch service API

Un'attività in esecuzione in Azure Batch può produrre dati di output quando viene eseguita.A task running in Azure Batch may produce output data when it runs. I dati di output delle attività spesso devono essere archiviati per consentirne il recupero da parte di altre attività del processo, dell'applicazione client che ha eseguito il processo o di entrambe.Task output data often needs to be stored for retrieval by other tasks in the job, the client application that executed the job, or both. Le attività scrivono i dati di output nel file system di un nodo di calcolo di Batch, ma tutti i dati presenti nel nodo vanno persi quando ne viene ricreata l'immagine o quando il nodo lascia il pool.Tasks write output data to the file system of a Batch compute node, but all data on the node is lost when it is reimaged or when the node leaves the pool. Le attività possono anche avere un periodo di memorizzazione dei file, dopo il quale i file creati dall'attività vengono eliminati.Tasks may also have a file retention period, after which files created by the task are deleted. Per questi motivi, è importante salvare in modo permanente l'output delle attività che sarà necessario in seguito in un archivio dati, ad esempio Archiviazione di Azure.For these reasons, it's important to persist task output that you'll need later to a data store such as Azure Storage.

A partire dalla versione 2017-05-01, l'API del servizio Batch supporta l'archiviazione permanente dei dati di output in Archiviazione di Azure per le attività e le attività di gestione processo eseguite sui pool con la configurazione della macchina virtuale.Starting with version 2017-05-01, the Batch service API supports persisting output data to Azure Storage for tasks and job manager tasks that run on pools with the virtual machine configuration. Quando si aggiunge un'attività, è possibile specificare un contenitore in Archiviazione di Azure come destinazione per l'output dell'attività.When you add a task, you can specify a container in Azure Storage as the destination for the task's output. Il servizio Batch scrive quindi i dati di output in tale contenitore al completamento dell'attività.The Batch service then writes any output data to that container when the task is complete.

Un vantaggio dell'uso dell'API del servizio Batch per rendere persistente l'output dell'attività è il fatto di non avere la necessità di l'applicazione eseguita dall'attività.An advantage to using the Batch service API to persist task output is that you do not need to modify the application that the task is running. Con poche semplici modifiche dell'applicazione client, è invece possibile rendere persistente l'output dell'attività dall'interno del codice che crea l'attività.Instead, with a few simple modifications to your client application, you can persist the task's output from within the code that creates the task.

Quando è appropriato usare l'API del servizio Batch per rendere persistente l'output delle attività?When do I use the Batch service API to persist task output?

Il servizio Azure Batch offre diversi modi per rendere persistente l'output delle attività.Azure Batch provides more than one way to persist task output. Usare l'API del servizio Batch è un approccio pratico adatto in particolar modo per gli scenari seguenti:Using the Batch service API is a convenient approach that's best suited to these scenarios:

  • Si vuole scrivere codice per rendere persistente l'output dell'attività dall'interno dell'applicazione client, senza modificare l'applicazione eseguita dall'attività.You want to write code to persist task output from within your client application, without modifying the application that your task is running.
  • Si vuole rendere persistente l'output delle attività del servizio Batch e delle attività del gestore di processi create con la configurazione della macchina virtuale.You want to persist output from Batch tasks and job manager tasks in pools created with the virtual machine configuration.
  • Si vuole rendere persistente l'output in un contenitore di Archiviazione di Azure con un nome arbitrario.You want to persist output to an Azure Storage container with an arbitrary name.
  • Si vuole rendere persistente l'output in un contenitore di Archiviazione di Azure denominato in base agli standard di Batch File Conventions.You want to persist output to an Azure Storage container named according to the Batch File Conventions standard.

Se lo scenario è diverso da quelli sopra elencati, potrebbe essere necessario prendere in considerazione un approccio diverso.If your scenario differs from those listed above, you may need to consider a different approach. Ad esempio, l'API del servizio Batch attualmente non supporta flussi dell'output in Archiviazione di Azure durante l'esecuzione dell'attività.For example, the Batch service API does not currently support streaming output to Azure Storage while the task is running. Per questa esigenza, prendere in considerazione l'uso della libreria Batch File Conventions, disponibile per .NET.To stream output, consider using the Batch File Conventions library, available for .NET. Per altri linguaggi, sarà necessario implementare una soluzione personalizzata.For other languages, you'll need to implement your own solution. Per altre informazioni sulle opzioni per rendere persistente l'output delle attività, vedere Rendere persistente l'output di processi e attività.For more information on other options for persisting task output, see Persist job and task output to Azure Storage.

Creare un contenitore in Archiviazione di AzureCreate a container in Azure Storage

Per rendere persistente l'output delle attività in Archiviazione di Azure, è necessario creare un contenitore che funge da destinazione per i file di output.To persist task output to Azure Storage, you'll need to create a container that serves as the destination for your output files. Creare il contenitore prima di eseguire l'attività, preferibilmente prima di inviare il processo.Create the container before you run your task, preferably before you submit your job. Per creare il contenitore, usare la libreria client o l'SDK di Archiviazione di Azure appropriati.To create the container, use the appropriate Azure Storage client library or SDK. Per altre informazioni sulle API di Archiviazione di Azure, vedere la documentazione su Archiviazione di Azure.For more information about Azure Storage APIs, see the Azure Storage documentation.

Se si scrive l'applicazione in C#, ad esempio, usare la libreria client di Archiviazione di Azure per .NET.For example, if you are writing your application in C#, use the Azure Storage client library for .NET. L'esempio seguente mostra come creare un contenitore:The following example shows how to create a container:

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

Ottenere una firma di accesso condiviso per il contenitoreGet a shared access signature for the container

Dopo aver creato il contenitore, è possibile ottenere una firma di accesso condiviso (SAS) con accesso in scrittura al contenitore.After you create the container, get a shared access signature (SAS) with write access to the container. Una firma di accesso condiviso consente l'accesso delegato al contenitore.A SAS provides delegated access to the container. La firma di accesso condiviso concede l'accesso con un set specificato di autorizzazioni e per un intervallo di tempo specificato.The SAS grants access with a specified set of permissions and over a specified time interval. Il servizio Batch deve disporre di una firma di accesso condiviso con autorizzazioni di scrittura per scrivere l'output delle attività del contenitore.The Batch service needs a SAS with write permissions to write task output to the container. Per altre informazioni sulle firme di accesso condiviso, vedere Uso delle firme di (accesso condiviso) in Archiviazione di Azure.For more information about SAS, see Using shared access signatures (SAS) in Azure Storage.

Quando si ottiene una firma di accesso condiviso tramite le API di Archiviazione di Azure, l'API restituisce una stringa di token di firma di accesso condiviso.When you get a SAS using the Azure Storage APIs, the API returns a SAS token string. Questa stringa di token include tutti i parametri della firma di accesso condiviso, incluse le autorizzazioni e l'intervallo di validità della firma di accesso condiviso.This token string includes all parameters of the SAS, including the permissions and the interval over which the SAS is valid. Per usare la firma di accesso condiviso per accedere a un contenitore in Archiviazione di Azure, è necessario aggiungere la stringa di token di firma di accesso all'URI della risorsa.To use the SAS to access a container in Azure Storage, you need to append the SAS token string to the resource URI. L'URI della risorsa, insieme al token della firma di accesso condiviso aggiunto, consente l'accesso autenticato ad Archiviazione di Azure.The resource URI, together with the appended SAS token, provides authenticated access to Azure Storage.

L'esempio seguente mostra come ottenere una stringa di token di firma di accesso condiviso in sola scrittura per il contenitore, quindi aggiunge la firma di accesso condiviso all'URI del contenitore:The following example shows how to get a write-only SAS token string for the container, then appends the SAS to the container URI:

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

string containerSasUrl = container.Uri.AbsoluteUri + containerSasToken; 

Specificare i file di output per l'output dell'attivitàSpecify output files for task output

Per specificare i file di output per un'attività, creare una raccolta di oggetti OutputFile e assegnarla alla proprietà CloudTask.OutputFiles quando si crea l'attività.To specify output files for a task, create a collection of OutputFile objects and assign it to the CloudTask.OutputFiles property when you create the task.

L'esempio di codice .NET seguente crea un'attività che scrive numeri casuali in un file denominato output.txt.The following .NET code example creates a task that writes random numbers to a file named output.txt. Nell'esempio viene creato un file di output per output.txt da scrivere nel contenitore.The example creates an output file for output.txt to be written to the container. L'esempio crea anche i file di output per gli eventuali file di log corrispondenti al modello di file std*.txt (ad esempio, stdout.txt e stderr.txt).The example also creates output files for any log files that match the file pattern std*.txt (e.g., stdout.txt and stderr.txt). L'URL del contenitore richiede la firma di accesso condiviso creata in precedenza per il contenitore.The container URL requires the SAS that was created previously for the container. Il servizio Batch usa la firma di accesso condiviso per autenticare l'accesso al contenitore:The Batch service uses the SAS to authenticate access to the container:

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

Specificare un modello di file per la corrispondenzaSpecify a file pattern for matching

Quando si specifica un file di output, è possibile usare la proprietà OutputFile.FilePattern per specificare un modello di file per la corrispondenza.When you specify an output file, you can use the OutputFile.FilePattern property to specify a file pattern for matching. Il modello di file potrebbe corrispondere a zero file, un singolo file o un set di file creati dall'attività.The file pattern may match zero files, a single file, or a set of files that are created by the task.

La proprietà FilePattern supporta i caratteri jolly standard del file system, ad esempio * (per corrispondenze non ricorsive) e ** (per corrispondenze ricorsive).The FilePattern property supports standard filesystem wildcards such as * (for non-recursive matches) and ** (for recursive matches). Ad esempio, l'esempio di codice precedente specifica il modello di file da usare per trovare corrispondenze per std*.txt in modo non ricorsivo:For example, the code sample above specifies the file pattern to match std*.txt non-recursively:

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

Per caricare un singolo file, specificare un modello di file senza caratteri jolly.To upload a single file, specify a file pattern with no wildcards. Ad esempio, l'esempio di codice precedente specifica il modello di file da usare per trovare corrispondenze per output.txt:For example, the code sample above specifies the file pattern to match output.txt:

filePattern: @"output.txt"

Specificare una condizione di caricamentoSpecify an upload condition

La proprietà OutputFileUploadOptions.UploadCondition consente il caricamento condizionale dei file di output.The OutputFileUploadOptions.UploadCondition property permits conditional uploading of output files. Uno scenario comune consiste nel caricare un set di file se l'attività ha esito positivo e un set di file diverso, in caso di errore.A common scenario is to upload one set of files if the task succeeds, and a different set of files if it fails. Ad esempio, può essere necessario caricare i file di log dettagliati solo quando l'attività ha esito negativo e viene terminata con un codice di uscita diverso da zero.For example, you may want to upload verbose log files only when the task fails and exits with a nonzero exit code. Analogamente, può essere utile caricare il file dei risultati solo se l'attività ha esito positivo, perché tali file potrebbero essere mancanti o incompleti se l'attività non riesce.Similarly, you may want to upload result files only if the task succeeds, as those files may be missing or incomplete if the task fails.

L'esempio di codice precedente imposta la proprietà UploadCondition su TaskCompletion.The code sample above sets the UploadCondition property to TaskCompletion. Questa impostazione specifica che il file deve essere caricato dopo aver completato le attività, indipendentemente dal valore del codice di uscita.This setting specifies that the file is to be uploaded after the tasks completes, regardless of the value of the exit code.

uploadCondition: OutputFileUploadCondition.TaskCompletion

Per altre impostazioni, vedere l'enumerazione OutputFileUploadCondition.For other settings, see the OutputFileUploadCondition enum.

Eliminare le ambiguità causate da file con lo stesso nomeDisambiguate files with the same name

Le attività in un processo possono produrre file con lo stesso nome.The tasks in a job may produce files that have the same name. Ad esempio, i file stdout.txt e stderr.txt vengono creati per ogni attività eseguita in un processo.For example, stdout.txt and stderr.txt are created for every task that runs in a job. Dato che ogni attività viene eseguita in un contesto specifico, questi file non sono in conflitto nel file system del nodo.Because each task runs in its own context, these files don't conflict on the node's file system. Quando si caricano file da più attività in un contenitore condiviso, tuttavia, è necessario evitare ambiguità tra i file con lo stesso nome.However, when you upload files from multiple tasks to a shared container, you'll need to disambiguate files with the same name.

La proprietà OutputFileBlobContainerDestination.Path specifica il BLOB o la directory virtuale di destinazione per i file di output.The OutputFileBlobContainerDestination.Path property specifies the destination blob or virtual directory for output files. È possibile usare la proprietà Path come nome del BLOB o della directory virtuale, in modo che i file di output con lo stesso nome abbiano un nome univoco in Archiviazione di Azure.You can use the Path property to name the blob or virtual directory in such a way that output files with the same name are uniquely named in Azure Storage. L'uso dell'ID attività nel percorso è un buon metodo per garantire nomi univoci e identificare facilmente i file.Using the task ID in the path is a good way to ensure unique names and easily identify files.

Se la proprietà FilePattern è impostata su un'espressione con caratteri jolly, tutti i file che corrispondono al modello vengono caricati nella directory virtuale specificata dalla proprietà Path.If the FilePattern property is set to a wildcard expression, then all files that match the pattern are uploaded to the virtual directory specified by the Path property. Ad esempio, se il contenitore è mycontainer, l'ID attività è mytask e il modello di file è ..\std*.txt, l'URI assoluto per i file di output in Archiviazione di Azure sarà simile a:For example, if the container is mycontainer, the task ID is mytask, and the file pattern is ..\std*.txt, then the absolute URIs to the output files in Azure Storage will be similar to:

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

Se la proprietà FilePattern è impostata su a un singolo nome di file, ovvero non contiene caratteri jolly, il valore della proprietà Path specifica il nome completo del BLOB.If the FilePattern property is set to match a single file name, meaning it does not contain any wildcard characters, then the value of the Path property specifies the fully qualified blob name. Se si prevedono conflitti di nome per un singolo file da più attività, includere il nome della directory virtuale come parte del nome del file per evitare ambiguità.If you anticipate naming conflicts with a single file from multiple tasks, then include the name of the virtual directory as part of the file name to disambiguate those files. Ad esempio, impostare la proprietà Path in modo da includere l'ID attività, il carattere di delimitazione (in genere una barra rovesciata) e il nome del file:For example, set the Path property to include the task ID, the delimiter character (typically a forward slash), and the file name:

path: taskId + @"/output.txt"

L'URI assoluto dei file di output per un set di attività sarà simile a:The absolute URIs to the output files for a set of tasks will be similar to:

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

Per altre informazioni sulle directory virtuali in Archiviazione di Azure, vedere Elencare i BLOB in un contenitore.For more information about virtual directories in Azure Storage, see List the blobs in a container.

Diagnosticare gli errori di caricamento fileDiagnose file upload errors

Se si verifica un errore di caricamento dei file di output in Archiviazione di Azure, l'attività passa allo stato Completato e viene impostata la proprietà TaskExecutionInformation.FailureInformation.If uploading output files to Azure Storage fails, then the task moves to the Completed state and the TaskExecutionInformation.FailureInformation property is set. Esaminare la proprietà FailureInformation per determinare l'errore che si è verificato.Examine the FailureInformation property to determine what error occurred. Quello che segue è un esempio di errore che si verifica al momento del caricamento di file se non è possibile trovare il contenitore:For example, here is an error that occurs on file upload if the container cannot be found:

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

Per ogni caricamento di file, il servizio Batch scrive due file di log nel nodo di calcolo, fileuploadout.txt e fileuploaderr.txt.On every file upload, Batch writes two log files to the compute node, fileuploadout.txt and fileuploaderr.txt. È possibile esaminare questi file di log per ottenere ulteriori informazioni su un errore specifico.You can examine these log files to learn more about a specific failure. Nei casi in cui il caricamento del file non è mai stato tentato, ad esempio perché non può essere eseguita l'attività stessa, questi file di log non esisteranno.In cases where the file upload was never attempted, for example because the task itself couldn’t run, then these log files will not exist.

Diagnosticare le prestazioni di caricamento fileDiagnose file upload performance

Lo stato di caricamento viene registrato nel file fileuploadout.txt.The fileuploadout.txt file logs upload progress. È possibile esaminare questo file per ottenere ulteriori informazioni su quanto tempo richiede il caricamento del file.You can examine this file to learn more about how long your file uploads are taking. Tenere presente che esistono molti fattori che possono influire sulle prestazioni del caricamento, tra cui la dimensione del nodo, altre attività in esecuzione sul nodo durante il caricamento, il fatto che il contenitore di destinazione si trovi nella stessa area del pool di Batch, il numero di nodi in caricamento nell'account di archiviazione nello stesso momento e così via.Keep in mind that there are many contributing factors to upload performance, including the size of the node, other activity on the node at the time of the upload, whether the target container is in the same region as the Batch pool, how many nodes are uploading to the storage account at the same time, and so on.

Usare l'API del servizio Batch con lo standard Batch File ConventionsUse the Batch service API with the Batch File Conventions standard

Quando si rende persistente l'output con l'API del servizio Batch, è possibile assegnare il nome preferito al contenitore di destinazione e ai BLOB.When you persist task output with the Batch service API, you can name your destination container and blobs however you like. Si può anche scegliere il nome in base allo standard Batch File Conventions.You can also choose to name them according to the Batch File Conventions standard. Lo standard File Conventions determina i nomi del contenitore e del BLOB di destinazione in Archiviazione di Azure per un file di output specificato in base ai nomi del processo e dell'attività.The File Conventions standard determines the names of the destination container and blob in Azure Storage for a given output file based on the names of the job and task. Se si usa lo standard File Conventions per la denominazione dei file di output, i file di output sono disponibili per la visualizzazione nel portale di Azure.If you do use the File Conventions standard for naming output files, then your output files are available for viewing in the Azure portal.

Se si sviluppa in C#, è possibile usare i metodi inclusi nella libreria Batch File Conventions per .NET.If you are developing in C#, you can use the methods built into the Batch File Conventions library for .NET. Questa libreria crea automaticamente i percorsi di BLOB e contenitori con nomi appropriati.This library creates the properly named containers and blob paths for you. Ad esempio, è possibile chiamare l'API per ottenere il nome corretto per il contenitore, in base al nome del processo:For example, you can call the API to get the correct name for the container, based on the job name:

string containerName = job.OutputStorageContainerName();

È possibile usare il metodo CloudJobExtensions.GetOutputStorageContainerUrl per restituire un URL di firma di accesso condiviso usato per scrivere nel contenitore.You can use the CloudJobExtensions.GetOutputStorageContainerUrl method to return a shared access signature (SAS) URL that is used to write to the container. È quindi possibile passare questa firma di accesso condiviso al costruttore OutputFileBlobContainerDestination.You can then pass this SAS to the OutputFileBlobContainerDestination constructor.

Se si sviluppa in un linguaggio diverso da C#, sarà necessario implementare manualmente lo standard File Conventions.If you are developing in a language other than C#, you will need to implement the File Conventions standard yourself.

Esempio di codiceCode sample

Il progetto di esempio PersistOutputs è uno degli esempi di codice di Azure Batch disponibili in GitHub.The PersistOutputs sample project is one of the Azure Batch code samples on GitHub. Questa soluzione di Visual Studio descrive come usare la libreria client Batch per .NET per rendere persistente l'output dell'attività in una risorsa di archiviazione permanente.This Visual Studio solution demonstrates how to use the Batch client library for .NET to persist task output to durable storage. Per eseguire l'esempio, seguire questa procedura:To run the sample, follow these steps:

  1. Aprire il progetto in Visual Studio 2015 o in una versione più recente.Open the project in Visual Studio 2015 or newer.
  2. Aggiungere le credenziali dell'account di archiviazione e Batch a AccountSettings.settings nel progetto Microsoft.Azure.Batch.Samples.Common.Add your Batch and Storage account credentials to AccountSettings.settings in the Microsoft.Azure.Batch.Samples.Common project.
  3. Compilare , ma non eseguire, la soluzione.Build (but do not run) the solution. Se richiesto, ripristinare tutti i pacchetti NuGet.Restore any NuGet packages if prompted.
  4. Usare il portale di Azure per caricare un pacchetto dell'applicazione per PersistOutputsTask.Use the Azure portal to upload an application package for PersistOutputsTask. Includere PersistOutputsTask.exe e relativi assembly dipendenti nel pacchetto ZIP, impostare l'ID applicazione su "PersistOutputsTask" e la versione del pacchetto dell'applicazione su "1.0".Include the PersistOutputsTask.exe and its dependent assemblies in the .zip package, set the application ID to "PersistOutputsTask", and the application package version to "1.0".
  5. Avviare, ovvero eseguire, il progetto PersistOutputs.Start (run) the PersistOutputs project.
  6. Quando viene richiesto di scegliere la tecnologia di persistenza da usare per l'esecuzione dell'esempio, immettere 2 per eseguire l'esempio con l'API del servizio Batch per rendere persistente l'output dell'attività.When prompted to choose the persistence technology to use for running the sample, enter 2 to run the sample using the Batch service API to persist task output.
  7. Se si desidera, eseguire nuovamente l'esempio, immettere 3 per rendere persistente l'output con l'API del servizio Batch e definire anche i nomi per il percorso del BLOB e del contenitore di destinazione in base allo standard File Conventions.If desired, run the sample again, entering 3 to persist output with the Batch service API, and also to name the destination container and blob path according to the File Conventions standard.

Passaggi successiviNext steps