Introduzione all'SDK di Batch per Node.jsGet started with Batch SDK for Node.js

Questo articolo illustra i concetti di base relativi alla compilazione di un client Batch in Node.js con l'SDK di Azure Batch per Node.js.Learn the basics of building a Batch client in Node.js using Azure Batch Node.js SDK. Verrà adottato un approccio graduale che prevede la definizione di uno scenario per un'applicazione batch e quindi la relativa configurazione con un client Node.js.We take a step by step approach of understanding a scenario for a batch application and then setting it up using a Node.js client.

PrerequisitiPrerequisites

Questo articolo presuppone che l'utente sappia usare Node.js e abbia familiarità con Linux.This article assumes that you have a working knowledge of Node.js and familiarity with Linux. Presuppone anche che abbia un account Azure configurato con i diritti di accesso necessari per creare servizi Batch e Archiviazione.It also assumes that you have an Azure account setup with access rights to create Batch and Storage services.

Prima di affrontare i passaggi descritti in questo articolo, è consigliabile vedere la panoramica tecnica di Azure Batch.We recommend reading Azure Batch Technical Overview before you go through the steps outlined this article.

Scenario dell'esercitazioneThe tutorial scenario

In questo scenario di flusso di lavoro batch,Let us understand the batch workflow scenario. un semplice script scritto in Python scarica tutti i file CSV da un contenitore di archiviazione BLOB di Azure e li converte in JSON.We have a simple script written in Python that downloads all csv files from an Azure Blob storage container and converts them to JSON. Per elaborare in parallelo più contenitori dell'account di archiviazione, è possibile distribuire lo script come processo di Azure Batch.To process multiple storage account containers in parallel, we can deploy the script as an Azure Batch job.

Architettura di Azure BatchAzure Batch Architecture

Il diagramma seguente illustra come è possibile ridimensionare lo script Python usando Azure Batch e un client Node.js.The following diagram depicts how we can scale the Python script using Azure Batch and a Node.js client.

Scenario di Azure Batch

Il client Node.js distribuisce un processo batch con un'attività di preparazione (illustrata in dettaglio più avanti) e un set di attività in base al numero di contenitori nell'account di archiviazione.The node.js client deploys a batch job with a preparation task (explained in detail later) and a set of tasks depending on the number of containers in the storage account. È possibile scaricare gli script dal repository GitHub.You can download the scripts from the github repository.

Suggerimento

Il client Node.js del collegamento riportato non contiene codice specifico da distribuire come app per le funzioni di Azure.The Node.js client in the link specified does not contain specific code to be deployed as an Azure function app. Per istruzioni per crearne una, vedere i collegamenti seguenti.You can refer to the following links for instructions to create one.

Compilare l'applicazione.Build the application

Verrà ora illustrato in modo dettagliato il processo per la compilazione del client Node.js.Now, let us follow the process step by step into building the Node.js client:

Passaggio 1: Installare l'SDK di Azure BatchStep 1: Install Azure Batch SDK

È possibile installare l'SDK di Azure Batch per Node.js usando il comando npm install.You can install Azure Batch SDK for Node.js using the npm install command.

npm install azure-batch

Questo comando installa l'ultima versione dell'SDK azure-batch per Node.This command installs the latest version of azure-batch node SDK.

Suggerimento

In un'app per le funzioni di Azure, è possibile passare alla "console Kudu" nella scheda Impostazioni di Funzioni di Azure per eseguire i comandi npm install,In an Azure Function app, you can go to "Kudu Console" in the Azure function's Settings tab to run the npm install commands. in questo caso per installare l'SDK di Azure Batch per Node.js.In this case to install Azure Batch SDK for Node.js.

Passaggio 2: Creare un account Azure BatchStep 2: Create an Azure Batch account

È possibile creare l'account dal portale di Azure o dalla riga di comando (Powershell /interfaccia della riga di comando di Azure).You can create it from the Azure portal or from command line (Powershell /Azure cli).

Di seguito sono riportati i comandi per creare un account tramite l'interfaccia della riga di comando di Azure.Following are the commands to create one through Azure CLI.

