Guía del desarrollador de PowerShell para Azure FunctionsAzure Functions PowerShell developer guide

En este artículo se proporcionan detalles sobre cómo escribir en Azure Functions con PowerShell.This article provides details about how you write Azure Functions using PowerShell.

Una función de Azure de PowerShell (función) se representa como un script de PowerShell que se ejecuta cuando se desencadena.A PowerShell Azure function (function) is represented as a PowerShell script that executes when triggered. Cada script de función tiene un archivo function.json relacionado donde se define el comportamiento de la función, como su desencadenamiento y sus parámetros de entrada y salida.Each function script has a related function.json file that defines how the function behaves, such as how it's triggered and its input and output parameters. Para más información, consulte el artículo sobre los desencadenadores y los enlaces.To learn more, see the Triggers and binding article.

Al igual que otros tipos de funciones, las funciones de script de PowerShell toman parámetros que coinciden con los nombres de todos los enlaces de entrada definidos en el archivo function.json.Like other kinds of functions, PowerShell script functions take in parameters that match the names of all the input bindings defined in the function.json file. También se pasa un parámetro TriggerMetadata que contiene información adicional sobre el desencadenador que inició la función.A TriggerMetadata parameter is also passed that contains additional information on the trigger that started the function.

En este artículo se supone que ya ha leído Referencia para desarrolladores de Azure Functions.This article assumes that you have already read the Azure Functions developer reference. Debe haber completado también el inicio rápido de Functions para PowerShell para crear su primera función de PowerShell.You should have also completed the Functions quickstart for PowerShell to create your first PowerShell function.

Estructura de carpetasFolder structure

La estructura de carpetas necesaria para un proyecto de PowerShell tiene el siguiente aspecto.The required folder structure for a PowerShell project looks like the following. Este valor predeterminado se puede cambiar.This default can be changed. Para más información, consulte la sección scriptFile a continuación.For more information, see the scriptFile section below.

PSFunctionApp
 | - MyFirstFunction
 | | - run.ps1
 | | - function.json
 | - MySecondFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - myFirstHelperModule
 | | | - myFirstHelperModule.psd1
 | | | - myFirstHelperModule.psm1
 | | - mySecondHelperModule
 | | | - mySecondHelperModule.psd1
 | | | - mySecondHelperModule.psm1
 | - local.settings.json
 | - host.json
 | - requirements.psd1
 | - profile.ps1
 | - extensions.csproj
 | - bin

En la raíz del proyecto, hay un archivo host.json compartido que se puede usar para configurar la aplicación de función.At the root of the project, there's a shared host.json file that can be used to configure the function app. Cada función tiene una carpeta con su propio archivo de código (.ps1) y archivo de configuración de enlace (function.json).Each function has a folder with its own code file (.ps1) and binding configuration file (function.json). El nombre del directorio primario del archivo function.json es siempre es el nombre de la función.The name of the function.json file's parent directory is always the name of your function.

Determinados enlaces requieren la presencia de un archivo extensions.csproj.Certain bindings require the presence of an extensions.csproj file. Las extensiones de enlace necesarias en la versión 2.x y posteriores del entorno en tiempo de ejecución de Functions se definen en el archivo extensions.csproj, con los archivos de biblioteca reales de la carpeta bin.Binding extensions, required in version 2.x and later versions of the Functions runtime, are defined in the extensions.csproj file, with the actual library files in the bin folder. Al desarrollar de forma local, debe registrar las extensiones de enlace.When developing locally, you must register binding extensions. Al desarrollar funciones en Azure Portal, este registro se realiza automáticamente.When developing functions in the Azure portal, this registration is done for you.

