Introduzione a Batch SDK per JavaScript

  • Articolo

Informazioni di base sulla compilazione di un client Batch in JavaScript usando Azure Batch JavaScript SDK. Si esegue un approccio dettagliato per comprendere uno scenario per un'applicazione batch e quindi configurarlo usando JavaScript.

Prerequisiti

Questo articolo presuppone che si abbia una conoscenza funzionante di JavaScript e familiarità con Linux. Presuppone anche che abbia un account Azure configurato con i diritti di accesso necessari per creare servizi Batch e Archiviazione.

Prima di affrontare i passaggi descritti in questo articolo, è consigliabile vedere la panoramica tecnica di Azure Batch.

Informazioni sullo scenario

Questo semplice script scritto in Python scarica tutti i file CSV da un contenitore di archiviazione BLOB di Azure e li converte in JSON. Per elaborare in parallelo più contenitori dell'account di archiviazione, è possibile distribuire lo script come processo di Azure Batch.

Architettura di Azure Batch

Il diagramma seguente illustra come ridimensionare lo script Python usando Azure Batch e un client.

Diagramma che illustra l'architettura dello scenario.

L'esempio JavaScript distribuisce un processo batch con un'attività di preparazione (illustrata in dettaglio più avanti) e un set di attività a seconda del numero di contenitori nell'account di archiviazione. È possibile scaricare gli script dal repository GitHub.

Suggerimento

L'esempio JavaScript nel collegamento specificato non contiene codice specifico da distribuire come app per le funzioni di Azure. Per istruzioni per crearne una, vedere i collegamenti seguenti.

Compilare l'applicazione

A questo punto, seguire il processo seguendo il passaggio per creare il client JavaScript:

Passaggio 1: installare l'SDK di Azure Batch

È possibile installare Azure Batch SDK per JavaScript usando il comando npm install.

npm install @azure/batch

Questo comando installa la versione più recente di azure-batch JavaScript 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 questo caso per installare Azure Batch SDK per JavaScript.

Passaggio 2: Creare un account Azure Batch

È possibile crearlo nel portale di Azure o dalla riga di comando (Powershell /interfaccia della riga di comando di Azure).

Di seguito sono riportati i comandi per creare un account tramite l'interfaccia della riga di comando di Azure.

Creare un gruppo di risorse. Ignorare questo passaggio se è già disponibile un gruppo di risorse in cui creare l'account Batch.

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

Creare quindi un account Azure Batch.

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

Ogni account Batch ha chiavi di accesso corrispondenti, necessarie per creare altre risorse nell'account Azure Batch. Nell'ambiente di produzione è consigliabile usare Azure Key Vault per archiviare tali chiavi. È quindi possibile creare un'entità servizio per l'applicazione. Con questa entità servizio, l'applicazione può creare un token OAuth per accedere alle chiavi dall'insieme di credenziali delle chiavi.

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

Copiare e archiviare la chiave da usare nei passaggi successivi.

Passaggio 3: creare un client del servizio Azure Batch

Il frammento di codice seguente importa prima il modulo JavaScript azure-batch e quindi crea un client del servizio Batch. È necessario prima di tutto creare un oggetto SharedKeyCredentials con la chiave dell'account Batch copiata nel passaggio precedente.

// Initializing Azure Batch variables

import { BatchServiceClient, BatchSharedKeyCredentials } from "@azure/batch";

// Replace values below with Batch Account details
const batchAccountName = '<batch-account-name>';
const batchAccountKey = '<batch-account-key>';
const batchEndpoint = '<batch-account-url>';

const credentials = new BatchSharedKeyCredentials(batchAccountName, batchAccountKey);
const batchClient = new BatchServiceClient(credentials, batchEndpoint);

L'URI di Azure Batch è riportato nella scheda Panoramica del portale di Azure, nel formato seguente:

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

Fare riferimento allo screenshot:

URI di Azure Batch

Passaggio 4: Creare un pool di Azure Batch

Un pool di Azure Batch è costituito da più VM, dette anche nodi Batch. Il servizio Azure Batch distribuisce le attività in questi nodi e li gestisce. È possibile definire i parametri di configurazione per il pool.

  • Tipo di immagine di macchina virtuale
  • Dimensioni dei nodi macchina virtuale
  • Numero di nodi macchina virtuale

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. È consigliabile eseguire test per determinare il numero e le dimensioni ideali.

