Compartilhar via

Adicionar e executar scripts do PowerShell com fluxos de trabalho Standard nos Aplicativos Lógicos do Azure

Aplica-se a: Aplicativos Lógicos do Azure (Standard)

Para executar tarefas de integração personalizadas embutidas com seu fluxo de trabalho Standard nos Aplicativos Lógicos do Azure, você pode adicionar e executar código do PowerShell diretamente do seu fluxo de trabalho. Para essa tarefa, use a ação de Código Embutido chamada Executar Código PowerShell. Essa ação retorna os resultados do código do PowerShell para que você possa usar essa saída nas ações posteriores do fluxo de trabalho.

Essa funcionalidade fornece os seguintes benefícios:

  • Escreva seus scripts no designer de fluxo de trabalho para que você possa resolver desafios complexos de integração. Não são necessários outros planos de serviço.

    Esse benefício reduz a complexidade e o custo porque você pode gerenciar mais serviços e simplificar o desenvolvimento de fluxo de trabalho.

  • Gere um arquivo de código dedicado, que oferece um espaço personalizado para scripts dentro do seu fluxo de trabalho.

  • Integre-se às funções do PowerShell do Azure Functions, que fornecem funcionalidade e herança avançadas para execução avançada de tarefas.

  • Implante scripts junto com seus fluxos de trabalho.

Este guia mostra como adicionar a ação em seu fluxo de trabalho e adicionar o código do PowerShell que você deseja executar.

Pré-requisitos

  • Uma conta e uma assinatura do Azure. Obtenha uma conta gratuita do Azure.

  • O recurso de aplicativo lógico Standard com o fluxo de trabalho no qual você deseja adicionar seu script do PowerShell.

    O fluxo de trabalho já precisa começar com um gatilho. Você pode usar qualquer gatilho para seu cenário, mas, como exemplo, este guia usa o gatilho de solicitação chamado Quando uma solicitação HTTP é recebida e também a ação resposta . O fluxo de trabalho é executado quando outro aplicativo ou fluxo de trabalho envia uma solicitação para a URL do ponto de extremidade do gatilho. O script de exemplo retorna os resultados da execução do código como saída que você pode usar em ações posteriores.

    Se você não tiver um recurso de aplicativo lógico e um fluxo de trabalho, crie-os agora seguindo estas etapas:

Considerações

  • O portal do Azure salva seu script como um arquivo de script do PowerShell (.ps1) na mesma pasta que o arquivo workflow.json, que armazena a definição JSON para seu fluxo de trabalho e implanta o arquivo no recurso de aplicativo lógico junto com a definição de fluxo de trabalho.

    O formato de arquivo .ps1 permite que você escreva menos "código padrão" e concentre-se apenas na escrita do código PowerShell. Se você renomear a ação, o arquivo também será renomeado, mas o contrário não é verdadeiro. Se você renomear diretamente o arquivo, a versão renomeada substituirá a versão anterior. Se o nome da ação e os nomes de arquivo não corresponderem, a ação não poderá localizar o arquivo e tentará criar um arquivo vazio.

  • O script é local para o fluxo de trabalho. Para usar o mesmo script em outros fluxos de trabalho, exiba o arquivo de script no console do Kudu e copie o script para reutilizar em outros fluxos de trabalho.

Limitações

Nome Limite Observações
Duração da execução do script 10 minutos Se você tiver cenários que precisam de durações mais longas, use a opção de comentários do produto para fornecer mais informações sobre suas necessidades.
Tamanho da saída 100 MB O tamanho da saída depende do limite de tamanho de saída para ações, que geralmente é de 100 MB.

Atualizar a versão do PowerShell

Você pode alterar a versão do PowerShell em seu recurso de aplicativo lógico editando as configurações do aplicativo. No entanto, antes de fazer upgrade do aplicativo, examine as seguintes considerações:

Observação