En las aplicaciones de funciones de PowerShell, podría tener opcionalmente un profile.ps1 que se ejecute cuando una aplicación de funciones empiece a ejecutarse (lo que también se conoce como arranque en frío .In PowerShell Function Apps, you may optionally have a profile.ps1 which runs when a function app starts to run (otherwise know as a cold start. Para más información, consulte el Perfil de PowerShell.For more information, see PowerShell profile.

Definición de un script de PowerShell como funciónDefining a PowerShell script as a function

De forma predeterminada, el tiempo de ejecución de Functions busca la función en run.ps1, donde run.ps1 comparte el mismo directorio primario que su function.json correspondiente.By default, the Functions runtime looks for your function in run.ps1, where run.ps1 shares the same parent directory as its corresponding function.json.

Varios argumentos se pasan al script durante la ejecución.Your script is passed a number of arguments on execution. Para controlar estos parámetros, agregue un bloque param a la parte superior del script como en el siguiente ejemplo:To handle these parameters, add a param block to the top of your script as in the following example:

# $TriggerMetadata is optional here. If you don't need it, you can safely remove it from the param block
param($MyFirstInputBinding, $MySecondInputBinding, $TriggerMetadata)

Parámetro TriggerMetadataTriggerMetadata parameter

El parámetro TriggerMetadata se usa para proporcionar información adicional acerca del desencadenador.The TriggerMetadata parameter is used to supply additional information about the trigger. Los metadatos adicionales varían de un enlace a otro, pero todos ellos contienen una propiedad sys con los siguientes datos:The additional metadata varies from binding to binding but they all contain a sys property that contains the following data:

$TriggerMetadata.sys
PropiedadProperty DescripciónDescription TipoType
UtcNowUtcNow Cuándo se desencadenó la función (en formato UTC)When, in UTC, the function was triggered DateTimeDateTime
MethodNameMethodName Nombre de la función desencadenadaThe name of the Function that was triggered stringstring
RandGuidRandGuid GUID único para esta ejecución de la funcióna unique guid to this execution of the function stringstring

Cada tipo de desencadenador tiene un conjunto diferente de metadatos.Every trigger type has a different set of metadata. Por ejemplo, $TriggerMetadata para QueueTrigger contiene InsertionTime, Id y DequeueCount, entre otras cosas.For example, the $TriggerMetadata for QueueTrigger contains the InsertionTime, Id, DequeueCount, among other things. Para más información sobre los metadatos del desencadenador de cola, vaya a la documentación oficial de los desencadenadores de cola.For more information on the queue trigger's metadata, go to the official documentation for queue triggers. Consulte la documentación sobre los desencadenadores con los que está trabajando para ver lo que está incluido en los metadatos de desencadenador.Check the documentation on the triggers you're working with to see what comes inside the trigger metadata.

EnlacesBindings

En PowerShell, los enlaces se configuran y definen en el archivo function.json de una función.In PowerShell, bindings are configured and defined in a function's function.json. Las funciones interactúan con los enlaces de varias maneras.Functions interact with bindings a number of ways.

Lectura de datos del desencadenador y de entradaReading trigger and input data

Los desencadenadores y los enlaces de entrada se leen como parámetros que se pasan a la función.Trigger and input bindings are read as parameters passed to your function. Los enlaces de entrada tienen un direction establecido en in en function.json.Input bindings have a direction set to in in function.json. La propiedad name definida en function.json es el nombre del parámetro, en el bloque param.The name property defined in function.json is the name of the parameter, in the param block. Dado que PowerShell utiliza parámetros con nombre para el enlace, no importa el orden de estos.Since PowerShell uses named parameters for binding, the order of the parameters doesn't matter. Sin embargo, es un procedimiento recomendado seguir el orden de los enlaces definidos en el archivo function.json.However, it's a best practice to follow the order of the bindings defined in the function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

Escritura de datos de salidaWriting output data

En Functions, un enlace de salida tiene un direction establecido en out en el archivo function.json.In Functions, an output binding has a direction set to out in the function.json. Puede escribir en un enlace de salida mediante el cmdlet Push-OutputBinding, disponible para Functions Runtime.You can write to an output binding by using the Push-OutputBinding cmdlet, which is available to the Functions runtime. En cualquier caso, la propiedad name del enlace tal como se define en function.json corresponde al parámetro Name del cmdlet Push-OutputBinding.In all cases, the name property of the binding as defined in function.json corresponds to the Name parameter of the Push-OutputBinding cmdlet.

A continuación se muestra cómo llamar a Push-OutputBinding en el script de la función:The following shows how to call Push-OutputBinding in your function script:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

También puede pasar un valor para un enlace específico mediante la canalización.You can also pass in a value for a specific binding through the pipeline.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

Push-OutputBinding se comporta de forma distinta según el valor especificado para -Name:Push-OutputBinding behaves differently based on the value specified for -Name:

  • Cuando no se puede resolver el nombre especificado en un enlace de salida válido, se produce un error.When the specified name cannot be resolved to a valid output binding, then an error is thrown.

  • Cuando el enlace de salida acepta una colección de valores, puede llamar a Push-OutputBinding varias veces para insertar varios valores.When the output binding accepts a collection of values, you can call Push-OutputBinding repeatedly to push multiple values.

  • Cuando el enlace de salida solo acepta un valor singleton, volver a llamar aPush-OutputBinding produce un error.When the output binding only accepts a singleton value, calling Push-OutputBinding a second time raises an error.

Sintaxis de Push-OutputBindingPush-OutputBinding syntax

Los siguientes son parámetros válidos para llamar a Push-OutputBinding:The following are valid parameters for calling Push-OutputBinding:

NombreName TipoType PosiciónPosition DescripciónDescription
-Name StringString 11 Nombre del enlace de salida que quiere establecer.The name of the output binding you want to set.
-Value ObjectObject 22 Valor del enlace de salida que desea establecer, aceptado desde la canalización ByValue.The value of the output binding you want to set, which is accepted from the pipeline ByValue.
-Clobber SwitchParameterSwitchParameter con nombreNamed (Opcional) Cuando se especifica, se fuerza el establecimiento del valor para un enlace de salida especificado.(Optional) When specified, forces the value to be set for a specified output binding.

También se admiten los siguientes parámetros habituales:The following common parameters are also supported:

  • Verbose
  • Debug
  • ErrorAction
  • ErrorVariable
  • WarningAction
  • WarningVariable
  • OutBuffer
  • PipelineVariable
  • OutVariable

Para más información, consulte About Common Parameters (Acerca de los parámetros habituales).For more information, see About CommonParameters.

Ejemplo de Push-OutputBinding: Respuestas HTTPPush-OutputBinding example: HTTP responses

Un desencadenador HTTP devuelve una respuesta con un enlace de salida denominado response.An HTTP trigger returns a response using an output binding named response. En el siguiente ejemplo, el enlace de salida de response tiene el valor de "output #1":In the following example, the output binding of response has the value of "output #1":

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #1"
})

Dado que la salida es HTTP, que acepta solo un valor singleton, al volver a llamar a Push-OutputBinding se produce un error.Because the output is to HTTP, which accepts a singleton value only, an error is thrown when Push-OutputBinding is called a second time.

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #2"
})

Para las salidas que solo aceptan valores singleton, puede usar el parámetro -Clobber para invalidar el antiguo valor en lugar de intentar agregarlo a una colección.For outputs that only accept singleton values, you can use the -Clobber parameter to override the old value instead of trying to add to a collection. En el siguiente ejemplo se da por supuesto que ya ha agregado un valor.The following example assumes that you have already added a value. Mediante el uso de -Clobber, la respuesta de ejemplo siguiente invalida el valor existente para devolver un valor de "output #3":By using -Clobber, the response from the following example overrides the existing value to return a value of "output #3":

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #3"
}) -Clobber

Ejemplo de Push-OutputBinding: Enlace de salida de colaPush-OutputBinding example: Queue output binding

Push-OutputBinding se usa para enviar datos a los enlaces de salida como enlace de salida de Azure Queue Storage.Push-OutputBinding is used to send data to output bindings, such as an Azure Queue storage output binding. En el siguiente ejemplo, el mensaje que se escribe en la cola tiene un valor de "output #1":In the following example, the message written to the queue has a value of "output #1":

PS >Push-OutputBinding -Name outQueue -Value "output #1"

