Guía para desarrolladores de Azure Functions

En Azure Functions, determinadas funciones comparten algunos componentes y conceptos técnicos básicos, independientemente del idioma o el enlace que use. Antes de ir a detalles de aprendizaje específicos de un idioma o un enlace determinados, asegúrese de leer al completo esta información general que se aplica a todos ellos.

En este artículo se supone que ya ha leído la Información general sobre Azure Functions.

Código de función

Una función es el concepto principal en las funciones de Azure. Una función contiene dos elementos importantes: el código, que se puede escribir en diversos lenguajes, y la configuración, el archivo function.json. Con los lenguajes compilados, este archivo de configuración se genera automáticamente a partir de las anotaciones del código. Para los lenguajes de scripting, debe proporcionar el archivo de configuración.

El archivo function.json define el desencadenador de la función, los enlaces y otras opciones de configuración. Cada función tiene un solo desencadenador. Este archivo de configuración se usa en tiempo de ejecución para determinar los eventos que se supervisarán y cómo pasar datos y devolverlos al ejecutarse una función. El siguiente es un ejemplo de archivo function.json.

{
    "disabled":false,
    "bindings":[
        // ... bindings here
        {
            "type": "bindingType",
            "direction": "in",
            "name": "myParamName",
            // ... more depending on binding
        }
    ]
}

Para más información, consulte Conceptos básicos sobre los enlaces y desencadenadores de Azure Functions.

La propiedad bindings es donde configura los enlaces y los desencadenadores. Cada enlace comparte unos ajustes de configuración comunes y algunos parámetros que son específicos de un determinado tipo de enlace. Cada enlace requiere la siguiente configuración:

Aplicación de función

La aplicación de función proporciona un contexto de ejecución en Azure donde ejecutar las funciones. Como tal, es la unidad de implementación y administración de las funciones. Una aplicación de función se compone de una o varias funciones individuales que se administran, implementan y escalan conjuntamente. Todas las funciones de una aplicación de función comparten el mismo plan de precios, el mismo método de implementación y la misma versión en tiempo de ejecución. Una aplicación de función es como una forma de organizar y administrar las funciones de manera colectiva. Para obtener más información, vea Administración de una Function App en Azure Portal.

Estructura de carpetas

El código de todas las funciones de una aplicación de funciones está ubicado en una carpeta de proyecto raíz que contiene un archivo de configuración de host. El archivo host.json contiene configuraciones específicas del entorno de ejecución y está en la carpeta raíz de la aplicación de funciones. Un carpeta bin contiene paquetes y otros archivos de biblioteca que requiere la aplicación de funciones. Las estructuras de carpeta específicas necesarias para la aplicación de funciones dependen del lenguaje:

• Compilado en C# (.csproj)
• Script de C# (.csx)
• Script de F#
• Java
• JavaScript
• Python

Tanto en la versión 2.x como en las superiores del runtime de Functions, todas las funciones de la aplicación de función deben compartir la misma pila de lenguaje.

La estructura de carpetas anterior es la predeterminada (y recomendada) para una aplicación de función. Si desea cambiar la ubicación del archivo de código de una función, modifique la sección scriptFile del archivo function.json. Asimismo, para implementar el proyecto en la aplicación de función en Azure, se recomienda usar la implementación de paquetes. También puede usar herramientas existentes como la integración e implementación continuas y Azure DevOps.

Uso de herramientas locales y publicación

Las aplicaciones de función pueden crearse y publicarse con diversas herramientas, incluidas Visual Studio, Visual Studio Code, IntelliJ, Eclipse y Azure Functions Core Tools. Para más información, consulte Codificación y comprobación de las funciones de Azure Functions en un entorno local.

Edición de funciones en Azure Portal

El editor de funciones integrado en Azure Portal le permite actualizar el código y el archivo function.json directamente. Esto solo se recomienda para pequeños cambios o pruebas de concepto: el procedimiento recomendado es usar una herramienta de desarrollo local como VS Code.

Ejecución en paralelo

Cuando se producen varios eventos de desencadenado más rápido de lo que un tiempo de ejecución de función de un solo subproceso pueda procesarlos, el tiempo de ejecución puede invocar la función varias veces en paralelo. Si una aplicación de función usa el plan de hospedaje de consumo, esta aplicación podría escalarse horizontalmente de forma automática. Cada instancia de la aplicación de función, tanto si la aplicación se ejecuta en el plan de hospedaje de consumo como en el plan de hospedaje de App Service normal, puede procesar invocaciones de función simultáneas en paralelo mediante varios subprocesos. El número máximo de invocaciones de función simultáneas en cada instancia de aplicación de función varía según el tipo de desencadenador usado y lo recursos empleados por otras funciones dentro de la aplicación de función.

