Uso de Azure Functions Core Tools

Azure Functions Core Tools le permite desarrollar y probar funciones en el equipo local desde el símbolo del sistema o terminal. Las funciones locales pueden conectarse a servicios de Azure en directo, y puede depurar sus funciones en el equipo local con el tiempo de ejecución de Functions completo. Incluso puede implementar una aplicación de función en su suscripción a Azure.

Nota

No mezcle el desarrollo local con el desarrollo del portal en la misma aplicación de función. Cuando cree y publique funciones desde un proyecto local, no podrá mantener o modificar el código del proyecto en el portal.

Para desarrollar funciones en el equipo local y publicarlas en Azure utilizando Core Tools siga estos pasos básicos:

Requisitos previos

Los requisitos previos específicos de Core Tools dependen de las características que planea usar:

Publicación: Core Tools actualmente depende de la CLI de Azure o de Azure PowerShell para la autenticación con su cuenta de Azure. Esto significa que debe instalar alguna de estas herramientas para poder realizar la publicación en Azure desde Azure Functions Core Tools.

Instalación de extensiones: para instalar manualmente extensiones mediante Core Tools, debe tener instalado el SDK de .NET Core 3.1.x. Core Tools usa el SDK de .NET Core para instalar extensiones de NuGet. No es necesario tener conocimientos de .NET para usar las extensiones de Azure Functions.

Versiones de Core Tools

Hay cuatro versiones de Azure Functions Core Tools. La versión que use depende del entorno de desarrollo local, la elección del lenguaje y el nivel de compatibilidad necesario.

Elija una pestaña de versión a continuación para obtener información sobre cada versión específica y para obtener instrucciones de instalación detalladas:

Admite la versión 4.x del runtime de Functions. Esta versión admite Windows, macOS y Linux, y emplea administradores de paquetes específicos de la plataforma o npm para la instalación. Esta es la versión recomendada del entorno de ejecución de Functions y Core Tools.

Solo puede instalar una versión de Core Tools en un equipo determinado. A menos que se indique lo contrario, los ejemplos de este artículo son para la versión 3.x.

Instalación de Azure Functions Core Tools

Azure Functions Core Tools incluye una versión del mismo tiempo de ejecución de Azure Functions que puede ejecutar en el equipo de desarrollo local. También proporciona comandos para crear funciones, conectarse a Azure e implementar proyectos de funciones.

A partir de la versión 2.x, Core Tools se ejecuta en Windows,macOS y Linux.

En los pasos siguientes se utiliza Windows Installer (MSI) para instalar Core Tools v4.x. Para más información sobre otros instaladores basados en paquetes, consulte el archivo Léame de Core Tools.

Descargue y ejecute el instalador de Core Tools según su versión de Windows:

Cambio de las versiones de Core Tools

Al cambiar a una versión diferente de Core Tools, debe usar el mismo administrador de paquetes que la instalación original para pasar a otra versión del paquete. Por ejemplo, si instaló la versión 2.x de Core Tools mediante npm, debe usar el siguiente comando para actualizar a la versión 3.x:

npm install -g azure-functions-core-tools@3 --unsafe-perm true

Si usó Windows instalador (MSI) para instalar Core Tools en Windows, debe desinstalar la versión anterior desde Agregar quitar programas antes de instalar otra versión.

Creación de un proyecto local de Functions

Un directorio de proyecto de Functions contiene los siguientes archivos y carpetas, independientemente del lenguaje:

Nombre de archivo Descripción
host.json Para obtener más información, consulte la referencia de host.json.
local.settings.json Configuración que usa Core Tools cuando se ejecuta localmente, incluida la configuración de la aplicación. Para obtener más información, consulte Configuración local.
.gitignore Impide que el archivo local.settings.json se publique accidentalmente en un repositorio de Git. Para obtener más información, consulte Configuración local.
.vscode\extensions.json Archivo de configuración que se usa al abrir la carpeta del proyecto en Visual Studio Code.

Para obtener más información sobre la carpeta del proyecto de Functions, consulte la Guía para desarrolladores de Azure Functions.

En la ventana de terminal o desde un símbolo del sistema, ejecute el siguiente comando para crear el proyecto y el repositorio de Git local:

func init MyFunctionProj

