Adicionar e executar o código de script do PowerShell em fluxos de trabalho Standard para Aplicativos Lógicos do Azure (versão prévia)
Aplica-se a: Aplicativos Lógicos do Azure (Standard)
Observação
Esse recurso está em versão prévia e está sujeito aos Termos de uso suplementares para versões prévias do Microsoft Azure.
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 simplifica o desenvolvimento de 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 oferece um espaço personalizado para scripts dentro do seu fluxo de trabalho.
Integre-se às Funções do PowerShell do Azure Functions, que fornece 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. Se você não tem uma assinatura, inscreva-se em uma conta gratuita do Azure.
O fluxo de trabalho do aplicativo lógico Standard ao qual você deseja adicionar seu script do PowerShell. O fluxo de trabalho já precisa começar com um gatilho. Para obter mais informações, consulte Criar exemplos de fluxos de trabalho do aplicativo lógico Standard.
Você pode usar qualquer gatilho para seu cenário, mas, como exemplo, este guia usa o gatilho Solicitar 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.
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 clichê" e concentre-se apenas em escrever um código do 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 KuduPlus e copie o script para reutilizá-lo em outros fluxos de trabalho.
Limitações
| Nome | Limit | 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. |
Adicionar a ação Executar Código do PowerShell
No portal do Azure, abra o recurso de aplicativo lógico Standard e o fluxo de trabalho 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 código.
Para acessar dados provenientes do fluxo de trabalho, consulte Acessar o gatilho de fluxo de trabalho e as saídas de ação no script mais adiante neste guia.
Para retornar os resultados do script ou outros dados ao fluxo de trabalho, confira Retornar dados ao 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 seguinte exemplo mostra um script de exemplo personalizado:
$action = Get-TriggerOutput $results = "Hello from PowerShell!" Push-WorkflowOutput -Output $resultsQuando 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 seguinte tabela, 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 | String | 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 | String | O nome do histórico de origem para gatilhos com a opção Split-On habilitada. |
| SourceHistoryName | String | O nome do histórico de origem de um gatilho reenviado. |
| TrackingId | String | A 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 da ação, por exemplo, Êxito ou Falha. |
| Erro | JToken | O código de erro HTTP. |
| TrackedProperties | JToken | Todas as propriedades rastreadas que você configurou. |
Retornar saídas ao fluxo de trabalho
Para retornar quaisquer saídas para o fluxo de trabalho, você precisa 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 | Descrição |
|---|---|---|
| ActionName | String | 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-Hoste Write-Output não retornam valores ao fluxo de trabalho. A instrução return 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:
-
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.
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 o recurso de aplicativo lógico Standard que tem o fluxo de trabalho desejado.
No menu do aplicativo lógico, acesse Ferramentas de Desenvolvimento e selecione Ferramentas Avançadas.
Na página Ferramentas Avançadas, selecione Ir, que abrirá o console do KuduPlus.
Abra o menu Depurar console e selecione CMD.
Vá para o local da raiz do aplicativo lógico: site/wwwroot
Vá para a pasta do fluxo de trabalho, que contém o arquivo .ps1, neste caminho: site/wwwroot/{nome-do-fluxo-de-trabalho}
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, em seguida, escolha o seu aplicativo lógico.
No menu Application Insights, em Monitoramento, selecione Logs.
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:
No portal do Azure, nos menus de recursos de aplicativo lógico, em Ferramentas de Desenvolvimento, selecione Ferramentas Avançadas.
Na página Ferramentas avançadas, selecione Go.
Na barra de ferramentas do Kudu Plus, a partir do menu do Console de depuração, selecione CMD.
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.
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 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.
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 Go.
Na barra de ferramentas do Kudu Plus, a partir do menu do Console de depuração, selecione CMD.
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.
Crie uma pasta chamada Módulos.
Na pasta Módulos, crie uma subpasta com o mesmo nome do módulo privado.
Na pasta de 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 opcional do PowerShell com a extensão de nome de arquivo 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 de runtime
Uma ação de fluxo de trabalho não retorna nenhuma saída.
Certifique-se de usar o cmdlet Push-WorkflowOutput.
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 quando o módulo privado não existir no seguinte caminho: C:\home\site\wwwroot\Modules{nome-do-módulo}, você receberá o seguinte erro:
O termo '{algum-texto}' 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 ele 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.