Versiones del entorno en tiempo de ejecución de Functions

Puede configurar la versión del entorno en tiempo de ejecución de Functions mediante la configuración de la aplicación FUNCTIONS_EXTENSION_VERSION. Por ejemplo, el valor "~3" indica que la aplicación de funciones utilizará 3.x como versión principal. Las aplicaciones de funciones se actualizan a las nuevas versiones secundarias a medida que se lanzan. Para más información y saber cómo ver la versión exacta de la aplicación de función, consulte Cómo seleccionar un destino para versiones en tiempo de ejecución de Azure Functions.

Repositorios

El código de Azure Functions es código abierto y está almacenado en repositorios de GitHub:

• Funciones de Azure
• Host de Azure Functions
• Portal de Azure Functions
• Plantillas de Azure Functions
• SDK de Azure WebJobs
• Extensiones del SDK de Azure WebJobs

Enlaces

Esta es una tabla de todos los enlaces admitidos.

En esta tabla se muestran los enlaces que son compatibles con las versiones principales del entorno en tiempo de ejecución de Azure Functions:

¹ A partir del entorno en tiempo de ejecución de la versión 2.x, se deben registrar todos los enlaces, excepto HTTP y el temporizador. Consulte Registro de extensiones de enlace.

² Los desencadenadores no se admiten en el plan de consumo. Requiere desencadenadores controlados por el runtime.

³ Solo se admite en Kubernetes, IoT Edge y otros modos autohospedados.

¿Tiene algún problema con errores procedentes de los enlaces? Revise la documentación de los códigos de error de los enlaces de Azure Functions.

Conexiones

El proyecto de función hace referencia a la información de conexión por nombre de su proveedor de configuración. No acepta directamente los detalles de conexión, lo que permite que se modifiquen en todos los entornos. Por ejemplo, una definición de desencadenador podría incluir una propiedad connection. Esta podría hacer referencia a una cadena de conexión, pero no puede establecer la cadena de conexión directamente en un objeto function.json. En su lugar, debe establecer connection en el nombre de una variable de entorno que contenga la cadena de conexión.

El proveedor de configuración predeterminado utiliza variables de entorno. Estas podrían establecerse mediante la Configuración de la aplicación cuando se ejecutan en el servicio Azure Functions, o desde el archivo de configuración local cuando el desarrollo se realiza localmente.

Valores de conexión

Cuando el nombre de la conexión se resuelve en un solo valor exacto, el tiempo de ejecución identifica el valor como una cadena de conexión, que normalmente incluye un secreto. Los detalles de una cadena de conexión se definen mediante el servicio al que quiere conectarse.

Sin embargo, un nombre de conexión también puede hacer referencia a una colección de varios elementos de configuración, útil para configurar las conexiones basadas en identidades. Las variables de entorno se pueden tratar como una colección mediante un prefijo compartido que termina en doble carácter de subrayado __. A continuación, se puede hacer referencia al grupo. Para ello, establezca el nombre de la conexión en este prefijo.

Por ejemplo, la propiedad connection de una definición de desencadenador de blob de Azure podría ser "Storage1". Siempre que no haya ningún valor de cadena único configurado por una variable de entorno denominada "Storage1", se podría usar una variable de entorno denominada Storage1__blobServiceUri para informar a la propiedad blobServiceUri de la conexión. Las propiedades de conexión son diferentes para cada servicio. Consulte la documentación del componente que utiliza la conexión.

Configuración de una conexión basada en identidades

Algunas conexiones de Azure Functions pueden estar configuradas para usar una identidad en lugar de un secreto. La compatibilidad depende de la extensión que utiliza la conexión. En algunos casos, es posible que aún se necesite una cadena de conexión en Functions aunque el servicio al que se está conectando admita conexiones basadas en identidades. Para obtener un tutorial sobre cómo configurar las aplicaciones de funciones con identidades administradas, consulte el tutorial Creación de una aplicación de funciones con conexiones basadas en identidades.

Las conexiones basadas en identidades son compatibles con los siguientes componentes:

Cuando se hospeda en el servicio de Azure Functions, las conexiones basadas en identidades usan una identidad administrada. La identidad asignada por el sistema se usa de manera predeterminada, aunque se puede especificar una identidad asignada por el usuario con las propiedades credential y clientID. Cuando se ejecuta en otros contextos, como el de desarrollo local, se usa en su lugar la identidad del desarrollador, aunque se puede personalizar. Consulte Desarrollo local con conexiones basadas en identidades.

Concesión de permiso a la identidad

