Adicionar e executar código de script do PowerShell em fluxos de trabalho padrão para Aplicativos Lógicos do Azure (Visualização)
Aplica-se a: Aplicativos Lógicos do Azure (Padrão)
Nota
Esta funcionalidade está em pré-visualização e está sujeita aos Termos de Utilização Suplementares para Pré-visualizações do Microsoft Azure.
Para executar tarefas de integração personalizadas em linha com seu fluxo de trabalho Standard nos Aplicativos Lógicos do Azure, você pode adicionar e executar diretamente o código do PowerShell de dentro do seu fluxo de trabalho. Para esta tarefa, use a ação Código embutido chamada Executar código do PowerShell. Essa ação retorna os resultados do código do PowerShell para que você possa usar essa saída nas ações subsequentes do fluxo de trabalho.
Esse recurso oferece os seguintes benefícios:
Escreva seus próprios scripts dentro do 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 simplifica o desenvolvimento do fluxo de trabalho e reduz a complexidade e o custo com o gerenciamento de mais serviços.
Gere um arquivo de código dedicado, que fornece um espaço de script personalizado em seu fluxo de trabalho.
Integre com o Azure Functions PowerShell Functions, que fornece funcionalidade poderosa e herança 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 subscrição do Azure. Se não tiver uma subscrição, inscreva-se numa conta do Azure gratuita.
O fluxo de trabalho do aplicativo lógico padrão onde você deseja adicionar seu script do PowerShell. O fluxo de trabalho já deve começar com um gatilho. Para obter mais informações, consulte Criar exemplos de fluxos de trabalho de aplicativos lógicos padrão.
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 de código como saída que você pode usar em ações subsequentes.
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 do aplicativo lógico junto com a definição do fluxo de trabalho.
O formato de arquivo .ps1 permite que você escreva menos "clichê" e se concentre apenas em escrever código do PowerShell. Se você renomear a ação, o arquivo também será renomeado, mas não vice-versa. 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 conseguirá localizar o arquivo e tentará criar um novo 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 KuduPlus e copie o script para reutilizar em outros fluxos de trabalho.
Limitações
| Nome | Limite | Notas |
|---|---|---|
| Duração da execução do script | 10 minutos | Se você tiver cenários que precisam de durações maiores, use a opção de feedback 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. |
Adicionar a ação Executar código do PowerShell
No portal do Azure, abra o recurso e o fluxo de trabalho do aplicativo lógico padrão no designer.
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 próprio código.
Para acessar dados provenientes do seu fluxo de trabalho, consulte Acessar gatilho de fluxo de trabalho e saídas de ação em seu script mais adiante neste guia.
Para retornar os resultados do script ou outros dados ao seu fluxo de trabalho, consulte Retornar dados ao seu fluxo de trabalho.
O exemplo a seguir mostra a guia Parâmetros da ação com o código de script de exemplo:
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 $customResponseO exemplo a seguir mostra um script de exemplo personalizado:
$action = Get-TriggerOutput $results = "Hello from PowerShell!" Push-WorkflowOutput -Output $resultsQuando terminar, salve seu fluxo de trabalho.
Depois de executar o fluxo de trabalho, você pode revisar a saída do fluxo de trabalho no Application Insights, se habilitado. Para obter mais informações, consulte Exibir saída no Application Insights.
Acesse o gatilho do 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, além de quaisquer 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
Nota
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 à ação
A tabela a seguir lista as saídas geradas quando você chama Get-ActionOutput ou Get-TriggerOutput. O valor de retorno é um objeto complexo chamado PowershellWorkflowOperationResult, que contém as seguintes saídas.
| Nome | Tipo | Description |
|---|---|---|
| Nome | Cadeia (de carateres) | O nome do gatilho ou ação. |
| Insumos | JToken | Os valores de entrada passados para o gatilho ou ação. |
| Saídas | JToken | As saídas do gatilho ou ação executada. |
| Horário de Início | DateTime | A hora de início do gatilho ou ação. |
| Tempo de Fim | DateTime | A hora de término do gatilho ou ação. |
| ScheduledTime | DateTime | A hora agendada para executar o gatilho ou ação ou gatilho. |
| OriginHistoryName | String | O nome do histórico de origem para gatilhos com a opção Split-On ativada. |
| SourceHistoryName | String | O nome do histórico de origem de um gatilho reenviado. |
| TrackingId | String | O ID de rastreamento da operação. |
| Código | String | O código de status do resultado. |
| Status | String | O status de execução do gatilho ou ação, por exemplo, Sucedido ou Reprovado. |
| Erro | JToken | O código de erro HTTP. |
| TrackedProperties | JToken | Todas as propriedades controladas configuradas. |
Retornar saídas para seu fluxo de trabalho
Para retornar quaisquer saídas ao seu fluxo de trabalho, você deve usar o cmdlet Push-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 | Description |
|---|---|---|
| Nome da ação | String | O nome da ação no fluxo de trabalho com a saída que você deseja referenciar. |
Push-WorkflowOutput
Envia a saída da ação Executar código do PowerShell para seu fluxo de trabalho, que pode repassar qualquer tipo de objeto. Se o valor de retorno for null, você obterá um erro de objeto nulo do cmdlet.
Nota
Os cmdlets Write-Debug, Write-Host e Write-Output não retornam valores ao seu fluxo de trabalho. A instrução return também não retorna valores para seu 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, consulte Microsoft.PowerShell.Utility.
Sintaxe
Push-WorkflowOutput [-Output <Object>] [-Clobber]
Parâmetros
| Parâmetro | Tipo | Description |
|---|---|---|
| Saída | Varia. | A saída que você deseja retornar ao fluxo de trabalho. Esta saída pode ter qualquer tipo. |
| Clobber | Varia. | Um parâmetro de switch opcional que você pode usar para substituir a saída enviada anteriormente. |
Autenticar e autorizar o acesso com uma identidade gerenciada usando o PowerShell
Com uma identidade gerenciada, seu recurso de aplicativo lógico e fluxo de trabalho podem autenticar e autorizar o acesso a qualquer serviço e recurso do Azure que ofereça 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 onde 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 de aplicativo lógico.
Para usar a identidade gerenciada de dentro da ação Executar código do PowerShell, você deve seguir estas etapas:
-
No recurso do Azure de destino, analise as seguintes considerações:
Na guia Função, uma função de Colaborador geralmente é suficiente.
Na página Adicionar atribuição de função, na guia Membros, para a propriedade Atribuir acesso a, certifique-se de selecionar Identidade gerenciada.
Depois de selecionar Selecionar membros, no painel Selecionar identidades gerenciadas, selecione a identidade gerenciada que deseja usar.
Em sua ação Executar código do PowerShell, inclua o seguinte código como a primeira instrução:
Connect-AzAccount -IdentityAgora, você pode trabalhar com o recurso do Azure usando cmdlets e módulos.
Exibir o arquivo de script
No portal do Azure, abra seu recurso de aplicativo lógico padrão que tem o fluxo de trabalho desejado.
No menu de recursos do aplicativo lógico, em Ferramentas de Desenvolvimento, selecione Ferramentas Avançadas.
Na página Ferramentas Avançadas, selecione Ir, que abre o console KuduPlus.
Abra o menu Depurar console e selecione CMD.
Vá para o local raiz do seu aplicativo lógico: site/wwwroot
Vá para a pasta do seu fluxo de trabalho, que contém o arquivo .ps1, ao longo deste caminho: site/wwwroot/{workflow-name}
Ao lado do nome do arquivo, selecione Editar para abrir e exibir o arquivo.
Exibir logs no Application Insights
No portal do Azure, no menu de recursos do aplicativo lógico, em Configurações, selecione Application Insights e selecione seu aplicativo lógico.
No menu Application Insights, em Monitoramento, selecione Logs.
Crie uma consulta para localizar quaisquer vestígios ou erros da execução do fluxo de trabalho, por exemplo:
union traces, errors | project TIMESTAMP, message
Módulos
Os módulos do PowerShell são unidades autônomas e reutilizáveis que incluem vários componentes, por exemplo:
- Cmdlets: comandos individuais que executam tarefas específicas.
- Provedores: permitem 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 próprios 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 encontrar módulos disponíveis publicamente, visite a galeria do PowerShell. Um recurso de aplicativo lógico padrão pode suportar até 10 módulos públicos. Para usar qualquer módulo público, você deve habilitar esse recurso seguindo estas etapas:
No portal do Azure, nos menus de recursos do aplicativo lógico, em Ferramentas de Desenvolvimento, selecione Ferramentas Avançadas.
Na página Ferramentas Avançadas, selecione Ir.
Na barra de ferramentas do Kudu Plus , no menu Depurar console , selecione CMD.
Navegue até o nível raiz do seu aplicativo lógico em C:\home\site\wwwroot usando a estrutura de diretórios ou a linha de comando.
Abra o arquivo host.json do fluxo de trabalho e defina a propriedade de dependência gerenciada como true, que já está definida por padrão.
"managedDependency": { "enabled": true }Abra o arquivo chamado 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 para módulos públicos
Se você usar o gerenciamento de dependência, as seguintes considerações se aplicam:
Para baixar módulos, os módulos públicos exigem acesso à Galeria do PowerShell.
Atualmente, as dependências gerenciadas não suportam módulos que exigem que você aceite uma licença, seja aceitando a licença interativamente ou fornecendo a opção -AcceptLicense quando você executa Install-Module.
Módulos privados
Você pode gerar seus próprios módulos privados do PowerShell. Para criar seu primeiro módulo do PowerShell, consulte Escrever um módulo de script do PowerShell.
No portal do Azure, no menu de recursos do aplicativo lógico, em Ferramentas de Desenvolvimento, selecione Ferramentas Avançadas.
Na página Ferramentas Avançadas, selecione Ir.
Na barra de ferramentas do Kudu Plus , no menu Depurar console , selecione CMD.
Navegue até o nível raiz do seu aplicativo lógico em C:\home\site\wwwroot usando a estrutura de diretórios ou a linha de comando.
Crie uma pasta chamada Modules.
Na pasta Módulos, crie uma subpasta com o mesmo nome do módulo privado.
Na pasta do módulo privado, adicione o arquivo de módulo privado do PowerShell com a extensão de nome de arquivo psm1 . Você também pode incluir um arquivo de manifesto do PowerShell opcional com a extensão de nome de arquivo psd1 .
Quando terminar, a estrutura completa do arquivo do aplicativo lógico será semelhante ao exemplo a seguir:
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 ao IntelliSense, que ainda está em melhoria. Quaisquer erros de compilação são detetados quando você salva seu fluxo de trabalho, e o tempo de execução dos Aplicativos Lógicos do Azure compila seu script. Esses erros aparecem nos logs de erros do seu aplicativo lógico por meio do Application Insights.
Erros de tempo de execução
Uma ação de fluxo de trabalho não retorna nenhuma saída.
Certifique-se de usar o cmdlet Push-WorkflowOutput .
A ação Executar código do PowerShell falha: "O termo '{some-text}' não é reconhecido..."
Se você fizer referência incorreta a um módulo público no arquivo requirements.psd1 ou quando o módulo privado não existir no seguinte 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.
Nota
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 descomentar o módulo.
A ação Executar código do PowerShell falha: "Não é possível vincular o argumento ao parâmetro 'Saída' porque ele é nulo."
Esse erro acontece quando você tenta enviar por push um objeto nulo para o fluxo de trabalho. Confirme se o objeto que você está enviando com Push-WorkflowOutput não é nulo.