En este ejemplo se crea un proyecto de Functions en una carpeta nueva MyFunctionProj. Se le pedirá que elija un lenguaje predeterminado para el proyecto.

Tenga en cuenta lo siguiente al inicializar el proyecto:

  • Si no proporciona la opción --worker-runtime en el comando, se le pedirá que elija el lenguaje. Para obtener más información, consulte la referencia de func init.

  • Si no proporciona un nombre de proyecto, se inicializa la carpeta actual.

  • Si tiene previsto publicar el proyecto en un contenedor de Linux personalizado, use la opción --docker para asegurarse de que se genere un Dockerfile para el proyecto. Para obtener más información, consulte Creación de una función en Linux con una imagen personalizada.

Es posible que deba tener en cuenta otros aspectos con algunos lenguajes:

  • Core Tools permite crear proyectos de aplicación de funciones para el runtime de .NET como proyectos de biblioteca de clases de C# (.csproj) en proceso y de proceso de trabajo aislado. Estos proyectos, que se pueden usar con Visual Studio o con Visual Studio Code, se compilan durante la depuración y al publicar en Azure.

  • Use el parámetro --csx si desea trabajar localmente con archivos de script de C# (.csx). Estos son los mismos archivos que se obtienen al crear funciones en Azure Portal y cuando se usa la versión 1.x de Core Tools. Para obtener más información, consulte la referencia de func init.

Registro de las extensiones

A partir de la versión 2.x del entorno de ejecución, los desencadenadores y enlaces de Functions se implementan como paquetes (NuGet) con la extensión .NET. En el caso de proyectos de C# compilados, basta con que haga referencia a los paquetes de extensión NuGet de los desencadenadores y enlaces específicos que use. Los enlaces HTTP y los desencadenadores de temporizador no requieren extensiones.

Con el fin de mejorar la experiencia de desarrollo para proyectos que no son de C#, Functions le permite hacer referencia a un conjunto de extensiones con versión en su archivo de proyecto host.json. Los conjuntos de extensiones ponen todas las extensiones a disposición de su aplicación y eliminan la posibilidad de que haya problemas de compatibilidad de paquetes entre extensiones. Los conjuntos de extensiones también eliminan el requisito de instalar el SDK de .NET Core 3.1 y de tener que gestionar el archivo extensions.csproj.

Los conjuntos de extensiones son el enfoque recomendado para los proyectos de Functions que no se han compilado con C#, así como el script C#. Para estos proyectos, el valor de conjunto de extensiones se genera en el archivo host.json durante la inicialización. Si las agrupaciones no están habilitadas, debe actualizar el archivo host.json del proyecto.

La forma más fácil de instalar extensiones de enlace es habilitar conjuntos de extensiones. Al habilitar agrupaciones, un conjunto predefinido de paquetes de extensiones se instala automáticamente.

Para habilitar las agrupaciones de extensiones, abra el archivo host.json y actualice su contenido para que coincida con el siguiente código:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[2.*, 3.0.0)"
    }
}

Para obtener más información, consulte Register Azure Functions binding extensions (Registrar las extensiones de enlace de Azure Functions).

En un proyecto que no sea de .NET, puede haber casos en los que no se puedan usar conjuntos de extensiones, por ejemplo, cuando necesite tener como destino una versión específica de una extensión que no esté en el conjunto. En estos casos excepcionales, puede usar Core Tools para instalar localmente los paquetes de extensión específicos que necesita el proyecto. Para obtener más información, consulte Instalación de extensiones.

Configuración local

Cuando se ejecuta en una aplicación de funciones de Azure, la configuración requerida por las funciones se almacena de forma segura en la configuración de la aplicación. Durante el desarrollo local, esta configuración se agrega en su lugar al objeto Values del archivo local.settings.json. El archivo local.settings.json almacena también la configuración que usan las herramientas locales de desarrollo.

Dado que local.settings.json puede contener secretos, como cadenas de conexión, nunca debe almacenarlo en un repositorio remoto. Para más información sobre la configuración local, consulte Archivo de configuración local.

De manera predeterminada, estas opciones de configuración no se migran automáticamente cuando el proyecto se publica en Azure. Use la opción --publish-local-settings cuando publique para asegurarse de que la configuración se agregue a la aplicación de funciones en Azure. Los valores de la sección ConnectionStrings no se publican nunca.