Cualquier identidad que se utilice debe tener permisos para realizar las acciones previstas. Deberá asignar un rol en Azure RBAC mediante roles integrados o personalizados que proporcionen esos permisos.

Elija una de las pestaña a continuación para obtener información sobre los permisos de cada componente:

Propiedades comunes para conexiones basadas en identidades

Una conexión basada en identidades para un servicio de Azure acepta las siguientes propiedades comunes, en las que <CONNECTION_NAME_PREFIX> es el valor de la propiedad connection en la definición de desencadenador o enlace:

Es posible que se admitan opciones adicionales para un tipo de conexión determinado. Consulte la documentación del componente que realiza la conexión.

Desarrollo local con conexiones basadas en identidades

Cuando se ejecuta localmente, la configuración anterior indica al tiempo de ejecución que use la identidad del desarrollador local. La conexión intentará obtener un token de las siguientes ubicaciones, en orden:

• Una caché local compartida entre las aplicaciones de Microsoft
• El contexto del usuario actual en Visual Studio
• El contexto del usuario actual en Visual Studio Code
• El contexto del usuario actual en la CLI de Azure

Si ninguna de estas opciones produce un resultado satisfactorio, se producirá un error.

Dado que usa la identidad del desarrollador, es posible que ya tenga algunos roles en los recursos de desarrollo, pero es posible que no proporcionen acceso a los datos. Los roles de administración, como Propietario, no son suficientes. Compruebe los permisos necesarios para las conexiones de cada componente y asegúrese de que se le han asignado.

En algunos casos, puede especificar el uso de una identidad diferente. Puede agregar propiedades de configuración para la conexión que apunten a la identidad alternativa en función de un identificador de cliente y un secreto de cliente para una entidad de servicio de Azure Active Directory. No se admite esta opción de configuración cuando se hospedan en el servicio Azure Functions. Para usar un identificador y un secreto en el equipo local, defina la conexión con las siguientes propiedades adicionales:

Ejemplo de las propiedades local.settings.json requeridas para la conexión basada en identidades a blobs de Azure:

{
  "IsEncrypted": false,
  "Values": {
    "<CONNECTION_NAME_PREFIX>__blobServiceUri": "<blobServiceUri>",
    "<CONNECTION_NAME_PREFIX>__queueServiceUri": "<queueServiceUri>",
    "<CONNECTION_NAME_PREFIX>__tenantId": "<tenantId>",
    "<CONNECTION_NAME_PREFIX>__clientId": "<clientId>",
    "<CONNECTION_NAME_PREFIX>__clientSecret": "<clientSecret>"
  }
}

Conexión al almacenamiento de host con una identidad (versión preliminar)

De forma predeterminada, Azure Functions usa la conexión "AzureWebJobsStorage" para comportamientos básicos, como la coordinación de la ejecución de singleton de los desencadenadores de temporizador y el almacenamiento de claves de aplicación predeterminado. También puede configurarse para aprovechar una identidad.

Para usar una conexión basada en identidades para "AzureWebJobsStorage", configure las siguientes opciones de la aplicación:

También se pueden establecer Propiedades comunes para conexiones basadas en identidades.

Si se usa una cuenta de almacenamiento que utiliza el nombre del servicio y el sufijo DNS predeterminado para Azure global, con el formato https://<accountName>.blob/queue/file/table.core.windows.net, puede, en cambio, establecer AzureWebJobsStorage__accountName en el nombre de la cuenta de almacenamiento. Los puntos de conexión de blobs y colas se deducirán para esta cuenta. Esto no funcionará si la cuenta de almacenamiento está en una nube soberana o tiene un DNS personalizado.

Deberá crear una asignación de roles que proporcione acceso a la cuenta de almacenamiento para "AzureWebJobsStorage" en entorno de ejecución. Los roles de administración, como Propietario, no son suficientes. El rol de Propietario de datos de blobs de almacenamiento cubre las necesidades básicas del almacenamiento de host de Functions: el entorno de ejecución necesita acceso de lectura y escritura a blobs y la capacidad de crear contenedores. Existen algunas situaciones, como con el uso del desencadenador de blobs, en las que el Colaborador de datos de la cola de Storage también puede ser necesario. Puede que necesite permisos adicionales si usa "AzureWebJobsStorage" para cualquier otro fin.

Problemas de informes

Pasos siguientes

Para obtener más información, consulte los siguientes recursos:

• Enlaces y desencadenadores de Azure Functions
• Codificación y comprobación de Azure Functions en un entorno local
• Procedimientos recomendados de Azure Functions
• Referencia para desarrolladores de C# de Azure Functions
• Referencia para desarrolladores de Node.js de Azure Functions