Inicio rápido: Creación de una función de PowerShell en Azure desde la línea de comandos

En este artículo se usan herramientas de línea de comandos para crear una función de PowerShell que responda a solicitudes HTTP. Después de probar el código localmente, se implementa en el entorno sin servidor de Azure Functions.

Este inicio rápido supone un pequeño costo en su cuenta de Azure.

También hay una versión basada en Visual Studio Code de este artículo.

Configuración del entorno local

Antes de empezar, debe disponer de lo siguiente:

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

• Una de las siguientes herramientas para crear recursos de Azure:

  • El módulo Az de PowerShell de Azure, versión 9.4.0 o posterior.

  • CLI de Azure, versión 2.4 o posterior.

• SDK de .NET 6.0

• PowerShell 7.4

Instalación de Azure Functions Core Tools

La manera recomendada de instalar Core Tools depende del sistema operativo del equipo de desarrollo local.

Creación de un proyecto de función local

En Azure Functions, un proyecto de función es un contenedor para una o varias funciones individuales que responden a un desencadenador específico. Todas las funciones de un proyecto comparten las mismas configuraciones locales y de hospedaje. En esta sección, se crea un proyecto de función que contiene una sola función.

1. Ejecute el comando func init, de la manera siguiente, para crear un proyecto de funciones en una carpeta llamada LocalFunctionProj con el entorno de ejecución especificado:

   func init LocalFunctionProj --powershell
   

2. Vaya a la carpeta del proyecto:

   cd LocalFunctionProj
   

   Esta carpeta contiene varios archivos del proyecto, incluidos los archivos de configuración local.settings.json y host.json. Como local.settings.json puede contener secretos descargados de Azure, el archivo se excluye del control de código fuente de forma predeterminada en el archivo .gitignore.

3. Agregue una función al proyecto mediante el comando siguiente, donde el argumento --name es el nombre único de la función (HttpExample) y el argumento --template especifica el desencadenador de esta (HTTP).

   func new --name HttpExample --template "HTTP trigger" --authlevel "anonymous"
   

   func new crea una subcarpeta que coincide con el nombre de la función que contiene un archivo de código apropiado para el lenguaje elegido del proyecto y un archivo de configuración denominado function.json.

(Opcional) Examen del contenido del archivo

Si lo desea, puede ir a Ejecución local de la función y examine el contenido del archivo posteriormente.

run.ps1

run.ps1 define un script de función que se desencadena de acuerdo con la configuración de function.json.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$name = $Request.Query.Name
if (-not $name) {
    $name = $Request.Body.Name
}

$body = "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."

if ($name) {
    $body = "Hello, $name. This HTTP triggered function executed successfully."
}

# Associate values to output bindings by calling 'Push-OutputBinding'.
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [HttpStatusCode]::OK
    Body = $body
})

Con un desencadenador HTTP, la función recibe los datos de solicitud pasados al parámetro $Request definido en function.json. El objeto devuelto, definido como Response en function.json, se pasa al cmdlet Push-OutputBinding como respuesta.

function.json

function.json es un archivo de configuración que define la entrada y salida bindings de la función, lo que incluye el tipo de desencadenador.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

Cada enlace requiere una dirección, un tipo y un nombre único. El desencadenador HTTP tiene un enlace de entrada de tipo httpTrigger y un enlace de salida de tipo http.

Ejecución local de la función

1. Para ejecutar la función, inicie el host en tiempo de ejecución local de Azure Functions desde la carpeta LocalFunctionProj.

   func start
   

   En la parte final de la salida, deberán aparecer las líneas siguientes:

   

   Nota

   Si HttpExample no aparece como se ha mostrado arriba, es probable que haya iniciado el host desde fuera de la carpeta raíz del proyecto. En ese caso, use Ctrl+C para detener el host, vaya a la carpeta raíz del proyecto y vuelva a ejecutar el comando anterior.

2. Copie la URL de su función HTTP de esta salida a un navegador y agregue la cadena de consulta ?name=<YOUR_NAME>, lo que hace que la URL completa sea como http://localhost:7071/api/HttpExample?name=Functions. El explorador debe mostrar un mensaje de respuesta que devuelve el valor de la cadena de consulta. El terminal en el que inició el proyecto también muestra la salida del registro cuando realiza solicitudes.

3. Cuando termine, presione Ctrl + C y escriba y para detener el host de Azure Functions.

Creación de recursos auxiliares de Azure para la función

Antes de poder implementar el código de la función en Azure, debe crear tres recursos:

• Un grupo de recursos, que es un contenedor lógico de recursos relacionados.
• Una cuenta de almacenamiento, que se usa para mantener el estado y otra información sobre sus funciones.
• Una aplicación de funciones, que proporciona el entorno para ejecutar el código de función. Una aplicación de funciones se asigna al proyecto de funciones y le permite agrupar funciones como una unidad lógica para facilitar la administración, la implementación y el uso compartido de recursos.

Utilice los comandos siguientes para crear los elementos. Se admiten las CLI de Azure y de PowerShell.

1. Si todavía no lo ha hecho, inicie sesión en Azure:

   • CLI de Azure
   • Azure PowerShell

   az login
   

   El comando az login inicia sesión en su cuenta de Azure.

2. Cree un grupo de recursos denominado AzureFunctionsQuickstart-rg en la región elegida:

   • CLI de Azure
   • Azure PowerShell

   az group create --name AzureFunctionsQuickstart-rg --location <REGION>
   

   El comando az group create crea un grupo de recursos. En el comando anterior, reemplace <REGION> por una región cercana mediante un código de región disponible devuelto por el comando az account list-locations.

3. Cree una cuenta de almacenamiento de uso general en su grupo de recursos y región:

   • CLI de Azure
   • Azure PowerShell

   az storage account create --name <STORAGE_NAME> --location <REGION> --resource-group AzureFunctionsQuickstart-rg --sku Standard_LRS --allow-blob-public-access false
   

   El comando az storage account create crea la cuenta de almacenamiento.

   En el ejemplo anterior, reemplace <STORAGE_NAME> por un nombre que sea apropiado para usted y único en Azure Storage. Los nombres deben contener entre 3 y 24 caracteres y solo letras minúsculas. Standard_LRS especifica una cuenta de uso general, que es compatible con Functions.

4. Cree la aplicación de funciones en Azure:

   • CLI de Azure
   • Azure PowerShell

   az functionapp create --resource-group AzureFunctionsQuickstart-rg --consumption-plan-location <REGION> --runtime powershell --functions-version 4 --name <APP_NAME> --storage-account <STORAGE_NAME>
   

   El comando az functionapp create crea la aplicación de funciones en Azure.

   En el ejemplo anterior, reemplace <STORAGE_NAME> por el nombre de la cuenta que usó en el paso anterior y reemplace <APP_NAME> por un nombre único global que le resulte adecuado. <APP_NAME> también es el dominio DNS predeterminado de la aplicación de función.

   Este comando crea una aplicación de funciones que se ejecuta en el entorno de ejecución del lenguaje especificado en el plan de consumo de Azure Functions, que es gratuito para la cantidad de uso que se realiza aquí. El comando también aprovisiona una instancia asociada de Azure Application Insights en el mismo grupo de recursos con la que puede supervisar la aplicación de funciones y ver registros. Para más información, consulte Supervisión de Azure Functions. La instancia no incurrirá en ningún costo hasta que se active.

Implementación del proyecto de función en Azure

Después de haber creado correctamente su aplicación de funciones en Azure, estará listo para implementar el proyecto de funciones local mediante el comando func azure functionapp publish.

En la carpeta del proyecto raíz, ejecute este comando func azure functionapp publish:

func azure functionapp publish <APP_NAME>

En este ejemplo, reemplace <APP_NAME> por el nombre de la aplicación. Una implementación correcta muestra resultados similares a la salida siguiente (truncada por motivos de simplicidad):

...

Getting site publishing info...
Creating archive for current directory...
Performing remote build for functions project.

...

Deployment successful.
Remote build succeeded!
Syncing triggers...
Functions in msdocs-azurefunctions-qs:
    HttpExample - [httpTrigger]
        Invoke url: https://msdocs-azurefunctions-qs.azurewebsites.net/api/httpexample

Invocación de la función en Azure

Como la función usa un desencadenador HTTP, para invocarla es preciso realizar una solicitud HTTP a su dirección URL en el explorador o con una herramienta como CURL.

Ejecute el siguiente comando para ver registros de streaming casi en tiempo real:

func azure functionapp logstream <APP_NAME> 

En una ventana de terminal independiente o en el explorador, vuelva a llamar a la función remota. En la ventana de terminal, se mostrará un registro detallado de la ejecución de la función en Azure.

Limpieza de recursos

Si continúa con el paso siguiente y agrega un enlace de salida de la cola de Azure Storage, conserve todos los recursos intactos, ya que va a crear a partir de lo que ya ha hecho.

De lo contrario, use el siguiente comando para eliminar el grupo de recursos y todos los recursos que contiene para evitar incurrir en costos adicionales.

az group delete --name AzureFunctionsQuickstart-rg

Remove-AzResourceGroup -Name AzureFunctionsQuickstart-rg

Pasos siguientes