Esta configuración de la aplicación de función también se puede leer en el código como variables de entorno. Para más información, consulte la sección Variables de entorno de estos temas de referencia específicos del lenguaje:

Cuando no se establece ninguna cadena de conexión de almacenamiento válida para AzureWebJobsStorage y no se usa un emulador, de almacenamiento local, se muestra el siguiente mensaje de error:

Missing value for AzureWebJobsStorage in local.settings.json. This is required for all triggers other than HTTP. Puede ejecutar "FUNC Azure functionapp fetch-App-Settings <functionAppName>" o especificar una cadena de conexión en local. Settings. JSON.

Obtención de las cadenas de conexión de almacenamiento

Aunque use el Emulador de Microsoft Azurite Storage para tareas de desarrollo, le recomendamos ejecutarlo localmente con una conexión de almacenamiento real. Suponiendo que ya ha creado una cuenta de almacenamiento, puede obtener una cadena de conexión de almacenamiento válida de una de las maneras siguientes:

  1. En Azure Portal, busque y seleccione Cuentas de almacenamiento.

    Selección de cuentas de almacenamiento desde Azure Portal

  2. Seleccione la cuenta de almacenamiento, elija Claves de acceso en Configuración y, a continuación, copie uno de los valores de Cadena de conexión.

    Copia de una cadena de conexión desde Azure Portal

Creación de una función

Para crear una función en un proyecto existente, ejecute el siguiente comando:

func new

En la versión 3.x/2.x, cuando ejecute func new, se le pedirá que elija una plantilla en el lenguaje predeterminado de su aplicación de funciones. A continuación, se le pedirá que elija un nombre para la función. En la versión 1.x, también se le pedirá que elija el lenguaje.

También puede especificar el nombre y la plantilla de la función en el comando func new. En el siguiente ejemplo se usa la opción --template para crear un desencadenador HTTP denominado MyHttpTrigger:

func new --template "Http Trigger" --name MyHttpTrigger

En este ejemplo se crea un desencadenador de Queue Storage denominado MyQueueTrigger:

func new --template "Azure Queue Storage Trigger" --name MyQueueTrigger

Para obtener más información, consulte el comando func new.

Ejecución local de funciones

Para ejecutar un proyecto de Functions, ejecute el host de Functions desde el directorio raíz del proyecto. El host habilita desencadenadores para todas las funciones del proyecto. El comando start varía en función del lenguaje del proyecto.

func start

Nota

En la versión 1.x del runtime de Functions, se requiere func host start. Para obtener más información, consulte Referencia de Azure Functions Core Tools.

Cuando se inicia el host de Functions, devuelve la dirección URL de las funciones desencadenadas por HTTP, como en el siguiente ejemplo:

Found the following functions:
Host.Functions.MyHttpTrigger

Job host started
Http Function MyHttpTrigger: http://localhost:7071/api/MyHttpTrigger

Importante

Cuando se ejecuta localmente, no se aplica la autorización para puntos de conexión HTTP. Esto significa que todas las solicitudes HTTP locales se tratan como authLevel = "anonymous". Para obtener más información, consulte el artículo sobre enlaces HTTP.

Paso de datos de prueba a una función

Para probar sus funciones localmente, inicie el host de Functions y llame a puntos de conexión del servidor local mediante solicitudes HTTP. El punto de conexión al que llama depende del tipo de función.

Nota

En los ejemplos de este tema se usa la herramienta cURL para enviar solicitudes HTTP desde el terminal o un símbolo del sistema. Puede usar una herramienta de su elección para enviar solicitudes HTTP al servidor local. La herramienta cURL está disponible de forma predeterminada en los sistemas basados en Linux y en la compilación 17063 de Windows 10, y en las posteriores. En las versiones anteriores de Windows, primero debe descargar e instalar la herramienta cURL.

Para obtener información más general sobre cómo probar funciones, consulte Estrategias para probar el código en Azure Functions.

Funciones desencadenadas por HTTP y webhook

Llama al siguiente punto de conexión para ejecutar de forma local funciones desencadenadas por HTTP y webhook:

http://localhost:{port}/api/{function_name}