Por padrão, se você não especificar uma versão do PowerShell, os Aplicativos Lógicos do Azure usarão a mesma versão padrão do Azure Functions. Atualmente, o PowerShell 7.4 está em disponibilidade geral. Para obter mais informações sobre as versões disponíveis, confira o guia de desenvolvedor do PowerShell do Azure Functions.

Com base no local em que você deseja atualizar a versão do PowerShell, siga as etapas correspondentes:

  1. No portal do Azure, abra o recurso do aplicativo lógico padrão.

  2. Na barra lateral do recurso, em Configurações, selecione Variáveis de ambiente.

  3. Na guia Configurações do aplicativo, selecione + Adicionar.

  4. No painel Adicionar/Editar configuração do aplicativo, adicione a seguinte nova configuração de aplicativo:

    Parâmetro Value Descrição
    Nome LOGIC_APPS_POWERSHELL_VERSION O nome da configuração do aplicativo.
    Valor < versão do PowerShell> A versão do PowerShell, atualmente 7.4.

  5. Quando terminar, selecione Aplicar. Quando o aviso de reinicialização for exibido, selecione Continuar.

    Seu aplicativo lógico será reiniciado com a versão atualizada.

Adicionar a ação Executar Código do PowerShell

  1. No portal do Azure, abra o recurso do aplicativo lógico padrão.

  2. Na barra lateral do recurso, em Fluxos de Trabalho, selecione Fluxos de Trabalho e selecione seu fluxo de trabalho em branco.

  3. Na barra lateral do fluxo de trabalho, em Ferramentas, selecione o designer para abrir o fluxo de trabalho.

  4. Adicione a ação Operações de Código Embutido chamada Executar Código do PowerShell ao fluxo de trabalho seguindo as etapas gerais para adicionar uma ação.

  5. Depois que o painel de informações da ação for aberto, na guia Parâmetros, na caixa Arquivo de Código, atualize o código de exemplo pré-preenchido com seu código.

    O exemplo a seguir mostra a guia Parâmetros da ação com o código de script de exemplo:

    A captura de tela mostra o portal do Azure, o designer de fluxo de trabalho Standard, o gatilho Solicitar, a ação Executar Código do PowerShell com o painel de informações aberto e a ação de Resposta.

    O exemplo a seguir mostra o código de script de exemplo:

    # Use the following cmdlets to retrieve outputs from prior steps.
# $triggerOutput = Get-TriggerOutput
# $ActionOutput = Get-ActionOutput -ActionName <action-name>

$customResponse =  [PSCustomObject]@{
   Message = "Hello world!"
}

# Use Write-Debug/Write-Host/Write-Output/ to log messages to Application Insights.
# Write-Host/Write-Output/Write-Debug and 'return' won't return an output to the workflow.
# Write-Host "Sending to Application Insight logs"

# Use Push-WorkflowOutput to push outputs into subsequent actions.
Push-WorkflowOutput -Output $customResponse

    O seguinte exemplo mostra um script de exemplo personalizado:

    $action = Get-TriggerOutput
$results = "Hello from PowerShell!"
Push-WorkflowOutput -Output $results

  6. Quando terminar, salve o fluxo de trabalho.

Depois de executar o seu fluxo de trabalho, você pode analisar a saída no Application Insights, caso esteja habilitado. Para obter mais informações, confira Exibir saída no Application Insights.

Acessar o gatilho de fluxo de trabalho e as saídas de ação em seu script

Os valores de saída do gatilho e das ações anteriores são retornados usando um objeto personalizado, que tem vários parâmetros. Para acessar essas saídas e garantir que você retorne o valor desejado, use os cmdlets Get-TriggerOutput, Get-ActionOutput e Push-WorkflowOutput mais os parâmetros apropriados descritos na tabela a seguir, por exemplo:

$trigger = Get-TriggerOutput
$statusCode = $trigger.status.ToString();
$action = Get-ActionOutput -ActionName Compose
$actionOutput = $action.outputs['actionOutput'].ToString();
$populatedString = "Send the $statusCode for the trigger status and $actionOutputName."

Push-WorkflowOutput -Output $populatedString

Observação

No PowerShell, se você fizer referência a um objeto que tenha o tipo JValue dentro de um objeto complexo e adicionar esse objeto a uma cadeia de caracteres, obterá uma exceção de formato. Para evitar esse erro, use ToString().

Saídas de gatilho e resposta de ação

A tabela a seguir lista as saídas geradas quando você chama Get-ActionOutput ou Get-TriggerOutput. O valor retornado é um objeto complexo chamado PowershellWorkflowOperationResult, que contém as saídas a seguir.

Nome Tipo Descrição
Nome fio O nome do gatilho ou da ação
Entradas JToken Os valores de entrada passados para o gatilho ou a ação
Saídas JToken As saídas do gatilho ou da ação executada
StartTime Datetime A hora de início do gatilho ou da ação
EndTime Datetime A hora de término do gatilho ou da ação
ScheduledTime Datetime A hora agendada para executar o gatilho ou ação
OriginHistoryName fio O nome do histórico de origem para gatilhos que usam a propriedade splitOn
SourceHistoryName fio O nome do histórico de origem de um gatilho reenviado
TrackingId fio A ID de acompanhamento da operação
Código fio O código de status do resultado
Estado fio O status de execução do gatilho ou da ação, por exemplo, "Êxito" ou "Falha"
Erro JToken O código de erro HTTP
TrackedProperties JToken Quaisquer propriedades rastreadas que você configurou

Retornar saídas ao fluxo de trabalho

Para retornar quaisquer saídas ao fluxo de trabalho, você deve usar o cmdletPush-WorkflowOutput.

Comandos personalizados do PowerShell

A ação Executar Código do PowerShell inclui os seguintes comandos personalizados do PowerShell (cmdlets) para interagir com seu fluxo de trabalho e outras operações em seu fluxo de trabalho:

Get-TriggerOutput

Obtém a saída do gatilho do fluxo de trabalho.

Sintaxe

Get-TriggerOutput

Parâmetros

Nenhum.

Get-ActionOutput

Obtém a saída de outra ação no fluxo de trabalho e retorna um objeto chamado PowershellWorkflowOperationResult.

Sintaxe

Get-ActionOutput [ -ActionName <String> ]

Parâmetros

Parâmetro Tipo Descrição
ActionName fio O nome da ação no fluxo de trabalho com a saída que você deseja referenciar.

Push-WorkflowOutput

Envia por push a saída da ação Executar Código do PowerShell para o fluxo de trabalho, que pode passar qualquer tipo de objeto. Se o valor retornado for nulo, você receberá um erro de objeto nulo do cmdlet.

Observação

Os cmdlets Write-Debug, Write-Host e Write-Output não retornam valores para o seu fluxo de trabalho. A return instrução também não retorna valores para o fluxo de trabalho. No entanto, você pode usar esses cmdlets para gravar mensagens de rastreamento que aparecem no Application Insights. Para obter mais informações, confira Microsoft.PowerShell.Utility.

Sintaxe

Push-WorkflowOutput [-Output <Object>] [-Clobber]

Parâmetros

Parâmetro Tipo Descrição
Saída Varia A saída que você deseja retornar ao fluxo de trabalho. Essa saída pode ter qualquer tipo.
Clobber Varia Um parâmetro opcional de comutador que você pode usar para substituir a saída enviada por push anteriormente.

Autenticar e autorizar o acesso com uma identidade gerenciada usando o PowerShell

Com uma identidade gerenciada, o recurso de aplicativo lógico e o fluxo de trabalho podem autenticar e autorizar o acesso a qualquer serviço e recurso do Azure que dê suporte à autenticação do Microsoft Entra sem incluir credenciais em seu código.

De dentro da ação Executar Código do PowerShell, você pode autenticar e autorizar o acesso com uma identidade gerenciada para que possa executar ações em outros recursos do Azure em que você habilitou o acesso. Por exemplo, você pode reiniciar uma máquina virtual ou obter os detalhes de execução de outro fluxo de trabalho do aplicativo lógico.

