Adición y ejecución de scripts de PowerShell con flujos de trabajo estándar en Azure Logic Apps

Se aplica a: Azure Logic Apps (Estándar)

Para realizar tareas de integración personalizadas insertadas con el flujo de trabajo Estándar en Azure Logic Apps, puede agregar y ejecutar directamente código de PowerShell desde el flujo de trabajo. Para esta tarea, use la acción de Código insertado denominada Ejecutar código de PowerShell. Esta acción devuelve los resultados desde el código de PowerShell para que pueda usar esa salida en las acciones posteriores del flujo de trabajo.

Esta funcionalidad proporciona las siguientes ventajas:

• Escriba scripts propios en el diseñador de flujos de trabajo para que pueda resolver desafíos de integración complejos. No es necesario ningún otro plan de servicio.

  Esta ventaja reduce la complejidad y el costo, ya que puede administrar más servicios y simplificar el desarrollo de flujos de trabajo.

• Genere un archivo de código dedicado, que proporciona un espacio de scripting personalizado dentro del flujo de trabajo.

• Integración con las funciones de PowerShell de Azure Functions, que proporciona una funcionalidad y herencia eficaces para la ejecución avanzada de tareas.

• Implemente scripts junto con los flujos de trabajo.

En esta guía se muestra cómo agregar la acción en el flujo de trabajo y agregar el código de PowerShell que quiere ejecutar.

Requisitos previos

• Una cuenta y una suscripción de Azure. Obtenga una cuenta gratuita de Azure.

• El recurso de aplicación lógica estándar con el flujo de trabajo donde quieres agregar el script de PowerShell.

  El flujo de trabajo ya debe comenzar con un desencadenador. Puede usar cualquier desencadenador para su escenario, pero como ejemplo, en esta guía se usa el desencadenador solicitud denominado Cuando se recibe una solicitud HTTP y también la acción Respuesta . El flujo de trabajo se ejecuta cuando otra aplicación o flujo de trabajo envía una solicitud a la dirección URL del punto de conexión del desencadenador. El script de ejemplo devuelve los resultados de la ejecución del código como salida que puede usar en acciones posteriores.

  Si no tiene un recurso de aplicación lógica y un flujo de trabajo, créelos ahora siguiendo estos pasos:

  • Creación de un flujo de trabajo de aplicación lógica estándar

Consideraciones

• Azure Portal guarda el script como un archivo de script de PowerShell (.ps1) en la misma carpeta que el archivo workflow.json, que almacena la definición JSON del flujo de trabajo e implementa el archivo en el recurso de la aplicación lógica junto con la definición de flujo de trabajo.

  El formato de archivo .ps1 le permite escribir menos "código repetitivo" y centrarse únicamente en escribir código PowerShell. Si cambia el nombre de la acción, también se cambia el nombre del archivo, pero no al contrario. Si cambia directamente el nombre del archivo, la versión cuyo nombre ha cambiado sobrescribe la versión anterior. Si el nombre de la acción y los nombres de archivo no coinciden, la acción no encuentra el archivo e intenta crear un archivo vacío.

• El script es local para el flujo de trabajo. Para usar el mismo script en otros flujos de trabajo, vea el archivo de script en la consola de Kudu y, a continuación, copie el script para reutilizarlo en otros flujos de trabajo.

Limitaciones

Actualización de la versión de PowerShell

Puede cambiar la versión de PowerShell en el recurso de aplicación lógica editando la configuración de la aplicación. Sin embargo, antes de actualizar la aplicación, revise las consideraciones siguientes:

• Una actualización de versión puede introducir cambios importantes en la aplicación lógica estándar, que usa un entorno de ejecución hospedado como una extensión en el entorno de ejecución de Azure Functions. Antes de actualizar, revise la siguiente guía de migración: Actualización de las aplicaciones de Azure Functions para que se ejecuten en PowerShell 7.4.

• Asegúrese de que la aplicación lógica usa la versión más reciente del entorno de ejecución de Azure Functions en Azure, que es la versión 4.x. Para obtener más información, consulte Visualización de la versión actual del entorno de ejecución.

En función de dónde quiera actualizar la versión de PowerShell, siga los pasos correspondientes:

Adición de la acción Ejecutar código de PowerShell

1. En el portal de Azure, abra el recurso de aplicación lógica estándar.

2. En la barra lateral del recurso, en Flujos de trabajo, seleccione Flujos de trabajo y, a continuación, seleccione el flujo de trabajo en blanco.

3. En la barra lateral del flujo de trabajo, en Herramientas, seleccione el diseñador para abrir el flujo de trabajo.

4. Agregue la acción Operaciones de código insertado denominada Ejecutar código de PowerShell al flujo de trabajo siguiendo los pasos generales para agregar una acción.

5. Una vez que se abra el panel de información de acción, en la pestaña Parámetros, en el cuadro Archivo de código, actualice el código de ejemplo rellenado previamente con código propio.

   • Para acceder a los datos procedentes del flujo de trabajo, vea Acceder a las salidas de acción y desencadenador de flujo de trabajo en el script más adelante en esta guía.

   • Para devolver los resultados del script u otros datos al flujo de trabajo, vea Devolución de datos al flujo de trabajo.

   En el ejemplo siguiente se muestra la pestaña Parámetros de la acción con el código de script de ejemplo:

   

   En el ejemplo siguiente se muestra el código de script de ejemplo:

   # 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
   

   En el ejemplo siguiente se muestra un script de ejemplo personalizado:

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

