Guía del desarrollador de Azure PowerShell de funcionesAzure Functions PowerShell developer guide

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

Nota

PowerShell para Azure Functions actualmente se encuentra disponible en versión preliminar.PowerShell for Azure Functions is currently in preview. Para recibir actualizaciones importantes, suscríbase al repositorio de anuncios de Azure App Service en GitHub.To receive important updates, subscribe to the Azure App Service announcements repository on GitHub.

Una función de PowerShell Azure (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 secuencia de comandos de función tiene un relacionados function.json archivo que define cómo se comporta la función, por ejemplo, cómo se activa y sus parámetros de entrada y salidos.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 obtener más información, consulte el desencadenadores y artículo enlace.To learn more, see the Triggers and binding article.

Al igual que otros tipos de funciones, funciones de script de PowerShell toman parámetros que coinciden con los nombres de todos los enlaces de entrada definidos en el function.json archivo.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. Un TriggerMetadata también se pasa parámetro que contiene información adicional sobre el desencadenador que inicia 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 necesarios 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 compartido host.json archivo 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 el 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 principal del archivo de function.json 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 extensions.csproj archivo.Certain bindings require the presence of an extensions.csproj file. Enlace las extensiones necesarias en versión 2.x del tiempo de ejecución de funciones, se definen en el extensions.csproj archivo, con los archivos de biblioteca real en el bin carpeta.Binding extensions, required in version 2.x 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 función de PowerShell, podría tener opcionalmente un profile.ps1 que se ejecuta cuando se inicia una aplicación de función para ejecutarse (en caso contrario, se conoce como un 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 obtener más información, consulte perfil PowerShell.For more information, see PowerShell profile.

Definición de un script de PowerShell como una 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.

La secuencia de comandos se pasa un número de argumentos en ejecución.Your script is passed a number of arguments on execution. Para controlar estos parámetros, agregue un param bloque a la parte superior de la secuencia de comandos como en el ejemplo siguiente: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 TriggerMetadata parámetro 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ía en función de enlace al enlace, pero todos ellos contienen un sys propiedad que contiene los datos siguientes: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 TypeType
UtcNowUtcNow Cuando, en UTC, se desencadenó la funciónWhen, in UTC, the function was triggered DateTimeDateTime
MethodNameMethodName El nombre de la función que se desencadenóThe name of the Function that was triggered stringstring
RandGuidRandGuid un 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, el $TriggerMetadata para QueueTrigger contiene el InsertionTime, Id, DequeueCount, entre otras cosas.For example, the $TriggerMetadata for QueueTrigger contains the InsertionTime, Id, DequeueCount, among other things. Para obtener más información sobre los metadatos del desencadenador de cola, vaya a la documentación oficial para los desencadenadores de colas.For more information on the queue trigger's metadata, go to the official documentation for queue triggers. Consulte la documentación en el desencadenadores 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, enlaces se configuran y se define en function.json de la 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

Desencadenador y enlaces de entrada se leen como parámetros pasados 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. El name propiedad definida en function.json es el nombre del parámetro, en el param bloque.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 los parámetros.Since PowerShell uses named parameters for binding, the order of the parameters doesn't matter. Sin embargo, es una práctica recomendada para seguir el orden de los enlaces definidos en el function.json.However, it's a best practice to follow the order of the bindings defined in the function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

Escribir datos de salidaWriting output data

En las funciones, 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 uso de la Push-OutputBinding cmdlet, que está disponible para el tiempo de ejecución de funciones.You can write to an output binding by using the Push-OutputBinding cmdlet, which is available to the Functions runtime. En todos los casos, el name propiedad del enlace tal como se define en function.json corresponde a la Name parámetro de la Push-OutputBinding cmdlet.In all cases, the name property of the binding as defined in function.json corresponds to the Name parameter of the Push-OutputBinding cmdlet.

La siguiente 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 a través de 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, una llamada a Push-OutputBinding una segunda vez genera un error.When the output binding only accepts a singleton value, calling Push-OutputBinding a second time raises an error.

Push-OutputBinding SintaxisPush-OutputBinding syntax

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

NOMBREName TypeType posiciónPosition DESCRIPCIÓNDescription
-Name StringString 11 El nombre del enlace de salida que desea establecer.The name of the output binding you want to set.
-Value ObjectObject 22 El valor del enlace de salida que desea establecer, que se acepta 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 valor debe establecerse 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 parámetros comunes siguientes:The following common parameters are also supported:

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

Para obtener más información, consulte acerca de CommonParameters.For more information, see About CommonParameters.

Ejemplo de inserción 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 ejemplo siguiente, el enlace de salida de response tiene el valor de "salida #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 sólo un valor singleton, se produce un error cuando Push-OutputBinding se llama a una segunda vez.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"
})