Asegúrese de usar el mismo nombre del servidor y puerto en el que escucha el host de Functions. Puede ver esto en la salida generada al iniciar el host de Functions. Puede llamar a esta dirección URL mediante cualquier método HTTP admitido por el desencadenador.

El siguiente comando cURL desencadena la función de inicio rápido MyHttpTrigger desde una solicitud GET con el parámetro name transferido en la cadena de consulta.

curl --get http://localhost:7071/api/MyHttpTrigger?name=Azure%20Rocks

En el siguiente ejemplo está la misma función a la que se llama desde una solicitud POST que transfiere name en el cuerpo de la solicitud:

curl --request POST http://localhost:7071/api/MyHttpTrigger --data '{"name":"Azure Rocks"}'

Puede realizar solicitudes GET desde un explorador que transfiere datos en la cadena de consulta. Para todos los demás métodos HTTP, debe usar cURL, Fiddler, Postman o una herramienta de pruebas HTTP similar que admita solicitudes POST.

Funciones no desencadenadas por HTTP

Para todas las funciones que no sean desencadenadores HTTP y Event Grid, puede probar sus funciones localmente mediante REST llamando a un punto de conexión especial denominado punto de conexión de administración. Al llamar a este punto de conexión con una solicitud HTTP POST en el servidor local se desencadena esta función.

Para probar las funciones de Event Grid desencadenadas localmente, consulte Pruebas locales con la aplicación web de visor.

Opcionalmente, puede transferir los datos de prueba a la ejecución en el cuerpo de la solicitud POST. Esta funcionalidad es similar a la pestaña Prueba de Azure Portal.

Se llama al siguiente punto de conexión de administrador para desencadenar funciones ajenas a HTTP:

http://localhost:{port}/admin/functions/{function_name}

Para transferir datos de prueba al punto de conexión de administrador de una función, debe proporcionar los datos en el cuerpo de un mensaje de solicitud POST. Es necesario que el cuerpo del mensaje tenga el siguiente formato JSON:

{
    "input": "<trigger_input>"
}

El valor <trigger_input> contiene datos en un formato esperado por la función. El siguiente ejemplo de cURL es una solicitud POST dirigida a una función QueueTriggerJS. En este caso, la entrada es una cadena que equivale al mensaje que se espera encontrar en la cola.

curl --request POST -H "Content-Type:application/json" --data '{"input":"sample queue data"}' http://localhost:7071/admin/functions/QueueTrigger

Al llamar a un punto de conexión de administración en su aplicación de funciones de Azure, debe proporcionar una clave de acceso. Para obtener más información, consulte Claves de acceso de función.

Publicación en Azure

Azure Functions Core Tools admite dos tipos de implementación:

Tipo de implementación Get-Help Descripción
Archivos de proyecto func azure functionapp publish Implementa los archivos de proyecto de función directamente en su aplicación de funciones usando la implementación mediante ZIP.
Clúster de Kubernetes func kubernetes deploy Implementa la aplicación de funciones de Linux como contenedor de Docker personalizado en un clúster de Kubernetes.

Antes de publicar

Importante

Debe tener la CLI de Azure o Azure PowerShell instalados localmente para poder realizar la publicación en Azure desde Core Tools.

Una carpeta de proyecto puede contener archivos y directorios específicos del idioma que no deben publicarse. Los elementos excluidos se enumeran en un archivo .funcignore en la carpeta raíz del proyecto.

Tiene que tener creada una aplicación de funciones en su suscripción de Azure para implementar su código. Se deben compilar los proyectos que lo requieran para poder implementar los archivos binarios.

Para obtener información sobre cómo crear una aplicación de función desde el símbolo del sistema o la ventana de Terminal mediante la CLI de Azure o Azure PowerShell, vea Creación de una aplicación de función para la ejecución de código sin servidor.

Importante

Cuando se crea una aplicación de función en Azure Portal, se usa la versión 3.x del entorno de ejecución de Functions de forma predeterminada. Para hacer que la aplicación de función utilice la versión 1.x del entorno de ejecución, siga las instrucciones de Ejecución en la versión 1.x. No se puede cambiar la versión del entorno de ejecución de una aplicación de función que tiene funciones existentes.

Implementación de los archivos de proyecto

Para publicar su código local en una aplicación de funciones en Azure, use el comando publish:

func azure functionapp publish <FunctionAppName>

