Gerenciar recursos do Lote com a CLI do Azure
É possível gerenciar seus recursos e suas contas do Lote do Azure com a CLI (interface de linha de comando) do Azure. Há comandos para criar e atualizar recursos do Lote, como pools, trabalhos e tarefas. Você também pode criar scripts para muitas das mesmas tarefas que você realiza por meio de APIs do Lote, cmdlets do PowerShell e pelo portal do Azure.
É possível executar a CLI do Azure no Azure Cloud Shell ou instalar localmente a CLI do Azure. As versões estão disponíveis para SO (sistemas operacionais) Windows, Mac e Linux.
Este artigo explica como usar a CLI do Azure com recursos e contas do Lote.
Configurar a CLI do Azure
Escolha como você deseja configurar a CLI do Azure:
- Execute a CLI do Azure no Cloud Shell.
- Instale a CLI do Azure localmente.
- Instale a CLI do Azure no Windows
- Instale a CLI do Azure no macOS
- Instale a CLI do Azure no Linux para várias distribuições do Linux.
Se você não estiver familiarizado com o uso da CLI do Azure, confira Introdução à CLI do Azure antes de continuar.
Se você já instalou a CLI do Azure localmente, atualize sua instalação para a versão mais recente.
Autenticar-se na CLI do Azure
Para usar a CLI do Azure com o Lote, primeiro entre em sua conta do Azure e, em seguida, entre em sua conta do Lote.
Entrar em uma conta do Azure
Para usar a CLI do Azure, primeiro entre em sua conta do Azure. O logon no Azure fornece acesso a comandos do Azure Resource Manager, que incluem comandos do Serviço de Gerenciamento de Lotes. Em seguida, você pode executar comandos para gerenciar chaves, pacotes de aplicativos, cotas e contas do Lote.
Você pode autenticar sua conta do Azure na CLI do Azure de duas maneiras. Para executar comandos por conta própria, entre na CLI do Azure interativamente. A CLI do Azure armazena suas credenciais em cache e pode usá-las para entrar em sua conta do Lote posteriormente. Faça logon na CLI do Azure com uma entidade de serviço para executar comandos de um script ou aplicativo.
Para entrar na CLI do Azure interativamente, execute az login:
az login
Entrar na conta do Lote
Em seguida, entre em sua conta do Lote na CLI do Azure usando o comando az batch account login. Esta etapa fornece acesso aos comandos do serviço Lote. Em seguida, você pode gerenciar recursos do Lote, como pools, trabalhos e tarefas.
É possível autenticar sua conta do Lote na CLI do Azure de duas maneiras. O método padrão é autenticar usando o Microsoft Entra ID. Recomenda-se usar esse método na maioria dos cenários. Outra opção é usar a autenticação de chave compartilhada.
Se você estiver criando scripts da CLI do Azure para automatizar comandos do Lote, poderá usar qualquer um dos métodos de autenticação. Em alguns cenários, o uso da autenticação de chave compartilhada pode ser mais simples do que criar uma entidade de serviço.
Autenticação com o Microsoft Entra ID
O método padrão para autenticar-se com sua conta do Lote é por meio do Microsoft Entra ID. Ao entrar na CLI do Azure interativamente ou com uma entidade de serviço, é possível usar essas mesmas credenciais armazenadas em cache para entrar em sua conta do Lote com o Microsoft Entra ID. Esse método de autenticação também oferece o RBAC (controle de acesso baseado em função) do Azure. Com o RBAC do Azure, o acesso do usuário depende da função atribuída, não das chaves de conta. Você só precisa gerenciar as funções do Azure, não as chaves de conta. Então, o Microsoft Entra ID manipulará o acesso e a autenticação.
Para entrar em sua conta do Lote com o Microsoft Entra ID, execute az batch login. Inclua os parâmetros obrigatórios para o nome da sua conta do Lote (-n) e o nome do grupo de recursos (-g).
az batch account login -g <your-resource-group> -n <your-batch-account>
Autenticar-se com chave compartilhada
Você também pode usar a autenticação de chave compartilhada para entrar em sua conta do Lote. Este método usa as chaves de acesso de sua conta a fim de autenticar comandos da CLI do Azure para o serviço Lote.
Para entrar em sua conta do Lote com a autenticação de chave compartilhada, execute az batch login com o parâmetro --shared-key-auth. Inclua os parâmetros obrigatórios para o nome da sua conta do Lote (-n) e o nome do grupo de recursos (-g).
az batch account login -g <your-resource-group> -n <your-batch-account> --shared-key-auth
Aprender comandos do Lote
A documentação de referência da CLI do Azure lista todos os comandos da CLI do Azure para o Lote.
Para listar todos os comandos do Lote na CLI do Azure, execute az batch -h.
Há vários scripts da CLI de exemplo para tarefas comuns do Lote. Esses exemplos mostram como usar muitos comandos disponíveis para o Lote na CLI do Azure. Você pode aprender a criar e gerenciar pools, trabalhos, tarefas e contas do Lote.
Usar comandos da extensão da CLI do Lote
É possível usar a extensão da CLI do Lote para executar trabalhos do Lote sem codificação. A extensão fornece comandos para usar modelos JSON a fim de criar pools, trabalhos e tarefas com a CLI do Azure. A extensão também fornece comandos para se conectar a uma conta do Armazenamento do Azure vinculada à sua conta do Lote. Em seguida, você pode carregar e baixar arquivos de entrada de trabalho.
Criar recursos com JSON
É possível criar a maioria dos recursos do Lote usando apenas parâmetros de linha de comando. Alguns recursos exigem que você especifique um arquivo de configuração JSON. O arquivo JSON contém os detalhes de configuração do novo recurso. Por exemplo, você deve usar um arquivo JSON se quiser especificar arquivos de recurso para uma tarefa de inicialização.
Por exemplo, para usar um arquivo JSON para configurar um novo recurso de pool do Lote:
az batch pool <your-batch-pool-configuration>.json
Ao especificar um arquivo JSON para um novo recurso, não use outros parâmetros em seu comando. O serviço usa apenas o arquivo JSON para configurar o recurso.
A documentação de referência da API REST do Lote lista a sintaxe JSON necessária para criar um recurso.
Para ver a sintaxe JSON necessária para criar um recurso, confira a documentação de referência da API REST do Lote. Acesse a seção Exemplos na página de referência da operação de recurso. Em seguida, encontre a subseção Adicionar <tipo de recurso>. Por exemplo, Adicionar uma tarefa básica. Use o código JSON de exemplo como modelo para seus arquivos de configuração.
Para um exemplo de script que especifica um arquivo JSON, consulte Executar um trabalho e tarefas com o Lote.
Consultar recursos do Lote com eficiência
É possível consultar sua conta do Lote e listar todos os recursos com o comando list. Por exemplo, para listar os pools em sua conta e as tarefas em um trabalho:
az batch pool list
az batch task list --job-id <your-job-id>
Para limitar a quantidade de dados que a consulta do Lote retorna, especifique uma cláusula OData. Toda a filtragem ocorre no lado do servidor, portanto, você só recebe os dados solicitados. Use essas cláusulas OData para economizar largura de banda e tempo com operações list. Para saber mais, confira Criar consultas de lista eficientes para recursos do Lote.
| Cláusula | Descrição |
|---|---|
--select-clause [select-clause] |
Retorna um subconjunto de propriedades para cada entidade. |
--filter-clause [filter-clause] |
Retorna apenas as entidades que correspondem à expressão de OData especificada. |
--expand-clause [expand-clause] |
Obtém as informações de entidade em uma única chamada REST subjacente. A cláusula expand atualmente dá suporte apenas à propriedade stats. |
Para um script de exemplo que mostra como usar uma dessas cláusulas, confira Executar um trabalho e tarefas com o Lote.
Solução de problemas
Para obter ajuda com qualquer comando do Lote, adicione -h ao final do comando. Não adicione outras opções. Por exemplo, para obter ajuda na criação de uma conta do Lote, execute az batch account create -h.
Para retornar a saída de comando detalhada, adicione -v ou -vv ao final do comando. Use essas opções para exibir a saída de erro completa. O-vv sinalizador retorna as solicitações e respostas REST reais.
Para exibir a saída do comando no formato JSON, adicione --json ao final do comando. Por exemplo, para exibir as propriedades de um pool chamado pool001, execute az batch pool show pool001 --json. Em seguida, copie e modifique a saída para criar recursos do Lote usando um arquivo de configuração JSON.
Solução geral de problemas da CLI do Azure
A CLI do Azure pode ser executada em vários ambientes de shell, mas com pequenas variações de formato. Se você tiver resultados inesperados com comandos da CLI do Azure, confira Como usar a CLI do Azure com êxito.