Introdução ao Batch SDK for JavaScript

Aprenda o básico para construir um cliente Batch em JavaScript usando Azure Batch JavaScript SDK. Adotamos uma abordagem passo a passo para entender um cenário para um aplicativo em lote e, em seguida, configurá-lo usando JavaScript.

Pré-requisitos

Este artigo pressupõe que você tenha um conhecimento prático de JavaScript e familiaridade com Linux. Também assume que tens uma conta Azure configurada com direitos de acesso para criar serviços de Batch e de Armazenamento.

Recomendamos a leitura de Azure Batch Technical Overview antes de seguir os passos descritos neste artigo.

Compreender o cenário

Aqui, temos um script simples escrito em Python que descarrega todos os ficheiros csv de um contentor de armazenamento Azure Blob e converte-os para JSON. Para processar múltiplos contentores de contas de armazenamento em paralelo, podemos implementar o script como um trabalho Azure Batch.

Arquitetura Azure Batch

O diagrama seguinte mostra como podemos escalar o script Python usando o Azure Batch e um cliente.

O exemplo de JavaScript implanta um trabalho em lote com uma tarefa de preparação (explicada em detalhes mais tarde) e um conjunto de tarefas, dependendo do número de contêineres na conta de armazenamento. Podes descarregar os scripts do repositório do GitHub.

• Código de Exemplo
• scripts de preparação da tarefa shell
• Python csv para processador JSON

Criar o aplicativo

Agora, vamos seguir o processo passo a passo para construir o cliente JavaScript:

Passo 1: Instalar o Azure Batch SDK

Podes instalar o Azure Batch SDK para JavaScript usando o comando de instalação npm.

npm install @azure/batch

Este comando instala a versão mais recente do azure-batch JavaScript SDK.

Passo 2: Criar uma conta Azure Batch

Pode criá-lo a partir do portal Azure ou da linha de comandos (PowerShell /Azure CLI).

A seguir estão os comandos para criar um através do Azure CLI.

Crie um Grupo de Recursos, ignore esta etapa se já tiver um onde deseja criar a Conta em lote:

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

De seguida, crie uma conta Azure Batch.

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

Cada conta Batch tem suas chaves de acesso correspondentes. Estas chaves são necessárias para criar mais recursos na conta batch do Azure. Uma boa prática para ambiente de produção é usar o Azure Key Vault para armazenar estas chaves. Em seguida, pode-se criar um Service principal para a aplicação. Usando essa entidade de serviço, o aplicativo pode criar um token OAuth para acessar chaves do cofre de chaves.

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

Copie e armazene a chave a ser usada nas etapas subsequentes.

Passo 3: Criar um cliente de serviço Azure Batch

O trecho de código a seguir primeiro importa o módulo JavaScript azure-batch e, em seguida, cria um cliente do Batch Service. Você precisa primeiro criar um objeto SharedKeyCredentials com a chave de conta Batch copiada da etapa anterior.

// 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);

O Azure Batch URI pode ser encontrado no separador Overview do portal Azure. É do formato:

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

Consulte a captura de tela:

Passo 4: Criar um Azure Batch pool

Um Azure Batch pool consiste em múltiplas VMs (também conhecidas como Batch Nodes). O serviço Azure Batch implementa as tarefas nestes nós e gere-as. Você pode definir os seguintes parâmetros de configuração para seu pool.

• Tipo de imagem da máquina virtual
• Tamanho dos nós da máquina virtual
• Número de nós de máquina virtual

O trecho de código a seguir cria os objetos de parâmetro de configuração.

// 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";

Depois de definida a configuração do pool, podes criar o Azure Batch pool. O comando Batch pool cria nós de Máquinas Virtuais Azure e prepara-os para receberem tarefas para execução. Cada pool deve ter um ID exclusivo para referência nas etapas subsequentes.

O seguinte excerto de código cria um Azure Batch pool.

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