El enlace de salida para una cola de Storage acepta varios valores de salida.The output binding for a Storage queue accepts multiple output values. En este caso, llamar al siguiente ejemplo después del primero hace que se escriba en la cola una lista con dos elementos: "output #1" y "output #2".In this case, calling the following example after the first writes to the queue a list with two items: "output #1" and "output #2".

PS >Push-OutputBinding -Name outQueue -Value "output #2"

Cuando se llama al siguiente ejemplo después de los dos anteriores, se agregan dos valores más a la colección de salida:The following example, when called after the previous two, adds two more values to the output collection:

PS >Push-OutputBinding -Name outQueue -Value @("output #3", "output #4")

Cuando se escribe en la cola, el mensaje contiene estos cuatro valores: "output #1", "output #2", "output #3" y "output #4".When written to the queue, the message contains these four values: "output #1", "output #2", "output #3", and "output #4".

cmdlet Get-OutputBindingGet-OutputBinding cmdlet

Puede usar el cmdlet Get-OutputBinding para recuperar los valores establecidos actualmente para los enlaces de salida.You can use the Get-OutputBinding cmdlet to retrieve the values currently set for your output bindings. Este cmdlet recupera una tabla hash que contiene los nombres de los enlaces de salida con sus respectivos valores.This cmdlet retrieves a hashtable that contains the names of the output bindings with their respective values.

El siguiente es un ejemplo del uso de Get-OutputBinding para devolver valores de enlace actuales:The following is an example of using Get-OutputBinding to return current binding values:

Get-OutputBinding
Name                           Value
----                           -----
MyQueue                        myData
MyOtherQueue                   myData

Get-OutputBinding también contiene un parámetro denominado -Name que se puede usar para filtrar el enlace devuelto, como en el siguiente ejemplo:Get-OutputBinding also contains a parameter called -Name, which can be used to filter the returned binding, as in the following example:

Get-OutputBinding -Name MyQ*
Name                           Value
----                           -----
MyQueue                        myData

En Get-OutputBinding se admiten caracteres comodín (*).Wildcards (*) are supported in Get-OutputBinding.

RegistroLogging

El inicio de sesión en las funciones de PowerShell funciona como el inicio de sesión normal de PowerShell.Logging in PowerShell functions works like regular PowerShell logging. Puede usar los cmdlets de registro para escribir en cada flujo de salida.You can use the logging cmdlets to write to each output stream. Cada cmdlet se asigna a un nivel de registro utilizado por Functions.Each cmdlet maps to a log level used by Functions.

Nivel de registro de FunctionsFunctions logging level cmdlet de registroLogging cmdlet
ErrorError Write-Error
AdvertenciaWarning Write-Warning
InformationInformation Write-Information
Write-Host
Write-Output
InformationInformation Escribe en nivel Información de registro.Writes to Information level logging.
DepurarDebug Write-Debug
SeguimientoTrace Write-Progress
Write-Verbose

Además de estos cmdlets, todo lo escrito en la canalización se redirige al nivel de registro Information y se muestra con el formato predeterminado de PowerShell.In addition to these cmdlets, anything written to the pipeline is redirected to the Information log level and displayed with the default PowerShell formatting.

Importante

El uso de los cmdlets Write-Verbose o Write-Debug no es suficiente para ver los niveles de registro detallado y de depuración.Using the Write-Verbose or Write-Debug cmdlets is not enough to see verbose and debug level logging. También debe configurar el umbral de nivel de registro que declara qué nivel de registro es realmente importante para usted.You must also configure the log level threshold, which declares what level of logs you actually care about. Para más información, consulte el artículo de Configuración del nivel de registro de la aplicación de funciones.To learn more, see Configure the function app log level.

Configuración del nivel de registro de la aplicación de funcionesConfigure the function app log level

Azure Functions permite definir el nivel umbral para facilitar el control de la manera en que Functions escribe en los registros.Azure Functions lets you define the threshold level to make it easy to control the way Functions writes to the logs. Para establecer el umbral para todos los seguimientos que se escriben en la consola, use la propiedad logging.logLevel.default en el host.jsonarchivo host.json.To set the threshold for all traces written to the console, use the logging.logLevel.default property in the host.json file. Esta configuración se aplica a todas las funciones de Function App.This setting applies to all functions in your function app.

En el siguiente ejemplo se establece el umbral para habilitar el registro detallado para todas las funciones, pero establece el umbral para habilitar el registro de depuración para una función denominada MyFunction:The following example sets the threshold to enable verbose logging for all functions, but sets the threshold to enable debug logging for a function named MyFunction:

{
    "logging": {
        "logLevel": {
            "Function.MyFunction": "Debug",
            "default": "Trace"
        }
    }
}  

Para más información, consulte la Referencia de host.json.For more information, see host.json reference.

Visualización de los registrosViewing the logs

Si la aplicación de funciones se ejecuta en Azure, puede usar Application Insights para supervisarla.If your Function App is running in Azure, you can use Application Insights to monitor it. Consulte cómo supervisar Azure Functions para obtener más información sobre cómo ver y consultar registros de la función.Read monitoring Azure Functions to learn more about viewing and querying function logs.

Si la aplicación de funciones se ejecuta localmente para el desarrollo, los registros están de manera predeterminada en el sistema de archivos.If you're running your Function App locally for development, logs default to the file system. Para ver los registros en la consola, establezca la variable de entorno AZURE_FUNCTIONS_ENVIRONMENT en Development antes de iniciar la aplicación de funciones.To see the logs in the console, set the AZURE_FUNCTIONS_ENVIRONMENT environment variable to Development before starting the Function App.

Tipos de desencadenadores y enlacesTriggers and bindings types

Hay varios desencadenadores y enlaces disponibles para usar con la aplicación de funciones.There are a number of triggers and bindings available to you to use with your function app. La lista completa de los desencadenadores y enlaces se encuentra aquí.The full list of triggers and bindings can be found here.

Todos los desencadenadores y enlaces se representan en código como tipos de datos reales:All triggers and bindings are represented in code as a few real data types:

  • HashtableHashtable
  • stringstring
  • byte[]byte[]
  • intint
  • doubledouble
  • HttpRequestContextHttpRequestContext
  • HttpResponseContextHttpResponseContext