Los resultados que sólo acepte valores singleton, puede usar el -Clobber parámetro para invalidar el valor anterior en lugar de intentar agregar 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 "salida #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 inserción OutputBinding: Enlace de salida de colaPush-OutputBinding example: Queue output binding

Push-OutputBinding se usa para enviar datos a los enlaces de salida, como un enlace de salida Azure Queue storage.Push-OutputBinding is used to send data to output bindings, such as an Azure Queue storage output binding. En el ejemplo siguiente, el mensaje que se escriben en la cola tiene un valor de "salida #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 almacenamiento acepta varios valores de salida.The output binding for a Storage queue accepts multiple output values. En este caso, una llamada en el ejemplo siguiente después de la primera escribe en la cola de una lista con dos elementos: "output #1" y "salida de #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"

El ejemplo siguiente, cuando se llama después de los dos anteriores, agrega dos o más valores 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", "salida de #2", "salida #3" y "salida #4".When written to the queue, the message contains these four values: "output #1", "output #2", "output #3", and "output #4".

Get-OutputBinding cmdletGet-OutputBinding cmdlet

Puede usar el 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 los valores respectivos.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 actual: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 ejemplo siguiente: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

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

RegistroLogging

Iniciar sesión en las funciones de PowerShell funciona como registro de PowerShell regular.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 las funciones.Each cmdlet maps to a log level used by Functions.

Funciones de nivel de registroFunctions logging level Cmdlet de registroLogging cmdlet
ErrorError Write-Error
AdvertenciaWarning Write-Warning
InformaciónInformation Write-Information
Write-Host
Write-Output
InformaciónInformation Escribe en información registro en el nivel.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 a la Information registro nivel y se muestran 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

Mediante el Write-Verbose o Write-Debug cmdlets no es suficiente para ver detallado y el registro de nivel 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 los registros de verdad te preocupas.You must also configure the log level threshold, which declares what level of logs you actually care about. Para obtener más información, consulte configurar el nivel de registro de aplicación de función.To learn more, see Configure the function app log level.

Configurar el nivel de registro de aplicación de funciónConfigure the function app log level

Functions permite definir el nivel de umbral para facilitar a las funciones de manera que se escribe en los registros de control.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 el logging.logLevel.default propiedad en el host.json archivo.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.

El ejemplo siguiente 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 sobre host.json.For more information, see host.json reference.

Visualización de los registrosViewing the logs

Si la aplicación de función se ejecuta en Azure, puede usar Application Insights para supervisarlo.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 está ejecutando la aplicación de función localmente para el desarrollo, registra de forma 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 el AZURE_FUNCTIONS_ENVIRONMENT variable de entorno Development antes de iniciar la aplicación de función.To see the logs in the console, set the AZURE_FUNCTIONS_ENVIRONMENT environment variable to Development before starting the Function App.

Tipos de enlaces y desencadenadoresTriggers and bindings types

Hay un número de enlaces y desencadenadores disponibles para su uso con la aplicación de función.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 puede encontrarse aquí.The full list of triggers and bindings can be found here.

Todos los desencadenadores y enlaces se representan en el código como algunos 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 se utilizan únicamente por la HttpTrigger desencadenador.The last two are used only by the HttpTrigger trigger.

Cada parámetro de enlace en las funciones debe ser 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 a la secuencia de comandos es del tipo HttpRequestContext, que tiene 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 TypeType
Body Objeto que contiene el cuerpo de la solicitud.An object that contains the body of the request. Body se serializa en el mejor tipo basándose en los datos.Body is serialized into the best type based on the data. Por ejemplo, si los datos JSON, se pasa en como una tabla hash.For example, if the data is JSON, it's passed in as a hashtable. Si los datos están una cadena, se pasa en forma de cadena.If the data is a string, it's passed in as a string. objetoobject
Headers Un diccionario que contiene los encabezados de 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

* Todos los Dictionary<string,string> claves 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 atrás es del 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 TypeType
Body Objeto que contiene el cuerpo de la respuesta.An object that contains the body of the response. objetoobject
ContentType Una mano corto 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

Cuando se trabaja 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 la param bloque.It's in the param block.

Use un HttpResponseContext objeto para devolver una respuesta, tal como se muestra en la siguiente: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 blob, 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 del almacenamiento de blobs proporcionado como una cadena, agregue el siguiente tipo de conversión a mi param bloque: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, hay el concepto de un perfil de PowerShell.In PowerShell, there's the concept of a PowerShell profile. Si no está familiarizado con los perfiles de PowerShell, consulte acerca de los perfiles.If you're not familiar with PowerShell profiles, see About profiles.

En las funciones de PowerShell, se ejecuta el script de perfil cuando se inicia la aplicación de función.In PowerShell Functions, the profile script executes when the function app starts. Inician de aplicaciones de función cuando se implementó por primera vez y después de que se está inactivo (frío).Function apps start when first deployed and after being idled (cold start).

Cuando se crea una aplicación de función con herramientas como Visual Studio Code y Azure Functions Core Tools, valor predeterminado es profile.ps1 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:

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

Versión de PowerShellPowerShell version

En la tabla siguiente se muestra la versión de PowerShell usada por cada versión principal del tiempo de ejecución de funciones:The following table shows the PowerShell version used by each major version of the Functions runtime:

Versión de FunctionsFunctions version Versión de PowerShellPowerShell version
1.x1.x Windows PowerShell 5.1 (bloqueado por el tiempo de ejecución)Windows PowerShell 5.1 (locked by the runtime)
2.x2.x PowerShell Core 6PowerShell Core 6

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

Administración de dependenciasDependency management

Las funciones de PowerShell admiten la administración de módulos de Azure por el servicio.PowerShell functions support managing Azure modules by the service. Modificando el host.json y establecer la propiedad managedDependency habilitada en true, se procesará el archivo requirements.psd1.By modifying the host.json and setting the managedDependency enabled property to true, the requirements.psd1 file will be processed. Los módulos de Azure más recientes se descargará automáticamente y disponible para la función.The latest Azure modules will be automatically downloaded and made available to the function.

host.jsonhost.json

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

requirements.psd1requirements.psd1

@{
    Az = '1.*'
}

Aprovechamiento de su propio custom módulos o los módulos de la Galería de PowerShell es un poco diferente de cómo lo haría normalmente.Leveraging your own custom modules or modules from the PowerShell Gallery is a little different than how you would do it normally.

Cuando se instala el módulo en el equipo local, se incluye en una de las carpetas disponibles globalmente en su $env:PSModulePath.When you install the module on your local machine, it goes in one of the globally available folders in your $env:PSModulePath. Dado que la función se ejecuta en Azure, no tendrá acceso a los módulos instalados en el equipo.Since your function runs in Azure, you won't have access to the modules installed on your machine. Esto requiere que el $env:PSModulePath para una función de PowerShell difiere aplicación $env:PSModulePath en un script de PowerShell normal.This requires that the $env:PSModulePath for a PowerShell function app differs from $env:PSModulePath in a regular PowerShell script.

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

  • Un Modules carpeta que existe en la raíz de la aplicación de función.A Modules folder that exists at the root of your Function App.
  • Una ruta de acceso a un Modules carpeta que se encuentra en el trabajo de lenguaje de PowerShell.A path to a Modules folder that lives inside the PowerShell language worker.

Nivel de aplicación de función Modules carpetaFunction app-level Modules folder

Para usar los módulos personalizados o los módulos de PowerShell desde la Galería de PowerShell, puede colocar los módulos que dependen las funciones en un Modules carpeta.To use custom modules or PowerShell modules from the PowerShell Gallery, you can place modules on which your functions depend in a Modules folder. Desde esta carpeta, módulos están automáticamente disponibles para el tiempo de ejecución de funciones.From this folder, modules are automatically available to the functions runtime. Cualquier función de la aplicación de función puede usar estos módulos.Any function in the function app can use these modules.

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

mkdir ./Modules
Save-Module MyGalleryModule -Path ./Modules

Usar Save-Module para guardar todos los módulos que utilizan las funciones o copiar sus propios módulos personalizados para el Modules carpeta.Use Save-Module to save all of the modules your functions use, or copy your own custom modules to the Modules folder. Con una carpeta de módulos, la aplicación de función debe tener la estructura de carpetas siguiente:With a Modules folder, your function app should have the following folder structure:

PSFunctionApp
 | - MyFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - MyGalleryModule
 | | - MyOtherGalleryModule
 | | - MyCustomModule.psm1
 | - local.settings.json
 | - host.json

Cuando se inicia la aplicación de función, el trabajador de lenguaje de PowerShell agrega este Modules carpeta a la $env:PSModulePath por lo que puede confiar en el módulo carga automática tal como 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.

Nivel de trabajo del lenguaje Modules carpetaLanguage worker level Modules folder

Varios módulos se usan normalmente el trabajador de lenguaje de PowerShell.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 los 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, .nupkgy otros.Microsoft.PowerShell.Archive: module used for working with archives, like .zip, .nupkg, and others.
  • ThreadJob: Una implementación basada en subprocesos de la API de trabajo de PowerShell.ThreadJob: A thread-based implementation of the PowerShell job APIs.

La versión más reciente de estos módulos se usa las funciones.The most recent version of these modules is used by Functions. Para usar una versión específica de estos módulos, puede colocar la versión específica en el Modules carpeta de la aplicación de función.To use a specific version of these modules, you can put the 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 tener acceso a estas opciones mediante $env:NAME_OF_ENV_VAR, como se muestra en el ejemplo siguiente: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, el tiempo de ejecución de PowerShell de funciones sólo puede procesar una invocación de una 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 situaciones siguientes:However, this concurrency level might not be sufficient in the following situations:

  • Cuando intenta administrar un gran número de llamadas al mismo tiempo.When you're trying to handle a large number of invocations at the same time.
  • Cuando dispone de funciones que llaman a otras funciones dentro de la misma aplicación de función.When you have functions that invoke other functions inside the same function app.

Puede cambiar este comportamiento estableciendo la variable de entorno siguiente en un valor entero:You can change this behavior by setting the following environment variable to an integer value:

PSWorkerInProcConcurrencyUpperBound

Establezca esta variable de entorno el configuración de la aplicación de la aplicación de función.You set this environment variable in the app settings of your Function App.

Consideraciones sobre el uso de simultaneidadConsiderations for using concurrency

PowerShell es un un único subproceso lenguaje de scripting de forma predeterminada.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. Esta característica es cómo funciona el tiempo de ejecución de funciones de Azure PowerShell.This feature is how the Azure Functions PowerShell runtime works.

Existen algunos inconvenientes con este enfoque.There are some drawbacks with this approach.

Simultaneidad es tan buena como el equipo en que se está ejecutandoConcurrency is only as good as the machine it's running on

Si la aplicación de función se ejecuta en un plan de App Service que solo admite un único núcleo, a continuación, simultaneidad no ayuda demasiado.If your function app is running on an App Service plan that only supports a single core, then concurrency won't help much. Eso es porque no hay ningún núcleos adicionales para ayudar a equilibrar la carga.That's because there are no additional cores to help balance the load. En este caso, el rendimiento puede variar cuando el núcleo único tiene a cambio de contexto entre los espacios de ejecución.In this case, performance can vary when the single core has to context-switch between runspaces.

El plan de consumo se ejecuta con un solo núcleo, lo que no puede aprovechar la simultaneidad.The Consumption plan runs using only one core, so you can't leverage concurrency. Si desea aprovechar al máximo de simultaneidad, en su lugar, implemente las funciones a una aplicación de función que se ejecuta en un plan de App Service dedicado con suficientes núcleos.If you want to take full advantage of concurrency, instead deploy your functions to a function app running on a dedicated App Service plan with sufficient cores.

Estado de Azure PowerShellAzure PowerShell state

Azure PowerShell usa algunos nivel de proceso contextos y estado para ayudar a ahorrar de exceso de escribir.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 función e invocar acciones que cambian 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 porque una invocación se basa en un estado determinado y la otra llamada 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.

Hay gran valor en la simultaneidad con Azure PowerShell, ya que algunas operaciones pueden tardar una cantidad considerable de tiempo.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 tiene una condición de carrera, establecer la simultaneidad al 1 e inténtelo de nuevo la solicitud.If you suspect that you're experiencing a race condition, set the concurrency back to 1 and try the request again.

Configurar 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 correspondiente function.json.By default, a PowerShell function is executed from run.ps1, a file that shares the same parent directory as its corresponding function.json.

El scriptFile propiedad en el function.json puede usarse para obtener una estructura de carpetas es similar al ejemplo siguiente: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 function.json para myFunction incluye un scriptFile propiedad hace referencia al archivo con la función exportada para 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": [
    // ...
  ]
}

Usar módulos de PowerShell mediante la configuración de un punto de entradaUse PowerShell modules by configuring an entryPoint

Este artículo le haya mostrado las funciones de PowerShell en el valor predeterminado run.ps1 generado por las plantillas de archivo de script.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 el código de función específica en el módulo mediante el scriptFile y entryPoint campos en el archivo function.json "archivo de configuración.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 cmdlet del módulo de PowerShell que se hace referenciado en scriptFile.In this case, entryPoint is the name of a function or cmdlet in the PowerShell module referenced in scriptFile.

Tenga en cuenta 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 un scriptFile propiedad que hace referencia a PSFunction.psm1, que es un módulo de PowerShell en 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. El entryPoint referencias de propiedad el Invoke-PSTestFunc función, que es el punto de entrada en el 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, el Invoke-PSTestFunc se ejecuta exactamente como un run.ps1 haría.With this configuration, the Invoke-PSTestFunc gets executed exactly as a run.ps1 would.

Consideraciones para las funciones de PowerShellConsiderations for PowerShell functions

Cuando se trabaja con las funciones de PowerShell, tenga en cuenta las consideraciones de las secciones siguientes.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 servidoren frío se inicia es una realidad.When developing Azure Functions in the serverless hosting model, cold starts are a reality. Arranque en frío se refiere al período de tiempo tarda la aplicación de función empezar a ejecutar para procesar una solicitud.Cold start refers to period of time it takes for your function app to start running to process a request. Arranque en frío se produce con mayor frecuencia en el consumo previsto porque la aplicación de función se cierra durante 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 usar 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 tiene 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 que afectan a las funciones, considere la posibilidad de implementar la aplicación de función a un plan de App Service establecido en AlwaysOn o a un 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: