Gerenciar conexões na Automação do Azure

Um ativo de conexão da Automação do Azure contém as informações listadas abaixo. Essas informações são necessárias para conexão com um aplicativo ou serviço externo de um runbook ou da configuração DSC.

• Informações necessárias para autenticação, como nome de usuário e senha
• Informações de conexão, como URL ou porta

O ativo de conexão mantém todas as propriedades para se conectar a um aplicativo específico, tornando a criação de várias variáveis desnecessária. O usuário pode editar os valores para uma conexão em um único local, e você pode transmitir o nome de uma conexão para um runbook ou uma configuração DSC em um único parâmetro. O runbook ou a configuração acessa as propriedades de uma conexão usando o cmdlet Get-AutomationConnection interno.

Ao criar uma conexão, você deve especificar um tipo de conexão. O tipo de conexão é um modelo que define um conjunto de propriedades. Você pode adicionar um tipo de conexão à Automação do Azure usando um módulo de integração com um arquivo de metadados. Também é possível usar a API da Automação do Azure para criar um tipo de conexão se o módulo de integração incluir um tipo de conexão e for importado para sua conta de Automação.

Observação

Os ativos protegidos na Automação do Azure incluem credenciais, certificados, conexões e variáveis criptografadas. Esses ativos são criptografados e armazenados na Automação do Azure usando uma chave exclusiva que é gerada para cada conta da Automação do Azure. A Automação do Azure armazena a chave no Key Vault gerenciado pelo sistema. Antes de armazenar um ativo seguro, a Automação do Azure carrega a chave do Key Vault e depois a usa para criptografar o ativo.

Tipos de conexão

A Automação do Azure torna os seguintes tipos de conexão internos disponíveis:

• Azure - Representa uma conexão usada para gerenciar os recursos clássicos.
• AzureServicePrincipal - Representa uma conexão usada para gerenciar recursos no Azure usando uma entidade de serviço.
• AzureClassicCertificate - Esse tipo de conexão é usado para gerenciar recursos no Azure que foram criados usando o modelo de implantação clássico que não oferece suporte à autenticação da entidade de serviço.

Cmdlets do PowerShell para acessar conexões

Os cmdlets na tabela a seguir são usados para criar e gerenciar credenciais de Automação com o PowerShell. Eles são fornecidos como parte de módulos Az.

Cmdlet	Descrição
Get-AzAutomationConnection	Recupera informações sobre uma conexão.
New-AzAutomationConnection	Cria uma nova conexão.
Remove-AzAutomationConnection	Remove uma conexão existente.
Set-AzAutomationConnectionFieldValue	Define o valor de determinado campo para uma conexão existente.

Cmdlets internos para acessar conexões

As cmdlets internos na tabela a seguir são usados para acessar conexões em seus runbooks ou configurações DSC. Esse cmdlet vem com o módulo globalOrchestrator.AssetManagement.Cmdlets. Para obter mais informações, confira Cmdlets internos.

Cmdlet Interno	Descrição
Get-AutomationConnection	Recupera os valores dos diferentes campos na conexão e os retorna como uma tabela de hash. Você pode usar essa tabela de hash com os comandos apropriados no runbook ou na configuração DSC.

Observação

Evite usar variáveis com o parâmetro Name de Get-AutomationConnection. O uso de variáveis neste caso pode complicar a descoberta de dependências entre runbooks ou configurações DSC e ativos de conexão em tempo de design.

Funções do Python para acessar conexões

A função na tabela a seguir é usada para acessar conexões em um runbook do Python 2 e 3. Atualmente, os runbooks do Python 3 estão em versão prévia.

Função	Descrição
automationassets.get_automation_connection	Recupera uma conexão. Retorna um dicionário com as propriedades da conexão.

Observação

É necessário importar o módulo automationassets, na parte superior do runbook do Python para acessar as funções do ativo.

Crie uma nova conexão

Criar uma nova conexão com o portal do Azure

Para criar uma nova conexão no portal do Azure:

1. Na sua Conta de Automação, clique em Conexões em Recursos Compartilhados.
2. Clique em + Adicionar uma conexão na página Conexões.
3. No campo Tipo no painel Nova Conexão, selecione o tipo de conexão a ser criado. Suas opções são Azure, AzureServicePrincipal e AzureClassicCertificate.
4. O formulário apresenta propriedades para o tipo de conexão escolhida. Preencha o formulário e clique em Criar para salvar a nova conexão.

Criar uma nova conexão com o Windows PowerShell

Criar uma nova conexão com o Windows PowerShell usando o cmdlet New-AzAutomationConnection. Esse cmdlet tem um parâmetro ConnectionFieldValues que espera uma tabela de hash que define os valores para cada uma das propriedades definidas pelo tipo de conexão.

Você pode usar os seguintes comandos de exemplo para criar uma conexão que pode ser usada para autenticação usando a Entidade de Serviço do Azure.

$ConnectionAssetName = "AzureConnection"
$ConnectionFieldValues = @{"ApplicationId" = $Application.ApplicationId; "TenantId" = $TenantID.TenantId; "CertificateThumbprint" = $Cert.Thumbprint; "SubscriptionId" = $SubscriptionId}
New-AzAutomationConnection -ResourceGroupName $ResourceGroup -AutomationAccountName $AutomationAccountName -Name $ConnectionAssetName -ConnectionTypeName AzureServicePrincipal -ConnectionFieldValues $ConnectionFieldValues

Se você tentar criar um novo ativo de conexão para se conectar a um serviço ou aplicativo com um método de autenticação diferente, a operação falhará porque o tipo de conexão já não está definido na sua conta de Automação. Para obter mais informações sobre como criar seu próprio tipo de conexão para um módulo personalizado, consulte Adicionar um tipo de conexão.

Adicionar um tipo de conexão

Se o runbook ou a configuração DSC se conectar a um serviço externo, você precisará definir um tipo de conexão em um módulo personalizado chamado de módulo de integração. Esse módulo inclui um arquivo de metadados que especifica as propriedades do tipo de conexão e é tem o nome <ModuleName>-Automation.json, localizado na pasta do módulo do arquivo compactado .zip. Esse arquivo contém os campos de uma conexão que são necessários para estabelecer conexão com o sistema ou serviço que o módulo representa. Use esse arquivo para definir os nomes de campo, os tipos de dados, o status de criptografia e o status opcional para o tipo de conexão. Não há suporte para vários tipos de conexão neste arquivo.

O exemplo a seguir é um modelo no formato de arquivo .json que define as propriedades de nome de usuário e senha para um tipo de conexão personalizado chamado MyModuleConnection:

{
   "ConnectionFields": [
   {
      "IsEncrypted":  false,
      "IsOptional":  true,
      "Name":  "Username",
      "TypeName":  "System.String"
   },
   {
      "IsEncrypted":  true,
      "IsOptional":  false,
      "Name":  "Password",
      "TypeName":  "System.String"
   }
   ],
   "ConnectionTypeName":  "MyModuleConnection",
   "IntegrationModuleName":  "MyModule"
}

Obter uma conexão em um runbook ou configuração DSC

Recuperar uma conexão em um runbook ou configuração DSC com o cmdlet Get-AutomationConnection interno. Prefira esse cmdlet ao Get-AzAutomationConnection, pois ele recupera os valores de conexão em vez de informações sobre a conexão.

PowerShell

O exemplo a seguir mostra como usar uma conexão para autenticar com os recursos do Azure Resource Manager em seu runbook. Ele usa um ativo de conexão que faz referência à entidade de serviço baseada em certificado.

$Conn = Get-AutomationConnection -Name AzureConnection
Connect-AzAccount -ServicePrincipal -Tenant $Conn.TenantID -ApplicationId $Conn.ApplicationID -CertificateThumbprint $Conn.CertificateThumbprint

Python

O exemplo a seguir mostra como autenticar usando a conexão em um runbook do Python 2 e 3.

""" Tutorial to show how to authenticate against Azure resource manager resources """
import azure.mgmt.resource
import automationassets

def get_automation_credential(azure_connection):
    """ Returns credentials to authenticate against Azure resource manager """
    from OpenSSL import crypto
    from msrestazure import azure_active_directory
    import adal

    # Get the Azure Automation service principal certificate
    cert = automationassets.get_automation_certificate("MyCertificate")
    pks12_cert = crypto.load_pkcs12(cert)
    pem_pkey = crypto.dump_privatekey(
        crypto.FILETYPE_PEM, pks12_cert.get_privatekey())

    # Get information for the Azure Automation service principal
    application_id = my_connection["ApplicationId"]
    thumbprint = my_connection["CertificateThumbprint"]
    tenant_id = my_connection["TenantId"]

    # Authenticate with service principal certificate
    resource = "https://management.core.windows.net/"
    authority_url = ("https://login.microsoftonline.com/" + tenant_id)
    context = adal.AuthenticationContext(authority_url)
    return azure_active_directory.AdalAuthentication(
        lambda: context.acquire_token_with_client_certificate(
            resource,
            application_id,
            pem_pkey,
            thumbprint)
    )


# Authenticate to Azure using the Azure Automation service principal
azure_connection = automationassets.get_automation_connection(
    "AzureConnection")
azure_credential = get_automation_credential(azure_connection)

Exemplos de runbook gráfico

Você pode adicionar uma atividade para o cmdlet Get-AutomationConnection interno a um runbook gráfico. Clique com o botão direito do mouse na conexão no painel Biblioteca do editor gráfico e selecione Adicionar à tela.

A imagem a seguir mostra um exemplo do uso de uma objeto de conexão em um runbook gráfico.

Próximas etapas

• Para saber mais sobre os cmdlets usados para acessar conexões, consulte Gerenciar módulos na Automação do Azure.
• Para obter informações gerais sobre runbooks, consulte Execução de runbook na Automação do Azure.
• Para obter detalhes sobre as configurações de DSC, consulte Visão geral do State Configuration.