Tutorial: criar um runbook do Python 3.8

Este tutorial orienta você durante a criação de um Runbook do Python 3.8 na Automação do Azure. Runbooks do Python são compilados no Python 2.7 e 3.8. É possível editar o código do runbook diretamente usando o editor de texto do portal do Azure.

• Criar um runbook simples do Python
• Testar e publicar o runbook
• Executar e acompanhar o status do trabalho do runbook
• Atualizar o runbook para iniciar uma máquina virtual do Azure com parâmetros de runbook

Pré-requisitos

Para concluir este tutorial, você precisará:

• Uma assinatura do Azure. Se você ainda não tiver uma, poderá ativar os benefícios de assinante do MSDN ou inscrever-se em uma conta gratuita.

• Uma Conta de automação para manter o runbook e se autenticar nos recursos do Azure usando Identidades Gerenciadas. Uma identidade gerenciada é criada automaticamente para você ao criar a conta de Automação.

• Uma máquina virtual do Azure. Durante este tutorial, você iniciará e interromperá o computador. Portanto, ele não deverá ser uma VM de produção.

Criar um novo runbook

Você começa criando um runbook simples que exibe o texto Olá, Mundo.

1. No portal do Azure, abra sua conta da Automação.

   A página da conta de Automação fornece uma exibição rápida dos recursos nessa conta. Você já deve ter alguns ativos. A maioria desses ativos é de módulos incluídos automaticamente em uma nova conta de Automação.

   Você também deve ter uma identidade gerenciada habilitada que é mencionada nos pré-requisitos. É possível verificar isso exibindo o recurso Identidade em Configurações da Conta.

2. Selecione Runbooks em Automação de Processos para abrir a lista de runbooks.

3. Selecione Criar um runbook para criar um runbook.

4. Atribua o nome MyFirstRunbook-Python ao runbook.

5. Selecione Python para escolher o Tipo de runbook.

6. Selecione Python 3.8 para escolher a Versão de runtime.

7. Clique em Criar para criar o runbook e abrir o editor textual.

Adicionar código ao runbook

Agora, você adiciona um comando simples para imprimir o texto Hello World.

print("Hello World!")

Clique em Salvar para salvar o runbook.

Testar o runbook

Antes de publicar o runbook para disponibilizá-lo na produção, teste-o para verificar se ele funciona corretamente. Ao testar um runbook, execute a versão de rascunho dele e veja a respectiva saída de modo interativo.

1. Clique em Testar painel para abrir o painel Teste.

2. Clique em Iniciar para iniciar o teste. Essa opção deve ser a única opção habilitada.

3. Um trabalho de runbook é criado e seu status é exibido. O status do trabalho é iniciado como Na fila, indicando que ele está aguardando um trabalho de runbook ficar disponível na nuvem. O status será alterado para Iniciando quando uma função de trabalho reivindicar o trabalho. Depois para Em execução quando o runbook realmente iniciar a execução.

4. Quando o trabalho do runbook é concluído, sua saída é exibida. Neste caso, você deve ver Hello World.

5. Feche o painel Teste para retornar à tela.

Publicar e iniciar o runbook

O runbook criado ainda está em modo de rascunho. Você precisa publicá-lo antes que possa executá-lo na produção. Quando você publica um runbook, substitui a versão Publicada existente pela versão de rascunho. Neste caso, ainda não há uma versão publicada porque você acabou de criar o runbook.

1. Selecione Publicar para publicar o runbook e em Sim quando solicitado.

2. Se você fechar o painel MyFirstRunbook_python, voltará à página Runbooks, em que deverá ver um Status de Criação de Publicado.

3. Selecione o nome MyFirstRunbook-Python na lista. Você voltará para o painel MyFirstRunbook-Python.

   As opções na parte superior nos permitem iniciar, exibir, editar ou agendar o runbook para ser iniciado em algum momento no futuro e outras ações.

4. Selecione Iniciar e clique em OK quando o painel Iniciar Runbook abrir.

5. Um painel chamado Trabalho será aberto para o trabalho de runbook criado. É possível fechar esse painel, mas deixe-o aberto, para acompanhar o progresso do trabalho.

6. O status do trabalho é mostrado no campo Status em Essentials. Os valores aqui correspondem aos valores de status no teste do runbook.

7. Depois que o status do runbook mostrar Concluído, selecione a guia Saída. Na guia Saída, é possível ver Hello World.

8. Feche a guia Saída.

9. Selecione a guia Todos os Logs para exibir fluxos do trabalho de runbook. Você deverá ver apenas Hello World no fluxo de saída. No entanto, essa guia poderá mostrar outros fluxos de um trabalho de runbook, como Detalhado e Erro, caso o runbook faça uma gravação neles.

10. Feche o painel Trabalho para retornar ao painel MyFirstRunbook-Python.

11. Selecione o recurso Trabalhos para abrir a página de recursos Trabalhos desse runbook. Essa página lista todos os trabalhos criados por esse runbook. Você deve ver apenas um trabalho listado, já que executou o trabalho apenas uma vez.

12. É possível selecionar esse trabalho para abrir o mesmo painel Trabalho que foi exibido ao iniciar o runbook. Esse painel permite que você volte no tempo e veja os detalhes de qualquer trabalho que foi criado para um determinado runbook.

Adicionar a autenticação para gerenciar os recursos do Azure

Você testou e publicou seu runbook, mas, até o momento, ele não faz nada útil. Você gostaria que ele gerencie recursos do Azure. Para gerenciar recursos, o script precisa ser autenticado.

A maneira recomendada de autenticá-lo é com a identidade gerenciada. Ao criar uma Conta de Automação do Azure, uma identidade gerenciada é automaticamente criada para você.

Para usar essas amostras, adicione os pacotes a seguir no recurso Pacotes do Python da Conta de Automação. É possível adicionar os arquivos WHL desses pacotes com esses links.

• azure-core
• azure-identity
• azure-mgmt-compute
• azure-mgmt-core
• msal
• typing-extensions

Ao adicionar esses pacotes, selecione uma versão de runtime que corresponda ao runbook.

Observação

O código a seguir foi testado com a versão de runtime 3.8.

Identidade gerenciada

Para usar a identidade gerenciada, verifique se ela está habilitada:

• Para verificar se a Identidade gerenciada está habilitada para a Conta de automação, acesse a Conta de automação>Configurações da Conta>Identidade e defina o Status como Ativado.
• A identidade gerenciada tem uma função atribuída para gerenciar o recurso. Neste exemplo de gerenciamento de um recurso de máquina virtual, adicione a função “Colaborador de Máquina Virtual” no grupo de recursos que contém a Máquina Virtual. Para obter mais informações, veja Atribuir funções do Azure usando o portal do Azure

Com a função de gerenciamento de identidade configurada, é possível começar a adicionar código.

1. Abra o editor de texto selecionando Editar no painel MyFirstRunbook-Python.

2. Adicione o código a seguir para autenticar no Azure:

#!/usr/bin/env python3
from azure.identity import DefaultAzureCredential
from azure.mgmt.compute import ComputeManagementClient

SUBSCRIPTION_ID="YOUR_SUBSCRIPTION_ID"

azure_credential = DefaultAzureCredential()

import os
import requests
# printing environment variables
endpoint = os.getenv('IDENTITY_ENDPOINT')+"?resource=https://management.azure.com/"
identityHeader = os.getenv('IDENTITY_HEADER')
payload={}
headers = {
'X-IDENTITY-HEADER' : identityHeader,
'Metadata' : True
}
response = requests.get(endpoint, headers)
print(response.text)

Adicionar código para criar o cliente da Computação em Python e iniciar a VM

Para trabalhar com VMs do Azure, crie uma instância do Cliente da Computação do Azure para Python.

# Initialize client with the credential and subscription.
compute_client = ComputeManagementClient(
    azure_credential,
    SUBSCRIPTION_ID
)

print('\nStart VM')
async_vm_start = compute_client.virtual_machines.begin_start(
    "MyResourceGroup", "TestVM")
async_vm_start.wait()
print('\nFinished start.')

Em que MyResourceGroup é o nome do grupo de recursos que contém a VM e TestVM é o nome da VM que você deseja iniciar.

Teste e execute o runbook novamente para ver se ele inicia a VM.

Usar parâmetros de entrada

Atualmente, o runbook usa valores embutidos em código para os nomes do grupo de recursos e da VM. Agora, vamos adicionar o código que obtém esses valores dos parâmetros de entrada.

Você usa a variável sys.argv para obter os valores de parâmetro. Adicione o seguinte código ao runbook imediatamente após as outras instruções import:

import sys

resource_group_name = str(sys.argv[1])
vm_name = str(sys.argv[2])

Esse código importará o módulo sys e criará duas variáveis para armazenar os nomes do grupo de recursos e da VM. Observe que o elemento da lista de argumentos, sys.argv[0], é o nome do script e não é fornecido pelo usuário.

Agora, é possível modificar as duas últimas linhas do runbook para usar os valores de parâmetro de entrada em vez de usar valores embutidos em código:

async_vm_start = compute_client.virtual_machines.begin_start(
    resource_group_name, vm_name)
async_vm_start.wait()

Ao iniciar um runbook do Python no painel Teste ou como um runbook publicado, será possível inserir valores para os parâmetros na página Iniciar Runbook em Parâmetros.

Depois de começar a inserir um valor na primeira caixa, uma segunda aparecerá e assim por diante, para que você possa inserir quantos valores de parâmetro forem necessários.

Os valores estão disponíveis para o script como a matriz sys.argv no código que você acabou de adicionar.

Insira o nome do seu grupo de recursos como o valor para o primeiro parâmetro e o nome da VM para iniciar como o valor do segundo parâmetro.

Clique em OK para iniciar o runbook. Ele é executado e inicia a VM especificada.

O tratamento de erro no Python

Você também pode usar as convenções a seguir para recuperar vários fluxos de seus runbooks do Python, incluindo os fluxos WARNING, ERROR e DEBUG.

print("Hello World output")
print("ERROR: - Hello world error")
print("WARNING: - Hello world warning")
print("DEBUG: - Hello world debug")
print("VERBOSE: - Hello world verbose")

O exemplo a seguir mostra essa convenção usada em um bloco try...except.

try:
    raise Exception('one', 'two')
except Exception as detail:
    print ('ERROR: Handling run-time error:', detail)

Próximas etapas

• Para aprender mais sobre os tipos de runbook, bem como as vantagens e as limitações deles, confira Tipos de runbook da Automação do Azure.

• Para obter informações sobre como desenvolver para o Azure em Python, consulte Azure para desenvolvedores de Python.

• Para ver exemplos de runbooks do Python 3, confira o repositório GitHub da Automação do Azure.