Il frammento di codice seguente crea gli oggetti dei parametri di configurazione.

// Creating Image reference configuration for Ubuntu Linux VM
const imgRef = {
    publisher: "Canonical",
    offer: "UbuntuServer",
    sku: "20.04-LTS",
    version: "latest"
}
// Creating the VM configuration object with the SKUID
const vmConfig = {
    imageReference: imgRef,
    nodeAgentSKUId: "batch.node.ubuntu 20.04"
};
// Number of VMs to create in a pool
const numVms = 4;

// Setting the VM size
const vmSize = "STANDARD_D1_V2";

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.

Dopo aver definito la configurazione del pool, è possibile creare il pool di Azure Batch. 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. Ogni pool dovrà avere un ID univoco a cui fare riferimento nei passaggi successivi.

Il frammento di codice seguente crea un pool di Azure Batch.

// Create a unique Azure Batch pool ID
const now = new Date();
const poolId = `processcsv_${now.getFullYear()}${now.getMonth()}${now.getDay()}${now.getHours()}${now.getSeconds()}`;

const poolConfig = {
    id: poolId,
    displayName: "Processing csv files",
    vmSize: vmSize,
    virtualMachineConfiguration: vmConfig,
    targetDedicatedNodes: numVms,
    enableAutoScale: false
};

// Creating the Pool
var pool = batchClient.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.

var cloudPool = batchClient.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.

{
  id: 'processcsv_2022002321',
  displayName: 'Processing csv files',
  url: 'https://<batch-account-name>.westus.batch.azure.com/pools/processcsv_2022002321',
  eTag: '0x8D9D4088BC56FA1',
  lastModified: 2022-01-10T07:12:21.943Z,
  creationTime: 2022-01-10T07:12:21.943Z,
  state: 'active',
  stateTransitionTime: 2022-01-10T07:12:21.943Z,
  allocationState: 'steady',
  allocationStateTransitionTime: 2022-01-10T07:13:35.103Z,
  vmSize: 'standard_d1_v2',
  virtualMachineConfiguration: {
    imageReference: {
      publisher: 'Canonical',
      offer: 'UbuntuServer',
      sku: '20.04-LTS',
      version: 'latest'
    },
    nodeAgentSKUId: 'batch.node.ubuntu 20.04'
  },
  resizeTimeout: 'PT15M',
  currentDedicatedNodes: 4,
  currentLowPriorityNodes: 0,
  targetDedicatedNodes: 4,
  targetLowPriorityNodes: 0,
  enableAutoScale: false,
  enableInterNodeCommunication: false,
  taskSlotsPerNode: 1,
  taskSchedulingPolicy: { nodeFillType: 'Spread' }}

Passaggio 4: inviare un processo di Azure Batch

Un processo di Azure Batch è un gruppo logico di attività simili. Nello scenario è "Process csv to JSON". Ogni attività qui potrebbe essere l'elaborazione di file csv presenti in ogni contenitore di archiviazione di Azure.

Queste attività verranno eseguite in parallelo e distribuite in più nodi, orchestrati dal servizio Azure Batch.

Suggerimento

È possibile usare la proprietà taskSlotsPerNode per specificare il numero massimo di attività che è possibile eseguire simultaneamente in un singolo nodo.

Attività di preparazione

I nodi VM creati sono nodi Ubuntu vuoti. Spesso è necessario installare un set di programmi come prerequisito. Per i nodi Linux è in genere possibile usare uno script della shell che installa i prerequisiti prima dell'esecuzione delle attività effettive. Può tuttavia trattarsi di qualsiasi eseguibile programmabile.

Lo script della shell in questo esempio installa Python-pip e Azure Storage BLOB SDK per 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. Questo processo può essere automatizzato anche usando JavaScript SDK di Archiviazione di Azure.

Suggerimento

Un'attività di preparazione per un processo viene eseguita solo sui nodi VM in cui deve essere eseguita l'attività specifica. 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. È possibile usare la definizione di attività di preparazione seguente come riferimento.

Un'attività di preparazione viene specificata durante l'invio del processo di Azure Batch. Di seguito sono riportati alcuni parametri dell'attività di preparazione configurabili:

  • ID: identificatore univoco dell'attività di preparazione
  • commandLine: riga di comando per eseguire l'eseguibile dell'attività
  • resourceFiles: matrice di oggetti che specifica i dettagli dei file da scaricare per l'esecuzione dell'attività. Di seguito sono riportate le opzioni.
    • httpUrl: URL del file da scaricare
    • filePath: percorso locale per il download e il salvataggio del file
    • fileMode: applicabile solo per nodi Linux, fileMode è in formato ottale con valore predefinito 0770
  • waitForSuccess: se è impostato su true, l'attività non viene eseguita in caso di errori dell'attività di preparazione
  • runElevated: impostare su true se sono necessari privilegi elevati per eseguire l'attività.

Il frammento di codice seguente illustra un esempio di configurazione dello script dell'attività di preparazione:

var jobPrepTaskConfig = {id:"installprereq",commandLine:"sudo sh startup_prereq.sh > startup.log",resourceFiles: [{ 'httpUrl': 'Blob sh url', 'filePath': 'startup_prereq.sh' }],waitForSuccess:true,runElevated:true, userIdentity: {autoUser: {elevationLevel: "admin", scope: "pool"}}}

Se per l'esecuzione delle attività non è necessario installare prerequisiti, è possibile ignorare le attività di preparazione. Il codice seguente crea un processo con il nome visualizzato "process csv files".

// Setting Batch Pool ID
const poolInfo = { poolId: poolId };
// Batch job configuration object
const jobId = "processcsvjob";
const jobConfig = {
    id: jobId,
    displayName: "process csv files",
    jobPreparationTask: jobPrepTaskConfig,
    poolInfo: poolInfo
};
// Adding Azure batch job to the pool
const job = batchClient.job.add(jobConfig, function (error, result) {
        if (error !== null) {
            console.log("An error occurred while creating the job...");
            console.log(error.response);
        }
    }
);

Passaggio 5: inviare le attività di Azure Batch per un processo

Dopo aver creato il processo per l'elaborazione dei file CSV, si creeranno le attività per tale processo. Supponendo di avere quattro contenitori, è necessario creare quattro attività, una per ogni contenitore.

Lo script Python accetta due parametri.

  • container name: contenitore di archiviazione da cui scaricare i file
  • pattern: parametro facoltativo del criterio nome file

Supponendo che siano presenti quattro contenitori "con1", "con2", "con3","con4" il codice seguente mostra l'invio di quattro attività al processo batch di Azure "process csv" creato in precedenza.

// storing container names in an array
const containerList = ["con1", "con2", "con3", "con4"];      //Replace with list of blob containers within storage account
containerList.forEach(function (val, index) {
    console.log("Submitting task for container : " + val);
    const containerName = val;
    const taskID = containerName + "_process";
    // Task configuration object
    const taskConfig = {
        id: taskID,
        displayName: 'process csv in ' + containerName,
        commandLine: 'python processcsv.py --container ' + containerName,
        resourceFiles: [{ 'httpUrl': 'Blob script url', 'filePath': 'processcsv.py' }]
    };

    const task = batchClient.task.add(jobId, taskConfig, function (error, result) {
        if (error !== null) {
            console.log("Error occurred while creating task for container " + containerName + ". Details : " + error.response);
        }
        else {
            console.log("Task for container : " + containerName + " submitted successfully");
        }
    });
});

Il codice aggiunge più attività al pool. Ogni attività viene eseguita in un nodo del pool di VM creato. Se il numero di attività è superiore al numero di VM in un pool o al valore della proprietà taskSlotsPerNode, le attività restano in attesa finché non diventa disponibile un nodo. Questa orchestrazione viene gestita automaticamente da Azure Batch.

Il portale offre visualizzazioni dettagliate delle attività e degli stati del processo. È anche possibile usare l'elenco e ottenere funzioni in Azure JavaScript SDK. Per informazioni dettagliate, vedere la documentazione.

Passaggi successivi