6. Cuando termine, guarde el flujo de trabajo.

Después de ejecutar el flujo de trabajo, puede revisar la salida del flujo de trabajo en Application Insights, si está habilitado. Para más información, vea Visualización de la salida en Application Insights.

Acceso a salidas de desencadenador y acción de flujo de trabajo en el script

Los valores de salida del desencadenador y las acciones anteriores se devuelven mediante un objeto personalizado, que tiene varios parámetros. Para acceder a estas salidas y asegurarse de devolver el valor que desee, use los cmdlets Get-TriggerOutput, Get-ActionOutput y Push-WorkflowOutput , además de los parámetros adecuados descritos en la tabla siguiente, por ejemplo:

$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

Salidas de los desencadenadores y la acción de respuesta

En la tabla siguiente se enumeran las salidas que se generan al llamar a Get-ActionOutput o Get-TriggerOutput. El valor devuelto es un objeto complejo denominado PowershellWorkflowOperationResult, que contiene las siguientes salidas.

Devolución de salidas al flujo de trabajo

Para devolver las salidas al flujo de trabajo, debe usar el cmdletPush-WorkflowOutput.

Comandos de PowerShell personalizados

La acción Ejecutar código de PowerShell incluye los siguientes comandos personalizados de PowerShell (cmdlets) para interactuar con el flujo de trabajo y otras operaciones del flujo de trabajo:

Get-TriggerOutput

Obtiene la salida del desencadenador del flujo de trabajo.

Sintaxis

Get-TriggerOutput

Parámetros

ninguno.

Get-ActionOutput

Obtiene la salida de otra acción del flujo de trabajo y devuelve un objeto denominado PowershellWorkflowOperationResult.

Sintaxis

Get-ActionOutput [ -ActionName <String> ]

Parámetros

Push-WorkflowOutput

Inserta la salida de la acción Ejecutar código de PowerShell en el flujo de trabajo, lo que puede devolver cualquier tipo de objeto. Si el valor devuelto es null, obtendrá un error de objeto null del cmdlet.

Sintaxis

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

Parámetros

Autenticación y autorización del acceso con una identidad administrada mediante PowerShell

Con una identidad administrada, el recurso de aplicación lógica y el flujo de trabajo pueden autenticar y autorizar el acceso a cualquier servicio y recurso de Azure que admita la autenticación de Microsoft Entra sin incluir credenciales en el código.

Desde dentro de la acción Ejecutar código de PowerShell, puede autenticar y autorizar el acceso con una identidad administrada para que pueda realizar acciones en otros recursos de Azure donde ha habilitado el acceso. Por ejemplo, puede reiniciar una máquina virtual u obtener los detalles de ejecución de otro flujo de trabajo de aplicación lógica.

Para usar la identidad administrada desde dentro de la acción Ejecutar código de PowerShell, debe seguir estos pasos:

1. Configure la identidad administrada en la aplicación lógica y conceda acceso a la identidad administrada en el recurso de Azure de destino. Para conocer los pasos detallados, consulte Autenticación del acceso y las conexiones a recursos de Azure con identidades administradas.

   En el recurso de Azure de destino, revise las consideraciones siguientes:

   • En la pestaña Rol, un rol de Colaborador suele ser suficiente.

   • En la página Agregar asignación de roles, en la pestaña Miembros, en la propiedad Asignar acceso a, asegúrese de seleccionar Identidad administrada.

   • Después de seleccionar Seleccionar miembros, en el panel Seleccionar identidades administradas, seleccione la identidad administrada que quiera usar.

2. En la acción Ejecutar código de PowerShell, incluya el código siguiente como primera instrucción:

   Connect-AzAccount -Identity
   

3. Ahora, puede trabajar con el recurso de Azure mediante cmdlets y módulos.

Visualización del archivo de script

1. En el portal de Azure, abra el recurso de aplicación lógica estándar.

2. En la barra lateral del recurso, en Herramientas de desarrollo, seleccione Herramientas avanzadas.

3. En la página Herramientas avanzadas , seleccione Ir, que abre la consola de Kudu .

4. Abra el menú Consola de depuración y seleccione CMD.

5. Vaya a la ubicación raíz de la aplicación lógica: sitio/wwwroot

6. Vaya a la carpeta del flujo de trabajo, que contiene el archivo con la extensión .ps1 a lo largo de esta ruta de acceso: site/wwwroot/{workflow-name}

7. Junto al nombre de archivo, seleccione Editar para abrir y ver el archivo.

Visualización de registros en Application Insights

1. En Azure Portal, en la barra lateral de la aplicación lógica, en Supervisión, seleccione Application Insights (no Insights).

2. Seleccione el vínculo al recurso de Application Insights.

3. En la barra lateral del recurso de Application Insights , en Supervisión, seleccione Registros.