Los cinco primeros tipos de esta lista son tipos de .NET estándar.The first five types in this list are standard .NET types. Los dos últimos los usa únicamente el desencadenador HttpTrigger.The last two are used only by the HttpTrigger trigger.

Todos los parámetros de enlace de las funciones deben ser de uno de estos tipos.Each binding parameter in your functions must be one of these types.

Desencadenadores y enlaces HTTPHTTP triggers and bindings

Los desencadenadores HTTP y de webhook trigger y los enlaces de salida HTTP usan objetos de solicitud y respuesta para representar la mensajería HTTP.HTTP and webhook triggers and HTTP output bindings use request and response objects to represent the HTTP messaging.

Objeto de solicitudRequest object

El objeto de solicitud que se pasa al script es del tipo HttpRequestContext, con las siguientes propiedades:The request object that's passed into the script is of the type HttpRequestContext, which has the following properties:

PropiedadProperty DescripciónDescription TipoType
Body Objeto que contiene el cuerpo de la solicitud.An object that contains the body of the request. Body se serializa al mejor tipo en función de los datos.Body is serialized into the best type based on the data. Por ejemplo, si los datos son JSON, se pasa como tabla hash.For example, if the data is JSON, it's passed in as a hashtable. Si los datos están una cadena, se pasan en forma de cadena.If the data is a string, it's passed in as a string. objectobject
Headers Diccionario que contiene los encabezados de la solicitud.A dictionary that contains the request headers. Diccionario<cadena,cadena>*Dictionary<string,string>*
Method Método HTTP de la solicitud.The HTTP method of the request. stringstring
Params Objeto que contiene los parámetros de enrutamiento de la solicitud.An object that contains the routing parameters of the request. Diccionario<cadena,cadena>*Dictionary<string,string>*
Query Objeto que contiene los parámetros de consulta.An object that contains the query parameters. Diccionario<cadena,cadena>*Dictionary<string,string>*
Url Dirección URL de la solicitud.The URL of the request. stringstring

*Todas las claves Dictionary<string,string> distinguen mayúsculas de minúsculas.* All Dictionary<string,string> keys are case-insensitive.

Objeto de respuestaResponse object

El objeto de respuesta que debe enviar de vuelta es de tipo HttpResponseContext, que tiene las siguientes propiedades:The response object that you should send back is of the type HttpResponseContext, which has the following properties:

PropiedadProperty DescripciónDescription TipoType
Body Objeto que contiene el cuerpo de la respuesta.An object that contains the body of the response. objectobject
ContentType Una mano corta para establecer el tipo de contenido para la respuesta.A short hand for setting the content type for the response. stringstring
Headers Objeto que contiene los encabezados de la respuesta.An object that contains the response headers. Diccionario o tabla hashDictionary or Hashtable
StatusCode Código de estado HTTP de la respuesta.The HTTP status code of the response. cadena o enterostring or int

Acceso a solicitudes y respuestasAccessing the request and response

Al trabajar con desencadenadores HTTP, puede acceder a la solicitud HTTP del mismo modo que lo haría con cualquier otro enlace de entrada.When you work with HTTP triggers, you can access the HTTP request the same way you would with any other input binding. Se encuentra en el bloque param.It's in the param block.

Use un objeto HttpResponseContext para devolver una respuesta, tal como se muestra a continuación:Use an HttpResponseContext object to return a response, as shown in the following:

function.json

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "anonymous"
    },
    {
      "type": "http",
      "direction": "out"
    }
  ]
}

run.ps1

param($req, $TriggerMetadata)

$name = $req.Query.Name

Push-OutputBinding -Name res -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "Hello $name!"
})

El resultado de invocar esta función sería:The result of invoking this function would be:

PS > irm http://localhost:5001?Name=Functions
Hello Functions!

Conversión de tipos de desencadenadores y enlacesType-casting for triggers and bindings

Para determinados enlaces como el enlace de blobs, podrá especificar el tipo del parámetro.For certain bindings like the blob binding, you're able to specify the type of the parameter.

Por ejemplo, para que los datos de Blob Storage se proporcionen como cadena, agregue la siguiente conversión de tipo de mi bloque param:For example, to have data from Blob storage supplied as a string, add the following type cast to my param block:

param([string] $myBlob)

Perfil de PowerShellPowerShell profile

En PowerShell, existe el concepto de "perfil de PowerShell".In PowerShell, there's the concept of a PowerShell profile. Si no está familiarizado con los perfiles de PowerShell, consulte About profiles (Acerca de los perfiles).If you're not familiar with PowerShell profiles, see About profiles.

En las funciones de PowerShell, el script de perfil se ejecuta una vez por instancia de trabajo de PowerShell en la aplicación cuando se implementa por primera vez y después de estar inactivo (arranque en frío.In PowerShell Functions, the profile script is executed once per PowerShell worker instance in the app when first deployed and after being idled (cold start. Cuando se habilita la simultaneidad estableciendo el valor PSWorkerInProcConcurrencyUpperBound, el script de perfil se ejecuta para cada espacio de ejecución creado.When concurrency is enabled by setting the PSWorkerInProcConcurrencyUpperBound value, the profile script is run for each runspace created.

Al crear una aplicación de funciones con herramientas como Visual Studio Code y Azure Functions Core Tools, el profile.ps1 predeterminado se crea automáticamente.When you create a function app using tools, such as Visual Studio Code and Azure Functions Core Tools, a default profile.ps1 is created for you. El perfil predeterminado se mantiene en el repositorio de GitHub de Core Tools y contiene:The default profile is maintained on the Core Tools GitHub repository and contains:

  • La autenticación automática de MSI en Azure.Automatic MSI authentication to Azure.
  • La capacidad de activar los alias de PowerShell para AzureRM de Azure PowerShell, si lo desea.The ability to turn on the Azure PowerShell AzureRM PowerShell aliases if you would like.

Versiones de PowerShellPowerShell versions

En la tabla siguiente se muestran las versiones de PowerShell disponibles para cada versión principal de Functions Runtime, así como la versión necesaria de .NET:The following table shows the PowerShell versions available to each major version of the Functions runtime, and the .NET version required:

Versión de FunctionsFunctions version Versión de PowerShellPowerShell version Versión de .NET.NET version
3.x (recomendado)3.x (recommended) PowerShell 7 (recomendado)PowerShell 7 (recommended)
PowerShell Core 6PowerShell Core 6
.NET Core 3.1.NET Core 3.1
.NET Core 2.1.NET Core 2.1
2.x2.x PowerShell Core 6PowerShell Core 6 .NET Core 2.2.NET Core 2.2

Puede ver la versión actual mediante la impresión de $PSVersionTable desde cualquier función.You can see the current version by printing $PSVersionTable from any function.

Ejecución local en una versión específicaRunning local on a specific version

Cuando se ejecuta localmente, Azure Functions Runtime tiene como valor predeterminado el uso de PowerShell Core 6.When running locally the Azure Functions runtime defaults to using PowerShell Core 6. Para usar PowerShell 7 cuando se ejecuta localmente, debe agregar el valor "FUNCTIONS_WORKER_RUNTIME_VERSION" : "~7" a la matriz Values en el archivo local.setting.json en la raíz del proyecto.To instead use PowerShell 7 when running locally, you need to add the setting "FUNCTIONS_WORKER_RUNTIME_VERSION" : "~7" to the Values array in the local.setting.json file in the project root. Cuando se ejecuta localmente en PowerShell 7, el archivo local.setting.json es similar al ejemplo siguiente:When running locally on PowerShell 7, your local.settings.json file looks like the following example:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "powershell",
    "FUNCTIONS_WORKER_RUNTIME_VERSION" : "~7"
  }
}

Cambio de la versión de PowerShellChanging the PowerShell version

La aplicación de funciones debe ejecutarse en la versión 3.x para poder actualizar desde PowerShell Core 6 a PowerShell 7.Your function app must be running on version 3.x to be able to upgrade from PowerShell Core 6 to PowerShell 7. Para información sobre cómo realizar esta acción, consulte Visualización y actualización de la versión actual del entorno de ejecución.To learn how to do this, see View and update the current runtime version.

Siga estos pasos para cambiar la versión de PowerShell que usa la aplicación de funciones.Use the following steps to change the PowerShell version used by your function app. Puede realizar esta acción en Azure Portal o mediante PowerShell.You can do this either in the Azure portal or by using PowerShell.

  1. En Azure Portal, vaya a la aplicación de función.In the Azure portal, browse to your function app.

  2. En las opciones de configuración haga clic en Configuración.Under Settings , choose Configuration. En la pestaña Configuración general , busque la versión de PowerShell.In the General settings tab, locate the PowerShell version.

    Elección de la versión de PowerShell usada por la aplicación de funciones

  3. Elija la versión de PowerShell Core que quiera y seleccione Guardar.Choose your desired PowerShell Core version and select Save. Cuando se le advierta sobre el reinicio pendiente, elija Continuar.When warned about the pending restart choose Continue. La aplicación de funciones se reinicia en la versión de PowerShell elegida.The function app restarts on the chosen PowerShell version.

La aplicación de funciones se reinicia después de realizar el cambio en la configuración.The function app restarts after the change is made to the configuration.

Administración de dependenciasDependency management

Functions le permite usar la Galería de PowerShell para administrar las dependencias.Functions lets you leverage PowerShell gallery for managing dependencies. Con la administración de dependencias habilitada, el archivo requirements. psd1 se usa para descargar automáticamente los módulos necesarios.With dependency management enabled, the requirements.psd1 file is used to automatically download required modules. Para habilitar este comportamiento, establezca la propiedad managedDependency en true en la raíz del archivo host.json, como en el ejemplo siguiente:You enable this behavior by setting the managedDependency property to true in the root of the host.json file, as in the following example:

{
  "managedDependency": {
          "enabled": true
       }
}

Cuando crea un proyecto de funciones de PowerShell, la administración de dependencias está habilitada de manera predeterminada, con el Azmódulo de Azure incluido.When you create a new PowerShell functions project, dependency management is enabled by default, with the Azure Az module included. El número máximo de módulos admitidos actualmente es 10.The maximum number of modules currently supported is 10. La sintaxis admitida es MajorNumber .* o la versión de módulo exacta que se muestra en el ejemplo de requirements.psd1 siguiente:The supported syntax is MajorNumber.* or exact module version as shown in the following requirements.psd1 example:

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

Al actualizar el archivo requirements.psd1, los módulos actualizados se instalan después de un reinicio.When you update the requirements.psd1 file, updated modules are installed after a restart.

Nota

Las dependencias administradas requieren el acceso a www.powershellgallery.com para descargar los módulos.Managed dependencies requires access to www.powershellgallery.com to download modules. Cuando la ejecución sea local, asegúrese de que el runtime puede acceder a esta dirección URL mediante la adición de las reglas de firewall necesarias.When running locally, make sure that the runtime can access this URL by adding any required firewall rules.

Nota

Actualmente, las dependencias administradas no admiten módulos que requieren que el usuario acepte una licencia, ya sea aceptando la licencia de forma interactiva o proporcionando el conmutador -AcceptLicense al invocar Install-Module.Managed dependencies currently don't support modules that require the user to accept a license, either by accepting the license interactively, or by providing -AcceptLicense switch when invoking Install-Module.

La configuración de la aplicación siguiente se puede usar para cambiar cómo se descargar e instalan las dependencias administradas.The following application settings can be used to change how the managed dependencies are downloaded and installed. La actualización de la aplicación se inicia dentro de MDMaxBackgroundUpgradePeriod y el proceso de actualización se completa aproximadamente dentro del período MDNewSnapshotCheckPeriod.Your app upgrade starts within MDMaxBackgroundUpgradePeriod, and the upgrade process completes within approximately the MDNewSnapshotCheckPeriod.