Creare un gruppo di risorse. Ignorare questo passaggio se è già disponibile un gruppo di risorse in cui creare l'account Batch.Create a Resource Group, skip this step if you already have one where you want to create the Batch Account:

az group create -n "<resource-group-name>" -l "<location>"

Creare quindi un account Azure Batch.Next, create an Azure Batch account.

az batch account create -l "<location>" -g "<resource-group-name>" -n "<batch-account-name>"

Ogni account Batch ha chiavi di accesso corrispondenti,Each Batch account has its corresponding access keys. necessarie per creare altre risorse nell'account Azure Batch.These keys are needed to create further resources in Azure batch account. Nell'ambiente di produzione è consigliabile usare Azure Key Vault per archiviare tali chiavi.A good practice for production environment is to use Azure Key Vault to store these keys. È quindi possibile creare un'entità servizio per l'applicazione.You can then create a Service principal for the application. Con questa entità servizio, l'applicazione può creare un token OAuth per accedere alle chiavi dall'insieme di credenziali delle chiavi.Using this service principal the application can create an OAuth token to access keys from the key vault.

az batch account keys list -g "<resource-group-name>" -n "<batch-account-name>"

Copiare e archiviare la chiave da usare nei passaggi successivi.Copy and store the key to be used in the subsequent steps.

Passaggio 3: Creare un client del servizio Azure BatchStep 3: Create an Azure Batch service client

Il frammento di codice seguente importa il modulo Node.js azure-batch e quindi crea un client del servizio Batch.Following code snippet first imports the azure-batch Node.js module and then creates a Batch Service client. È necessario prima di tutto creare un oggetto SharedKeyCredentials con la chiave dell'account Batch copiata nel passaggio precedente.You need to first create a SharedKeyCredentials object with the Batch account key copied from the previous step.

// Initializing Azure Batch variables

var batch = require('azure-batch');

var accountName = '<azure-batch-account-name>';

var accountKey = '<account-key-downloaded>';

var accountUrl = '<account-url>'

// Create Batch credentials object using account name and account key

var credentials = new batch.SharedKeyCredentials(accountName,accountKey);

// Create Batch service client

var batch_client = new batch.ServiceClient(credentials,accountUrl);

L'URI di Azure Batch è riportato nella scheda Panoramica del portale di Azure,The Azure Batch URI can be found in the Overview tab of the Azure portal. nel formato seguente:It is of the format:

https://accountname.location.batch.azure.com

Fare riferimento allo screenshot:Refer to the screenshot:

URI di Azure Batch

Passaggio 4: Creare un pool di Azure BatchStep 4: Create an Azure Batch pool

Un pool di Azure Batch è costituito da più VM, dette anche nodi Batch.An Azure Batch pool consists of multiple VMs (also known as Batch Nodes). Il servizio Azure Batch distribuisce le attività in questi nodi e li gestisce.Azure Batch service deploys the tasks on these nodes and manages them. È possibile definire i parametri di configurazione per il pool.You can define the following configuration parameters for your pool.

  • Tipo di immagine di macchina virtualeType of Virtual Machine image
  • Dimensioni dei nodi macchina virtualeSize of Virtual Machine nodes
  • Numero di nodi macchina virtualeNumber of Virtual Machine nodes

Suggerimento

Le dimensioni e il numero dei nodi macchina virtuale dipendono in gran parte dal numero di attività che si vuole eseguire in parallelo e anche dall'attività stessa.The size and number of Virtual Machine nodes largely depend on the number of tasks you want to run in parallel and also the task itself. È consigliabile eseguire test per determinare il numero e le dimensioni ideali.We recommend testing to determine the ideal number and size.

Il frammento di codice seguente crea gli oggetti dei parametri di configurazione.The following code snippet creates the configuration parameter objects.

// Creating Image reference configuration for Ubuntu Linux VM
var imgRef = {publisher:"Canonical",offer:"UbuntuServer",sku:"14.04.2-LTS",version:"latest"}

// Creating the VM configuration object with the SKUID
var vmconfig = {imageReference:imgRef,nodeAgentSKUId:"batch.node.ubuntu 14.04"}

// Setting the VM size to Standard F4
var vmSize = "STANDARD_F4"

//Setting number of VMs in the pool to 4
var numVMs = 4

Suggerimento

Per l'elenco delle immagini di VM Linux disponibili per Azure Batch e dei relativi ID SKU, vedere Elenco di immagini di macchine virtuali.For the list of Linux VM images available for Azure Batch and their SKU IDs, see List of virtual machine images.

Dopo aver definito la configurazione del pool, è possibile creare il pool di Azure Batch.Once the pool configuration is defined, you can create the Azure Batch pool. Il comando per il pool di Batch crea i nodi macchina virtuale di Azure e li prepara in modo che siano pronti a ricevere le attività da eseguire.The Batch pool command creates Azure Virtual Machine nodes and prepares them to be ready to receive tasks to execute. Ogni pool dovrà avere un ID univoco a cui fare riferimento nei passaggi successivi.Each pool should have a unique ID for reference in subsequent steps.

Il frammento di codice seguente crea un pool di Azure Batch.The following code snippet creates an Azure Batch pool.

// Create a unique Azure Batch pool ID
var poolid = "pool" + customerDetails.customerid;
var poolConfig = {id:poolid, displayName:poolid,vmSize:vmSize,virtualMachineConfiguration:vmconfig,targetDedicatedComputeNodes:numVms,enableAutoScale:false };
// Creating the Pool for the specific customer
var pool = batch_client.pool.add(poolConfig,function(error,result){
    if(error!=null){console.log(error.response)};
});

È possibile controllare lo stato del pool creato e verificare che sia "active" prima di procedere con l'invio di un processo al pool.You can check the status of the pool created and ensure that the state is in "active" before going ahead with submission of a Job to that pool.

var cloudPool = batch_client.pool.get(poolid,function(error,result,request,response){
        if(error == null)
        {

            if(result.state == "active")
            {
                console.log("Pool is active");
            }
        }
        else
        {
            if(error.statusCode==404)
            {
                console.log("Pool not found yet returned 404...");    

            }
            else
            {
                console.log("Error occurred while retrieving pool data");
            }
        }
        });

Di seguito è riportato un oggetto risultato di esempio restituito dalla funzione pool.get.Following is a sample result object returned by the pool.get function.

{ id: 'processcsv_201721152',
  displayName: 'processcsv_201721152',
  url: 'https://<batch-account-name>.centralus.batch.azure.com/pools/processcsv_201721152',
  eTag: '<eTag>',
  lastModified: 2017-03-27T10:28:02.398Z,
  creationTime: 2017-03-27T10:28:02.398Z,
  state: 'active',
  stateTransitionTime: 2017-03-27T10:28:02.398Z,
  allocationState: 'resizing',
  allocationStateTransitionTime: 2017-03-27T10:28:02.398Z,
  vmSize: 'standard_a1',
  virtualMachineConfiguration:
   { imageReference:
      { publisher: 'Canonical',
        offer: 'UbuntuServer',
        sku: '14.04.2-LTS',
        version: 'latest' },
     nodeAgentSKUId: 'batch.node.ubuntu 14.04' },
  resizeTimeout:
   { [Number: 900000]
     _milliseconds: 900000,
     _days: 0,
     _months: 0,
     _data:
      { milliseconds: 0,
        seconds: 0,
        minutes: 15,
        hours: 0,
        days: 0,
        months: 0,
        years: 0 },
     _locale:
      Locale {
        _calendar: [Object],
        _longDateFormat: [Object],
        _invalidDate: 'Invalid date',
        ordinal: [Function: ordinal],
        _ordinalParse: /\d{1,2}(th|st|nd|rd)/,
        _relativeTime: [Object],
        _months: [Object],
        _monthsShort: [Object],
        _week: [Object],
        _weekdays: [Object],
        _weekdaysMin: [Object],
        _weekdaysShort: [Object],
        _meridiemParse: /[ap]\.?m?\.?/i,
        _abbr: 'en',
        _config: [Object],
        _ordinalParseLenient: /\d{1,2}(th|st|nd|rd)|\d{1,2}/ } },
  currentDedicated: 0,
  targetDedicated: 4,
  enableAutoScale: false,
  enableInterNodeCommunication: false,
  maxTasksPerNode: 1,
  taskSchedulingPolicy: { nodeFillType: 'Spread' } }

Passaggio 5: Inviare un processo di Azure BatchStep 4: Submit an Azure Batch job

Un processo di Azure Batch è un gruppo logico di attività simili.An Azure Batch job is a logical group of similar tasks. In questo scenario, esegue l'elaborazione da CSV a JSON.In our scenario, it is "Process csv to JSON." Ogni attività potrà elaborare i file CSV presenti in ogni contenitore di archiviazione di Azure.Each task here could be processing csv files present in each Azure Storage container.

Queste attività verranno eseguite in parallelo e distribuite in più nodi, orchestrati dal servizio Azure Batch.These tasks would run in parallel and deployed across multiple nodes, orchestrated by the Azure Batch service.

Suggerimento

È possibile usare la proprietà maxTasksPerNode per specificare il numero massimo di attività che è possibile eseguire simultaneamente in un singolo nodo.You can use the maxTasksPerNode property to specify maximum number of tasks that can run concurrently on a single node.

Attività di preparazionePreparation task

I nodi VM creati sono nodi Ubuntu vuoti.The VM nodes created are blank Ubuntu nodes. Spesso è necessario installare un set di programmi come prerequisito.Often, you need to install a set of programs as prerequisites. Per i nodi Linux è in genere possibile usare uno script della shell che installa i prerequisiti prima dell'esecuzione delle attività effettive.Typically, for Linux nodes you can have a shell script that installs the prerequisites before the actual tasks run. Può tuttavia trattarsi di qualsiasi eseguibile programmabile.However it could be any programmable executable. Lo script della shell di questo esempio installa Python-pip e Azure Storage SDK per Python.The shell script in this example installs Python-pip and the Azure Storage SDK for Python.

È possibile caricare lo script in un account di archiviazione di Azure e generare un URI di firma di accesso condiviso per accedere allo script.You can upload the script on an Azure Storage Account and generate a SAS URI to access the script. Questo processo può essere automatizzato con Azure Storage SDK per Node.js.This process can also be automated using the Azure Storage Node.js SDK.

Suggerimento

Un'attività di preparazione per un processo viene eseguita solo sui nodi VM in cui deve essere eseguita l'attività specifica.A preparation task for a job runs only on the VM nodes where the specific task needs to run. Se si vogliono installare i prerequisiti in tutti i nodi indipendentemente dalle attività in essi eseguite, si può usare la proprietà startTask durante l'aggiunta di un pool.If you want prerequisites to be installed on all nodes irrespective of the tasks that run on it, you can use the startTask property while adding a pool. È possibile usare la definizione di attività di preparazione seguente come riferimento.You can use the following preparation task definition for reference.

Un'attività di preparazione viene specificata durante l'invio del processo di Azure Batch.A preparation task is specified during the submission of Azure Batch job. Di seguito sono riportati i parametri di configurazione dell'attività di preparazione.Following are the preparation task configuration parameters:

  • ID: identificatore univoco dell'attività di preparazione.ID: A unique identifier for the preparation task
  • commandLine: riga di comando per eseguire l'eseguibile dell'attività.commandLine: Command line to execute the task executable
  • resourceFiles: matrice di oggetti che specifica i dettagli dei file da scaricare per l'esecuzione dell'attività.resourceFiles: Array of objects that provide details of files needed to be downloaded for this task to run. Di seguito sono riportate le opzioni.Following are its options
    • blobSource: URI di firma di accesso condiviso del fileblobSource: The SAS URI of the file
    • filePath: percorso locale per il download e il salvataggio del filefilePath: Local path to download and save the file
    • fileMode: applicabile solo per nodi Linux, in formato ottale con valore predefinito 0770fileMode: Only applicable for Linux nodes, fileMode is in octal format with a default value of 0770
  • waitForSuccess: se è impostato su true, l'attività non viene eseguita in caso di errori dell'attività di preparazione.waitForSuccess: If set to true, the task does not run on preparation task failures
  • runElevated: impostare su true se sono necessari privilegi elevati per eseguire l'attività.runElevated: Set it to true if elevated privileges are needed to run the task.