Você pode verificar o estado do pool criado e assegurar-se de que o estado seja "ativo" antes de prosseguir com o envio de um trabalho para esse 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");
            }
        }
        });

A seguir está um objeto de resultado de exemplo retornado pela função 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' }}

Passo 4: Enviar um trabalho para o Azure Batch

Um trabalho do Azure Batch é um grupo lógico de tarefas semelhantes. No nosso cenário, é "Processar csv para JSON." Cada tarefa aqui pode ser processar ficheiros csv presentes em cada contentor do Azure Storage.

Estas tarefas seriam executadas em paralelo e implementadas em múltiplos nós, orquestradas pelo serviço Azure Batch.

Tarefa de preparação

Os nós de VM criados são nós Ubuntu vazios. Muitas vezes, você precisa instalar um conjunto de programas como pré-requisitos. Normalmente, para nós Linux você pode ter um shell script que instala os pré-requisitos antes que as tarefas reais sejam executadas. No entanto, pode ser qualquer executável programável.

O script shell neste exemplo instala o Python-pip e o Azure Storage Blob SDK para Python.

Podes carregar o script numa conta Azure Storage e gerar um URI SAS para aceder ao script. Este processo também pode ser automatizado usando o Azure Storage JavaScript SDK.

Uma tarefa de preparação é especificada durante a submissão do Azure Batch Job. A seguir estão alguns parâmetros configuráveis da tarefa de preparação:

• ID: Um identificador único para a tarefa de preparação
• CommandLine: Linha de comandos para executar o executável da tarefa
• resourceFiles: Array de objetos que fornecem detalhes dos ficheiros necessários para que esta tarefa seja executada. Seguem-se as suas opções
  • httpUrl: O URL do arquivo para baixar
  • filePath: Caminho local para baixar e salvar o arquivo
  • fileMode: Aplicável apenas para nós Linux, fileMode está em formato octal com um valor predefinido de 0770
• waitForSuccess: Caso seja definido como verdadeiro, a tarefa não é executada em caso de falhas na tarefa de preparação
• runElevated: Defina-o como true se forem necessários privilégios elevados para executar a tarefa.

O trecho de código a seguir mostra o exemplo de configuração de script de tarefa de preparação:

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 não houver pré-requisitos a serem instalados para que suas tarefas sejam executadas, você poderá ignorar as tarefas de preparação. O código a seguir cria um trabalho com o nome de exibição "processar arquivos csv".

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

Passo 5: Submeter tarefas em Azure Batch para um trabalho

Agora que a nossa tarefa de processo CSV está criada, vamos criar tarefas para essa tarefa. Supondo que temos quatro contêineres, temos que criar quatro tarefas, uma para cada contêiner.

Se olharmos para o script Python, aceita dois parâmetros:

• nome do contêiner: o contêiner de armazenamento do qual baixar arquivos
• pattern: um parâmetro opcional do padrão de nome de arquivo

Assumindo que temos quatro contentores "con1", "con2", "con3", "con4", o código seguinte mostra como submeter quatro tarefas ao trabalho em lote do Azure "process csv" que criámos anteriormente.

// 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");
        }
    });
});

O código adiciona várias tarefas ao pool. E cada uma das tarefas é executada em um nó no pool de VMs criadas. Se o número de tarefas exceder o número de VMs num pool ou a propriedade taskSlotsPerNode, as tarefas esperarão até que um nó esteja disponível. Esta orquestração é gerida automaticamente pelo Azure Batch.

O portal tem vistas detalhadas sobre as tarefas e os status das funções. Também podes usar a lista e obter funções no Azure JavaScript SDK. Os detalhes são fornecidos no link da documentação.

Próximos passos

• Saiba mais sobre o fluxo de trabalho do serviço Batch e os recursos primários, como pools, nós, jobs e tarefas.
• Consulte a referência ao JavaScript do Batch para explorar a API do Batch.