Configuración de la aplicación de funcionesFunction App setting Valor predeterminadoDefault value DescripciónDescription
MDMaxBackgroundUpgradePeriod 7.00:00:00 (7 días)7.00:00:00 (7 days) Cada proceso de trabajo de PowerShell inicia la comprobación de las actualizaciones de módulo en la Galería de PowerShell en el inicio del proceso y, después, cada MDMaxBackgroundUpgradePeriod.Each PowerShell worker process initiates checking for module upgrades on the PowerShell Gallery on process start and every MDMaxBackgroundUpgradePeriod after that. Cuando hay disponible una nueva versión de módulo en la Galería de PowerShell, se instala en el sistema de archivos y se pone a disposición de los trabajadores de PowerShell.When a new module version is available in the PowerShell Gallery, it's installed to the file system and made available to PowerShell workers. Si se reduce este valor, la aplicación de funciones obtiene versiones más recientes de los módulos, pero también aumenta el uso de recursos de la aplicación (E/S de red, CPU, almacenamiento).Decreasing this value lets your function app get newer module versions sooner, but it also increases the app resource usage (network I/O, CPU, storage). Al aumentar este valor, se reduce el uso de recursos de la aplicación, pero también se puede retrasar la entrega de nuevas versiones de módulos a la aplicación.Increasing this value decreases the app's resource usage, but it may also delay delivering new module versions to your app.
MDNewSnapshotCheckPeriod 01:00:00 (1 hora)01:00:00 (1 hour) Una vez instaladas las nuevas versiones del módulo en el sistema de archivos, se debe reiniciar cada proceso de trabajo de PowerShell.After new module versions are installed to the file system, every PowerShell worker process must be restarted. Reiniciar los trabajos de PowerShell afecta la disponibilidad de la aplicación, ya que puede interrumpir la ejecución de la función actual.Restarting PowerShell workers affects your app availability as it can interrupt current function execution. Hasta que se reinicien todos los procesos de trabajo de PowerShell, las invocaciones de función pueden usar las versiones de módulos anteriores o nuevas.Until all PowerShell worker processes are restarted, function invocations may use either the old or the new module versions. El reinicio de todos los trabajos de PowerShell se completa dentro del período MDNewSnapshotCheckPeriod.Restarting all PowerShell workers complete within MDNewSnapshotCheckPeriod. Si se aumenta este valor, se disminuye la frecuencia de las interrupciones, pero también puede aumentar el período de tiempo en que las invocaciones de función usen las versiones de módulos anteriores o nuevas de forma no determinista.Increasing this value decreases the frequency of interruptions, but may also increase the period of time when function invocations use either the old or the new module versions non-deterministically.
MDMinBackgroundUpgradePeriod 1.00:00:00 (1 día)1.00:00:00 (1 day) Para evitar que se actualicen excesivamente los módulos en los reinicios frecuentes de los trabajos, no se realizará la comprobación de las actualizaciones de los módulos si ya se inició algún trabajo en el último MDMinBackgroundUpgradePeriod.To avoid excessive module upgrades on frequent Worker restarts, checking for module upgrades isn't performed when any worker has already initiated that check in the last MDMinBackgroundUpgradePeriod.

Aprovechar los propios módulos personalizados es algo diferente a como lo haría normalmente.Leveraging your own custom modules is a little different than how you would do it normally.

En el equipo local, el módulo se instala en una de las carpetas disponibles a nivel global en su $env:PSModulePath.On your local computer, the module gets installed in one of the globally available folders in your $env:PSModulePath. Cuando ejecuta Azure, no tiene acceso a los módulos instalados en su máquina.When running in Azure, you don't have access to the modules installed on your machine. Esto significa que $env:PSModulePath de una aplicación de funciones de PowerShell difiera de $env:PSModulePath en un script de PowerShell normal.This means that the $env:PSModulePath for a PowerShell function app differs from $env:PSModulePath in a regular PowerShell script.

En Functions, PSModulePath contiene dos rutas de acceso:In Functions, PSModulePath contains two paths:

  • Una carpeta Modules que existe en la raíz de la aplicación de funciones.A Modules folder that exists at the root of your function app.
  • Una ruta de acceso a una carpeta Modules que está controlada por el trabajo de lenguaje de PowerShell.A path to a Modules folder that is controlled by the PowerShell language worker.

Carpeta Modules del nivel de la aplicación de funcionesFunction app-level Modules folder

Para usar módulos personalizados, puede colocar los módulos de los que dependen sus funciones en una carpeta Modules.To use custom modules, you can place modules on which your functions depend in a Modules folder. Desde esta carpeta los módulos están automáticamente disponibles para Functions Runtime.From this folder, modules are automatically available to the functions runtime. Cualquier función de la aplicación de funciones puede usar estos módulos.Any function in the function app can use these modules.

Nota

Los módulos especificados en el archivo requirements.psd1 se descargan y se incluyen automáticamente en la ruta de acceso, por lo que no es necesario incluirlos en la carpeta modules.Modules specified in the requirements.psd1 file are automatically downloaded and included in the path so you don't need to include them in the modules folder. Estos se almacenan localmente en la carpeta $env:LOCALAPPDATA/AzureFunctions y en la carpeta /data/ManagedDependencies cuando se ejecutan en la nube.These are stored locally in the $env:LOCALAPPDATA/AzureFunctions folder and in the /data/ManagedDependencies folder when run in the cloud.

Para aprovechar las ventajas de la característica de módulos personalizados, cree una carpeta Modules en la raíz de la aplicación de funciones.To take advantage of the custom module feature, create a Modules folder in the root of your function app. Copie los módulos que quiere usar en las funciones en esta ubicación.Copy the modules you want to use in your functions to this location.

mkdir ./Modules
Copy-Item -Path /mymodules/mycustommodule -Destination ./Modules -Recurse

Con una carpeta Modules, la aplicación de funciones debe tener la siguiente estructura de carpetas:With a Modules folder, your function app should have the following folder structure:

PSFunctionApp
 | - MyFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - MyCustomModule
 | | - MyOtherCustomModule
 | | - MySpecialModule.psm1
 | - local.settings.json
 | - host.json
 | - requirements.psd1