Il frammento di codice seguente illustra un esempio di configurazione dello script dell'attività di preparazione:Following code snippet shows the preparation task script configuration sample:

var job_prep_task_config = {id:"installprereq",commandLine:"sudo sh startup_prereq.sh > startup.log",resourceFiles:[{'blobSource':'Blob SAS URI','filePath':'startup_prereq.sh'}],waitForSuccess:true,runElevated:true}

Se per l'esecuzione delle attività non è necessario installare prerequisiti, è possibile ignorare le attività di preparazione.If there are no prerequisites to be installed for your tasks to run, you can skip the preparation tasks. Il codice seguente crea un processo con il nome visualizzato "process csv files".Following code creates a job with display name "process csv files."

// Setting up Batch pool configuration
var pool_config = {poolId:poolid}
// Setting up Job configuration along with preparation task
var jobId = "processcsvjob"
var job_config = {id:jobId,displayName:"process csv files",jobPreparationTask:job_prep_task_config,poolInfo:pool_config}
// Adding Azure batch job to the pool
var job = batch_client.job.add(job_config,function(error,result){
    if(error != null)
    {
        console.log("Error submitting job : " + error.response);
    }});

Passaggio 6: Inviare le attività di Azure Batch per un processoStep 5: Submit Azure Batch tasks for a job

Dopo aver creato il processo per l'elaborazione dei file CSV, si creeranno le attività per tale processo.Now that our process csv job is created, let us create tasks for that job. Supponendo di avere quattro contenitori, è necessario creare quattro attività, una per ogni contenitore.Assuming we have four containers, we have to create four tasks, one for each container.

Lo script Python accetta due parametri.If we look at the Python script, it accepts two parameters:

  • container_name: contenitore di archiviazione da cui scaricare i filecontainer name: The Storage container to download files from
  • pattern: parametro facoltativo del modello di nome filepattern: An optional parameter of file name pattern

Supponendo di avere i quattro contenitori "con1", "con2", "con3" e "con4", il codice seguente illustra l'invio delle attività al processo "process csv" di Azure Batch creato in precedenza.Assuming we have four containers "con1", "con2", "con3","con4" following code shows submitting for tasks to the Azure batch job "process csv" we created earlier.

// storing container names in an array
var container_list = ["con1","con2","con3","con4"]
    container_list.forEach(function(val,index){           

           var container_name = val;
           var taskID = container_name + "_process";
           var task_config = {id:taskID,displayName:'process csv in ' + container_name,commandLine:'python processcsv.py --container ' + container_name,resourceFiles:[{'blobSource':'<blob SAS URI>','filePath':'processcsv.py'}]}
           var task = batch_client.task.add(poolid,task_config,function(error,result){
                if(error != null)
                {
                    console.log(error.response);     
                }
                else
                {
                    console.log("Task for container : " + container_name + "submitted successfully");
                }



           });

    });

Il codice aggiunge più attività al pool.The code adds multiple tasks to the pool. Ogni attività viene eseguita in un nodo del pool di VM creato.And each of the tasks is executed on a node in the pool of VMs created. Se il numero di attività è superiore al numero di VM in un pool o alla proprietà maxTasksPerNode, le attività restano in attesa finché non diventa disponibile un nodo.If the number of tasks exceeds the number of VMs in a pool or the maxTasksPerNode property, the tasks wait until a node is made available. Questa orchestrazione viene gestita automaticamente da Azure Batch.This orchestration is handled by Azure Batch automatically.

Il portale offre visualizzazioni dettagliate delle attività e degli stati del processo.The portal has detailed views on the tasks and job statuses. È anche possibile usare le funzioni list e get in Azure SDK per Node.You can also use the list and get functions in the Azure Node SDK. Per informazioni dettagliate, vedere la documentazione.Details are provided in the documentation link.

Passaggi successiviNext steps