4. Cree una consulta para buscar los seguimientos o errores de la ejecución del flujo de trabajo, por ejemplo:

   union traces, errors
   | project TIMESTAMP, message
   

Módulos

Los módulos de PowerShell son unidades autocontenidas y reutilizables que incluyen varios componentes, por ejemplo los siguientes:

• Cmdlets: comandos individuales que realizan tareas específicas.
• Proveedores: permiten el acceso a almacenes de datos, como el Registro o el sistema de archivos, como si fueran unidades.
• Funciones: bloques de código reutilizables que realizan acciones específicas.
• Variables: almacenan datos para usarlos en el módulo.
• Otro tipos de recursos.

Un módulo organiza el código de PowerShell, lo que facilita su distribución. Por ejemplo, puede crear módulos propios para empaquetar y hacer que la funcionalidad relacionada sea más fácil de administrar y compartir. La acción Ejecutar código de PowerShell le permite importar módulos de PowerShell públicos y privados.

Módulos públicos

Para buscar módulos disponibles públicamente, visite la galería de PowerShell. Un recurso de aplicación lógica Estándar puede admitir hasta 10 módulos públicos. Para usar cualquier módulo público, debe seguir estos pasos para habilitar esta funcionalidad:

1. En Azure Portal, en la barra lateral de la aplicación lógica, en Herramientas de desarrollo, seleccione Herramientas avanzadas.

2. En la página Herramientas avanzadas, seleccione Ir.

3. En la barra de herramientas de Kudu, abra el menú Consola de depuración y seleccione CMD.

4. Vaya al nivel raíz de la aplicación lógica en C:\home\site\wwwroot mediante la estructura de directorios o la línea de comandos.

5. Abra el archivo host.json del flujo de trabajo y establezca la propiedad ManagedDependency.enabled a true, que ya está configurada de forma predeterminada.

   "managedDependency": {
       "enabled": true
   }
   

6. Abra el archivo denominado requirements.psd1. Incluya el nombre y la versión del módulo que desee mediante la sintaxis siguiente: MajorNumber.* o la versión exacta del módulo, por ejemplo:

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

Consideraciones para los módulos públicos

Si usa la administración de dependencias, se aplican las siguientes consideraciones:

• Para descargar módulos, los módulos públicos necesitan acceso a la galería de PowerShell.

• Actualmente, las dependencias administradas no admiten módulos que requieren que acepte una licencia, ya sea aceptando la licencia de forma interactiva o proporcionando la -AcceptLicense opción al ejecutar Install-Module.

Módulos privados

Puede generar módulos privados de PowerShell propios. Para crear el primer módulo de PowerShell, vea Escritura de un módulo de script de PowerShell.

1. En Azure Portal, en las barras laterales del recurso de la aplicación lógica, en Herramientas de desarrollo, seleccione Herramientas avanzadas.

2. En la página Herramientas avanzadas, seleccione Ir.

3. En la barra de herramientas de Kudu, abra el menú Consola de depuración y seleccione CMD.

4. Vaya al nivel raíz de la aplicación lógica en C:\home\site\wwwroot mediante la estructura de directorios o la línea de comandos.

5. Cree una carpeta con el nombre Módulos.

6. En la carpeta Módulos, cree una subcarpeta con el mismo nombre que el módulo privado.

7. En la carpeta del módulo privado, agregue el archivo de módulo privado de PowerShell con la extensión .psm1 . También puede incluir un archivo de manifiesto de PowerShell opcional con la extensión .psd1 .

Cuando haya terminado, la estructura de archivos de aplicación lógica completa será similar a la del ejemplo siguiente:

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

Errores de compilación

En esta versión, el editor basado en web incluye compatibilidad limitada con IntelliSense, que todavía está en mejora. Se detectan errores de compilación al guardar el flujo de trabajo y el entorno de ejecución de Azure Logic Apps compila el script. Estos errores aparecen en los registros de errores de su aplicación lógica a través de Application Insights.

Errores de tiempo de ejecución

Una acción de flujo de trabajo no devuelve ninguna salida.

Asegúrese de usar el Push-WorkflowOutput cmdlet .

Se produce un error en la acción Ejecutar código de PowerShell: "El término "{un-texto}" no se reconoce..."

Si hace referencia incorrectamente a un módulo público en el archivo requirements.psd1 , o si el módulo privado no existe en la ruta de acceso C:\home\site\wwwroot\Modules{module-name}, obtendrá el siguiente error:

"El término '{some-text}' no se reconoce como un nombre de un cmdlet, una función, un archivo de script o un programa ejecutable. Compruebe la ortografía del nombre o si se incluyó una ruta de acceso, compruebe que la ruta de acceso es correcta e inténtelo de nuevo".

Se produce un error en la acción Ejecutar código de PowerShell: "No se puede enlazar el argumento del parámetro "Output" porque es null".

Este error se produce cuando se intenta insertar un objeto null en el flujo de trabajo. Confirme que el objeto que está enviando con Push-WorkflowOutput no es nulo.

Contenido relacionado

• Adición y ejecución de fragmentos de código de JavaScript
• Adición y ejecución de scripts de C#