Al inicia la aplicación de funciones, el trabajo de lenguaje de PowerShell agrega esta carpeta Modules a $env:PSModulePath, de manera que pueda confiar en la carga automática del módulo del mismo modo que lo haría en un script de PowerShell normal.When you start your function app, the PowerShell language worker adds this Modules folder to the $env:PSModulePath so that you can rely on module autoloading just as you would in a regular PowerShell script.

Carpeta Modules del nivel de trabajo de lenguajeLanguage worker level Modules folder

El trabajo de lenguaje de PowerShell usa varios módulos frecuentemente.Several modules are commonly used by the PowerShell language worker. Estos módulos se definen en la última posición de PSModulePath.These modules are defined in the last position of PSModulePath.

La lista actual de módulos es como sigue:The current list of modules is as follows:

  • Microsoft.PowerShell.Archive: módulo usadas para trabajar con archivos, como .zip, .nupkg y otros.Microsoft.PowerShell.Archive: module used for working with archives, like .zip, .nupkg, and others.
  • ThreadJob : implementación basada en subprocesos de las API de trabajo de PowerShell.ThreadJob : A thread-based implementation of the PowerShell job APIs.

De manera predeterminada, Functions usa la versión más reciente de estos módulos.By default, Functions uses the most recent version of these modules. Para usar una versión específica del módulo, coloque esa versión específica en la carpeta Modules de la aplicación de funciones.To use a specific module version, put that specific version in the Modules folder of your function app.

Variables de entornoEnvironment variables

En Functions, la configuración de la aplicación, como las cadenas de conexión del servicio, se exponen como variables de entorno durante la ejecución.In Functions, app settings, such as service connection strings, are exposed as environment variables during execution. Puede acceder a esta configuración mediante $env:NAME_OF_ENV_VAR, como se muestra en el siguiente ejemplo:You can access these settings using $env:NAME_OF_ENV_VAR, as shown in the following example:

param($myTimer)

Write-Host "PowerShell timer trigger function ran! $(Get-Date)"
Write-Host $env:AzureWebJobsStorage
Write-Host $env:WEBSITE_SITE_NAME

Hay varias maneras de agregar, actualizar y eliminar opciones de configuración de la aplicación de función:There are several ways that you can add, update, and delete function app settings:

Cuando se ejecuta localmente, la configuración de la aplicación se lee desde el archivo del proyecto local.settings.json.When running locally, app settings are read from the local.settings.json project file.

SimultaneidadConcurrency

De forma predeterminada, Function Runtime de PowerShell solo puede procesar una invocación de función a la vez.By default, the Functions PowerShell runtime can only process one invocation of a function at a time. Sin embargo, este nivel de simultaneidad podría no ser suficiente en las siguientes situaciones:However, this concurrency level might not be sufficient in the following situations:

  • Al intentar controlar un gran número de invocaciones a la vez.When you're trying to handle a large number of invocations at the same time.
  • Al disponer de funciones que invocan a otras dentro de la misma aplicación de funciones.When you have functions that invoke other functions inside the same function app.

Hay algunos modelos de simultaneidad que se pueden explorar según el tipo de carga de trabajo:There are a few concurrency models that you could explore depending on the type of workload:

  • Aumente FUNCTIONS_WORKER_PROCESS_COUNT.Increase FUNCTIONS_WORKER_PROCESS_COUNT. Esto permite controlar las invocaciones de función en varios procesos dentro de la misma instancia, que presenta cierta sobrecarga de CPU y de memoria.This allows handling function invocations in multiple processes within the same instance, which introduces certain CPU and memory overhead. En general, esta sobrecarga no afectará a las funciones enlazadas a E/S.In general, I/O-bound functions will not suffer from this overhead. En el caso de las funciones enlazadas a la CPU, el impacto puede ser significativo.For CPU-bound functions, the impact may be significant.

  • Aumente el valor de la configuración de aplicación PSWorkerInProcConcurrencyUpperBound.Increase the PSWorkerInProcConcurrencyUpperBound app setting value. Esto permite crear varios espacios de ejecución en el mismo proceso, lo que reduce significativamente la sobrecarga de CPU y de memoria.This allows creating multiple runspaces within the same process, which significantly reduces CPU and memory overhead.

Establezca estas variables de entorno en la configuración de la aplicación de la aplicación de funciones.You set these environment variables in the app settings of your function app.

En función del caso de uso, Durable Functions puede mejorar significativamente la escalabilidad.Depending on your use case, Durable Functions may significantly improve scalability. Para obtener más información, vea Patrones de aplicación de Durable Functions.To learn more, see Durable Functions application patterns.

Nota

Puede obtener advertencias que indiquen que "las solicitudes están en cola porque no hay espacios de ejecución disponibles". Tenga en cuenta que esto no es un error.You might get "requests are being queued due to no available runspaces" warnings, please note that this is not an error. El mensaje indica que las solicitudes se van a poner en cola y se controlarán cuando se completen las solicitudes anteriores.The message is telling you that requests are being queued and they will be handled when the previous requests are completed.

Consideraciones para usar la simultaneidadConsiderations for using concurrency

De forma predeterminada, PowerShell es un único subproceso de lenguaje de scripting.PowerShell is a single threaded scripting language by default. Sin embargo, la simultaneidad puede agregarse mediante el uso de varios espacios de ejecución de PowerShell en el mismo proceso.However, concurrency can be added by using multiple PowerShell runspaces in the same process. La cantidad de espacios de ejecución coincidirá con la configuración de la aplicación PSWorkerInProcConcurrencyUpperBound.The amount of runspaces created will match the PSWorkerInProcConcurrencyUpperBound application setting. El rendimiento se verá afectado por la cantidad de CPU y memoria disponibles en el plan seleccionado.The throughput will be impacted by the amount of CPU and memory available in the selected plan.