Para usar a identidade gerenciada de dentro da ação Executar Código do PowerShell, siga estas etapas:

  1. Configure a identidade gerenciada em seu aplicativo lógico e conceda acesso à identidade gerenciada no recurso do Azure de destino. Para obter etapas detalhadas, consulte Autenticar acesso e conexões com recursos do Azure com identidades gerenciadas.

    No recurso de destino do Azure, examine as seguintes considerações:

    • Na guia Função, uma função Colaborador geralmente é suficiente.

    • Na página Adicionar atribuição de função, na guia Membros, para Atribuir acesso à propriedade , selecione Identidade gerenciada.

    • Depois de selecionar Selecionar membros, no painel Selecionar identidades gerenciadas, selecione a identidade gerenciada que você deseja usar.

  2. Em sua ação Executar Código do PowerShell, inclua o seguinte código como a primeira instrução:

    Connect-AzAccount -Identity

  3. Agora, você pode trabalhar com o recurso do Azure usando cmdlets e módulos.

Exibir o arquivo de script

  1. No portal do Azure, abra o recurso do aplicativo lógico padrão.

  2. Na barra lateral do recurso, em Ferramentas de Desenvolvimento, selecione Ferramentas Avançadas.

  3. Na página Ferramentas Avançadas , selecione Go, que abre o console do Kudu .

  4. Abra o menu Depurar console e selecione CMD.

  5. Vá para o local da raiz do aplicativo lógico: site/wwwroot

  6. Vá para a pasta do fluxo de trabalho, que contém o arquivo com a extensão .ps1 neste caminho: site/wwwroot/{workflow-name}

  7. Ao lado do nome do arquivo, selecione Editar para abrir e exibir o arquivo.

Exibir logs no Application Insights

  1. No portal do Azure, na barra lateral do aplicativo lógico, em Monitoramento, selecione Application Insights (não Insights).

  2. Selecione o link para o recurso do Application Insights.

  3. Na barra lateral do recurso do Application Insights , em Monitoramento, selecione Logs.

  4. Crie uma consulta para localizar os rastreamentos ou erros provenientes da execução do seu fluxo de trabalho, por exemplo:

    union traces, errors
| project TIMESTAMP, message

Módulos

Os módulos do PowerShell são unidades autocontidas e reutilizáveis que incluem vários componentes, por exemplo:

  • Cmdlets: comandos individuais que executam tarefas específicas.
  • Provedores: permitir o acesso a armazenamentos de dados, como o registro ou o sistema de arquivos, como se fossem unidades.
  • Funções: blocos de código reutilizáveis que executam ações específicas.
  • Variáveis: armazene dados para uso dentro do módulo.
  • Outros tipos de recursos.

Um módulo organiza o código do PowerShell, facilitando a distribuição. Por exemplo, você pode criar seus módulos para empacotar e tornar a funcionalidade relacionada mais gerenciável e compartilhável. A ação Executar Código do PowerShell permite importar módulos públicos e privados do PowerShell.

Módulos públicos

Para localizar módulos disponíveis publicamente, visite a Galeria do PowerShell. Um recurso de aplicativo lógico Standard pode dar suporte a até dez módulos públicos. Para usar qualquer módulo público, você precisa habilitar essa funcionalidade seguindo estas etapas:

  1. No portal do Azure, na barra lateral do aplicativo lógico, em Ferramentas de Desenvolvimento, selecione Ferramentas Avançadas.

  2. Na página Ferramentas avançadas, selecione Go.

  3. Na barra de ferramentas do Kudu, abra o menu do Console de depuração e selecione CMD.

  4. Navegue até o nível raiz do aplicativo lógico em C:\home\site\wwwroot usando a estrutura de diretório ou a linha de comando.

  5. Abra o arquivo host.json do fluxo de trabalho e defina a propriedade ManagedDependency.enabled como true, que já está definida por padrão.

    "managedDependency": {
    "enabled": true
}

  6. Abra o arquivo nomeado requirements.psd1. Inclua o nome e a versão do módulo desejado usando a seguinte sintaxe: MajorNumber.* ou a versão exata do módulo, por exemplo:

    @{
    Az = '1.*'
    SqlServer = '21.1.18147'
}

Considerações sobre módulos públicos

As seguintes considerações se aplicam ao usar o gerenciamento de dependências:

  • Para baixar módulos, os módulos públicos exigem acesso à Galeria do PowerShell.

  • Atualmente, as dependências gerenciadas não dão suporte a módulos que exigem que você aceite uma licença, aceitando a licença interativamente ou fornecendo a opção -AcceptLicense ao executar Install-Module.

Módulos privados

Você pode gerar seus módulos privados do PowerShell. Para criar seu primeiro módulo do PowerShell, confira Escrever um módulo de script do PowerShell.

  1. No portal do Azure, nas barras laterais do recurso do aplicativo lógico, em Ferramentas de Desenvolvimento, selecione Ferramentas Avançadas.

  2. Na página Ferramentas avançadas, selecione Go.

  3. Na barra de ferramentas do Kudu, abra o menu do Console de depuração e selecione CMD.

  4. Navegue até o nível raiz do aplicativo lógico em C:\home\site\wwwroot usando a estrutura de diretório ou a linha de comando.

  5. Crie uma pasta chamada Módulos.

  6. Na pasta Módulos, crie uma subpasta com o mesmo nome do módulo privado.

  7. Na pasta do módulo privado, adicione o arquivo de módulo privado do PowerShell com a extensão .psm1 . Você também pode incluir um arquivo de manifesto opcional do PowerShell com a extensão .psd1 .

Quando terminar, a estrutura completa do arquivo de aplicativo lógico será semelhante ao seguinte exemplo:

MyLogicApp
-- execute_powershell_script.ps1
-- mytestworkflow.json
Modules
-- MyPrivateModule
--- MyPrivateModule.psd1
--- MyPrivateModule.psm1
-- MyPrivateModule2
--- MyPrivateModule2.psd1
--- MyPrivateModule2.psm1
requirements.psd1
host.json

Erros de compilação

Nesta versão, o editor baseado na web inclui suporte limitado do IntelliSense, que ainda está em aperfeiçoamento. Todos os erros de compilação são detectados quando você salva o fluxo de trabalho, e o runtime dos Aplicativos Lógicos do Azure compila seu script. Esses erros aparecem nos logs de erro do aplicativo lógico por meio do Application Insights.

Erros em runtime

Uma ação de fluxo de trabalho não retorna nenhuma saída.

Certifique-se de usar o Push-WorkflowOutput cmdlet.

Falha na ação Executar Código do PowerShell: "O termo '{algum-texto}' não é reconhecido..."

Se você fizer referência incorreta a um módulo público no arquivo requirements.psd1 ou se o módulo privado não existir no caminho C:\home\site\wwwroot\Modules{module-name}, você receberá o seguinte erro:

"O termo '{some-text}' não é reconhecido como um nome de um cmdlet, função, arquivo de script ou programa executável. Verifique a ortografia do nome ou se um caminho foi incluído, verifique se o caminho está correto e tente novamente."

Observação

Por padrão, os módulos Az* aparecem no arquivo requirements.psd1, mas são comentados na criação do arquivo. Ao fazer referência a um cmdlet do módulo, certifique-se de remover a marca de comentário do módulo.

Falha na ação Executar Código do PowerShell: "Não é possível associar o argumento ao parâmetro 'Output' porque ele é nulo."

Esse erro ocorre quando você tenta enviar um objeto nulo por push para o fluxo de trabalho. Confirme se o objeto que você está enviando com Push-WorkflowOutput não é nulo.

Conteúdo relacionado

  • Last updated on