Tenga en cuenta los siguientes aspectos con relación a este tipo de implementación:

  • Al publicar, se sobrescriben los archivos existentes en la aplicación de funciones.

  • Use la opción --publish-local-settings para crear automáticamente la configuración de aplicación en su aplicación de funciones a partir de los valores del archivo local.settings.json.

  • En proyectos compilados se lleva a cabo una compilación remota. Esta acción se puede controlar usando la opción --no-build.

  • Su proyecto se implementa de tal forma que se ejecute desde el paquete de implementación. Para deshabilitar este modo de implementación recomendado, use la opción --nozip.

  • Java utiliza Maven para publicar el proyecto local en Azure. Para publicar proyectos en Azure, use en su lugar el siguiente comando: mvn azure-functions:deploy. Durante la implementación inicial se crean recursos de Azure.

  • Obtendrá un error si intenta publicarla en un <FunctionAppName> que no exista en su suscripción.

Clúster de Kubernetes

Functions también le permite definir su proyecto de la plataforma para que se ejecute en un contenedor de Docker. Use la opción --docker de func init con el fin de generar un Dockerfile para su lenguaje específico. Este archivo se usa posteriormente al crear un contenedor para implementar. Para obtener información sobre cómo publicar un contenedor personalizado en Azure sin Kubernetes, consulte Creación de una función en Linux con un contenedor personalizado.

Core Tools se puede usar para implementar el proyecto como una imagen de contenedor personalizada en un clúster de Kubernetes.

El siguiente comando usa el Dockerfile para generar un contenedor e implementarlo en un clúster de Kubernetes.

func kubernetes deploy --name <DEPLOYMENT_NAME> --registry <REGISTRY_USERNAME> 

Para obtener más información, consulte Implementación de una aplicación de funciones en Kubernetes.

Instalar extensiones

Si no puede usar paquetes de extensión, utilice Azure Functions Core Tools localmente para instalar los paquetes de extensión específicos que requiere el proyecto.

Importante

No se pueden instalar extensiones explícitamente en una aplicación de función con conjuntos de extensiones habilitados. Primero, antes de instalar las extensiones explícitamente, quite la sección extensionBundle en host.json.

En los siguientes elementos se describen algunos de los motivos por los que es posible que tenga que instalar las extensiones manualmente:

  • Debe tener acceso a una versión específica de una extensión que no está disponible en un conjunto.
  • Debe tener acceso a una extensión personalizada que no está disponible en un conjunto.
  • Debe tener acceso a una combinación específica de extensiones que no está disponible en un único conjunto.

Cuando se instalan las extensiones explícitamente, se agrega un archivo de proyecto .NET denominado extensions.csproj a la raíz del proyecto. Este archivo define el conjunto de paquetes NuGet requeridos por las funciones. Aunque puede trabajar con las referencias de paquetes de NuGet en este archivo, las herramientas principales le permiten instalar extensiones sin tener que editar manualmente este archivo del proyecto C#.

Hay varias maneras de usar las herramientas principales para instalar las extensiones necesarias en el proyecto local.

Instalación de todas las extensiones

Utilice el comando siguiente para agregar automáticamente todos los paquetes de extensiones que usan los enlaces del proyecto local:

func extensions install

El comando lee el archivo function.json para ver qué paquetes necesita, los instala y, luego, recompila el proyecto de extensiones. Agrega los nuevos enlaces en la versión actual, pero no actualiza los enlaces existentes. Use la opción --force para actualizar los enlaces existentes a la versión más reciente cuando instale otros nuevos. Para obtener más información, vea el comando func extensions install.

Si la aplicación de función usa enlaces que Core Tools o los paquetes de NuGet no reconocen, debe instalar manualmente la extensión específica.

Instalación de una extensión específica

Utilice el siguiente comando para instalar un paquete de extensiones específico en una versión específica, en este caso la extensión de almacenamiento:

func extensions install --package Microsoft.Azure.WebJobs.Extensions.Storage --version 5.0.0

Puede usar este comando para instalar cualquier paquete de NuGet compatible. Para obtener más información, consulte el comando func extensions install.

Supervisión de funciones

La forma recomendada de supervisar la ejecución de sus funciones, es usar la integración con Azure Application Insights. También puede transmitir los registros de ejecución al equipo local. Para más información, consulte Supervisión de Azure Functions.

Integración de Application Insights

Al crear la aplicación de funciones en Azure, la integración de Application Insights debe estar habilitada. Si, por alguna razón, la aplicación de funciones no está conectada a una instancia de Application Insights, es fácil llevar a cabo esta integración en Azure Portal. Para más información, consulte Habilitación de la integración de Application Insights.

Habilitación de los registros de streaming

Puede ver una secuencia de archivos de registro que generan las funciones en una sesión de línea de comandos en el equipo local.

Streaming integrado de registros

Use el comando func azure functionapp logstream para empezar a recibir registros de streaming de una aplicación de funciones específica que se ejecuta en Azure, como en el ejemplo siguiente:

func azure functionapp logstream <FunctionAppName>

Nota

El streaming de registro integrado aún no se ha habilitado en Core Tools para las aplicaciones de funciones que se ejecutan en Linux en un plan de consumo. En estos planes de hospedaje, es preciso usar Live Metrics Stream para ver los registros casi en tiempo real.

Secuencia de métricas en directo

La información de Live Metrics Stream de una aplicación de funciones se puede ver en una ventana nueva del explorador. Para ello, hay que incluir la opción --browser, como se hace en el ejemplo siguiente:

func azure functionapp logstream <FunctionAppName> --browser

Este tipo de registros de streaming requiere que se habilite la integración de Application Insights para la aplicación de funciones.

Emulación x86 en ARM64

Functions no admite actualmente el desarrollo de funciones de Python local en dispositivos ARM64. Siga estos pasos para desarrollar funciones de Python en un equipo Mac con un chip M1 mediante la ejecución en un entorno x86 emulado.

Habilitación de Rosetta en Terminal

  1. En el equipo Mac, abra Finder, elija Aplicaciones y busque Terminal.

  2. Haga clic en Terminal y seleccione Obtener información. También puede crear un entorno paralelo independiente duplicando el Terminal y cambiando su nombre.

    Captura de pantalla de la selección de Obtener información haciendo clic en Terminal

  3. Seleccione Abrir con Rosetta.

    Captura de pantalla del Terminal configurado para abrirse mediante Rosetta

  4. Abra Terminal, que ahora tiene Rosetta habilitado y asegúrese de que el shell es zsh.

  5. Ejecute el siguiente comando para validar la emulación x86.

    $ arch
    

    Una respuesta de i386 indica que el terminal ejecuta un entorno emulado x86.

Instalación de los paquetes requeridos

Vuelva a instalar todas las dependencias requeridas por Functions en este entorno, que incluye los siguientes paquetes:

Además, vuelva a instalar los demás paquetes requeridos por el proyecto de Python.

Establecer alias (opcional)

Opcionalmente, puede establecer alias para facilitar la referencia a las versiones correctas en Rosetta.

A continuación se muestra un ejemplo de cómo crear un archivo .zshrc para configurar el terminal zsh:

# file: .zshrc
# rosetta terminal setup
if [ $(arch) = "i386" ]; then
    alias python="/usr/local/bin/python3"
    alias brew86='/usr/local/bin/brew'
    alias pyenv86="arch -x86_64 pyenv"
    alias func="/usr/local/Cellar/azure-functions-core-tools@4/4.0.4785/func"
fi

Ejecute el comando siguiente para aplicar los alias:

$ source .zshrc

Valide que hace referencia a las versiones correctas mediante el comando which, como se muestra en los ejemplos siguientes:

Get-Help Respuesta de ejemplo
$ which python python: aliased to /usr/local/bin/python3
$ which func func: aliased to /usr/local/Cellar/azure-functions-core-tools@4/4.0.4785/func

Estas respuestas de ejemplo se basan en el archivo .zshrc del ejemplo anterior.

Ahora, está preparado para usar Azure Functions en el entorno x86 desde Terminal.

Si usa Visual Studio Code, puede integrar Rosetta con el Terminal integrado. Para obtener más información, consulte Habilitación de la emulación en Visual Studio Code.

Pasos siguientes

Aprenda a desarrollar, probar y publicar funciones de Azure mediante las herramientas principales de Azure Functions. Azure Functions Core Tools es código abierto que se hospeda en GitHub. Para notificar un error o realizar una solicitud de característica, abra un problema de GitHub.