Azure PowerShell usa algunos procesos y estados de nivel de proceso para que no tenga que escribir tanto.Azure PowerShell uses some process-level contexts and state to help save you from excess typing. Sin embargo, si activa la simultaneidad en la aplicación de funciones e invoca acciones que cambien el estado, puede acabar con las condiciones de carrera.However, if you turn on concurrency in your function app and invoke actions that change state, you could end up with race conditions. Estas condiciones de carrera son difíciles de depurar, ya que una invocación se basa en un estado determinado y la otra ha cambiado el estado.These race conditions are difficult to debug because one invocation relies on a certain state and the other invocation changed the state.

La simultaneidad es muy valiosa con Azure PowerShell, ya que algunas operaciones pueden tardar un tiempo considerable.There's immense value in concurrency with Azure PowerShell, since some operations can take a considerable amount of time. Sin embargo, debe proceder con precaución.However, you must proceed with caution. Si sospecha que está experimentando una condición de carrera, establezca la configuración de la aplicación PSWorkerInProcConcurrencyUpperBound en 1 y, en su lugar, use el aislamiento de nivel de proceso de trabajo de lenguaje para la simultaneidad.If you suspect that you're experiencing a race condition, set the PSWorkerInProcConcurrencyUpperBound app setting to 1 and instead use language worker process level isolation for concurrency.

Configuración de la función scriptFileConfigure function scriptFile

De forma predeterminada, se ejecuta una función de PowerShell desde run.ps1, un archivo que comparte el mismo directorio primario que su archivo function.json correspondiente.By default, a PowerShell function is executed from run.ps1, a file that shares the same parent directory as its corresponding function.json.

La propiedad scriptFile de function.json se puede usar para obtener una estructura de carpetas que tenga el aspecto del siguiente ejemplo:The scriptFile property in the function.json can be used to get a folder structure that looks like the following example:

FunctionApp
 | - host.json
 | - myFunction
 | | - function.json
 | - lib
 | | - PSFunction.ps1

En este caso, el archivo function.json para myFunction incluye una propiedad scriptFile que hace referencia al archivo con la función exportada que se va a ejecutar.In this case, the function.json for myFunction includes a scriptFile property referencing the file with the exported function to run.

{
  "scriptFile": "../lib/PSFunction.ps1",
  "bindings": [
    // ...
  ]
}

Uso de módulos de PowerShell mediante la configuración de entryPointUse PowerShell modules by configuring an entryPoint

En este artículo se han mostrado las funciones de PowerShell en el archivo de script run.ps1 predeterminado generado por las plantillas.This article has shown PowerShell functions in the default run.ps1 script file generated by the templates. Sin embargo, también puede incluir las funciones en módulos de PowerShell.However, you can also include your functions in PowerShell modules. Puede hacer referencia a su código de función específico del módulo mediante los campos scriptFile y entryPoint del archivo de configuración function.json.You can reference your specific function code in the module by using the scriptFile and entryPoint fields in the function.json` configuration file.

En este caso, entryPoint es el nombre de una función o un cmdlet del módulo de PowerShell a los que se hace referencia en scriptFile.In this case, entryPoint is the name of a function or cmdlet in the PowerShell module referenced in scriptFile.

Considere la siguiente estructura de carpetas:Consider the following folder structure:

FunctionApp
 | - host.json
 | - myFunction
 | | - function.json
 | - lib
 | | - PSFunction.psm1

Donde PSFunction.psm1 contiene:Where PSFunction.psm1 contains:

function Invoke-PSTestFunc {
    param($InputBinding, $TriggerMetadata)

    Push-OutputBinding -Name OutputBinding -Value "output"
}

Export-ModuleMember -Function "Invoke-PSTestFunc"

En este ejemplo, la configuración de myFunction incluye una propiedad scriptFile que hace referencia a PSFunction.psm1, que es un módulo de PowerShell de otra carpeta.In this example, the configuration for myFunction includes a scriptFile property that references PSFunction.psm1, which is a PowerShell module in another folder. La propiedad entryPoint hace referencia a la función Invoke-PSTestFunc, que es el punto de entrada del módulo.The entryPoint property references the Invoke-PSTestFunc function, which is the entry point in the module.

{
  "scriptFile": "../lib/PSFunction.psm1",
  "entryPoint": "Invoke-PSTestFunc",
  "bindings": [
    // ...
  ]
}

Con esta configuración, Invoke-PSTestFunc se ejecuta exactamente como lo haría run.ps1.With this configuration, the Invoke-PSTestFunc gets executed exactly as a run.ps1 would.

Consideraciones para las funciones de PowerShellConsiderations for PowerShell functions

Al trabajar con las funciones de PowerShell, tenga en cuenta las consideraciones de las siguientes secciones.When you work with PowerShell functions, be aware of the considerations in the following sections.

Arranque en fríoCold Start

Al desarrollar Azure Functions en el modelo de hospedaje sin servidor, los arranques en frío son una realidad.When developing Azure Functions in the serverless hosting model, cold starts are a reality. El arranque en frío se refiere al período de tiempo tarda la aplicación de funciones en empezar a ejecutarse para procesar una solicitud.Cold start refers to period of time it takes for your function app to start running to process a request. El arranque en frío se produce con mayor frecuencia en el plan Consumo, puesto que la aplicación de funciones se cierra durante los períodos de inactividad.Cold start happens more frequently in the Consumption plan because your function app gets shut down during periods of inactivity.

Módulos de agrupación en lugar de Install-ModuleBundle modules instead of using Install-Module

El script se ejecuta en cada invocación.Your script is run on every invocation. Evite el uso de Install-Module en el script.Avoid using Install-Module in your script. En su lugar, use Save-Module antes de publicar para que la función no tenga que perder tiempo descargando el módulo.Instead use Save-Module before publishing so that your function doesn't have to waste time downloading the module. Si los arranques en frío afectan a las funciones, considere la posibilidad de implementar la aplicación de funciones en un plan de App Service establecido en AlwaysOn o plan Premium.If cold starts are impacting your functions, consider deploying your function app to an App Service plan set to always on or to a Premium plan.

Pasos siguientesNext steps

Para obtener más información, consulte los siguientes recursos:For more information, see the following resources: