Gerenciar conexões na Automação do Azure

Um ativo de conexão de Automação do Azure contém as informações listadas abaixo. Essas informações são necessárias para conexão com um serviço ou aplicativo externo a partir de um runbook ou 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 juntas todas as propriedades para se conectar a um aplicativo específico, tornando desnecessário criar várias variáveis. Você pode editar os valores de uma conexão em um só lugar e pode passar o nome de uma conexão para um runbook ou configuração DSC em um único parâmetro. O runbook ou configuração acessa as propriedades de uma conexão usando o cmdlet interno Get-AutomationConnection .

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 criar um tipo de conexão usando a API de Automação do Azure se o módulo de integração incluir um tipo de conexão e for importado para sua conta de Automação.

Nota

Os recursos protegidos na Automatização do Azure incluem credenciais, certificados, ligações e variáveis encriptadas. Esses ativos são criptografados e armazenados na Automação do Azure usando uma chave exclusiva gerada para cada conta de Automação. A Automação do Azure armazena a chave no Cofre de Chaves gerenciado pelo sistema. Antes de armazenar um ativo seguro, a Automação carrega a chave do Cofre da Chave e a usa para criptografar o ativo.

Tipos de ligação

A Automação do Azure disponibiliza os seguintes tipos de conexão internos:

• Azure - Representa uma conexão usada para gerenciar 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 criam e gerenciam conexões de automação com o PowerShell. Eles são enviados como parte dos módulos Az.

Cmdlet	Description
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 um campo específico para uma conexão existente.

Cmdlets internos para acessar conexões

O cmdlet interno na tabela a seguir é usado para acessar conexões em seus runbooks e configurações de DSC. Este cmdlet vem com o módulo Orchestrator.AssetManagement.Cmdletsglobal . Para obter mais informações, consulte Cmdlets internos.

Cmdlet interno	Description
Get-AutomationConnection	Obtém os valores dos diferentes campos na ligação e devolve-os como uma tabela hash. Em seguida, pode utilizar esta tabela hash com os comandos adequados na configuração do runbook ou do DSC.

Nota

Evite usar variáveis com o Name parâmetro de Get-AutomationConnection. O uso de variáveis nesse 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 Python para acessar conexões

A função na tabela a seguir é usada para acessar conexões em um runbook Python 2 e 3. Os runbooks do Python 3 estão atualmente em visualização.

Function	Description
automationassets.get_automation_connection	Recupera uma conexão. Retorna um dicionário com as propriedades da conexão.

Nota

Você deve importar o automationassets módulo na parte superior do seu runbook Python para acessar as funções do ativo.

Criar uma nova ligaçã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 criada. Suas escolhas são Azure, AzureServicePrincipale AzureClassicCertificate.
4. O formulário apresenta propriedades para o tipo de conexão que você escolheu. Preencha o formulário e clique em Criar para salvar a nova conexão.

Criar uma nova conexão com o Windows PowerShell

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

Você pode usar os comandos de exemplo a seguir 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 ainda não está definido em 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 ligação

Se sua configuração de runbook ou DSC se conectar a um serviço externo, você deverá definir um tipo de conexão em um módulo personalizado chamado módulo de integração. Este módulo inclui um arquivo de metadados que especifica as propriedades do tipo de conexão e é chamado <ModuleName>-Automation.json, localizado na pasta do módulo do arquivo de .zip compactado. Este arquivo contém os campos de uma conexão que são necessários para se conectar ao sistema ou serviço que o módulo representa. Usando esse arquivo, você pode definir os nomes de campo, tipos de dados, status de criptografia e 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

Recupere uma conexão em uma configuração de runbook ou DSC com o cmdlet interno Get-AutomationConnection . Esse cmdlet é preferido sobre o Get-AzAutomationConnection cmdlet, pois 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 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 conexão em um runbook 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 interno Get-AutomationConnection 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 de uso de um objeto de conexão em um runbook gráfico.

Próximos passos

• 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 Runbook execution in Azure Automation.
• Para obter detalhes sobre as configurações de DSC, consulte Visão geral da configuração de estado.