Guía para desarrolladores de Azure Functions

En Azure Functions, todas las funciones comparten algunos conceptos y componentes técnicos básicos, sin importar su lenguaje o entorno de desarrollo preferido. Este artículo es específico del lenguaje. Elija su languaje preferido en la parte superior del artículo.

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

Proyecto de código

En el núcleo de Azure Functions es un proyecto de código específico del lenguaje que implementa una o varias unidades de ejecución de código llamada funciones. Las funciones son simplemente métodos que se ejecutan en la nube de Azure en función de eventos, en respuesta a solicitudes HTTP o según una programación. Piense en su proyecto de código de Azure Functions como un mecanismo para organizar, implementar y administrar colectivamente sus funciones individuales en el proyecto cuando se ejecutan en Azure. Para obtener más información, consulte Organizar funciones.

Todas las funciones deben tener un desencadenador, que define cómo se inicia la función y puede proporcionar entrada a la función. Opcionalmente, las funciones pueden definir enlaces de entrada y salida. Estos enlaces simplifican las conexiones a otros servicios sin tener que trabajar con los SDK de cliente. Para más información, vea Conceptos básicos sobre los enlaces y desencadenadores de Azure Functions.

Azure Functions proporciona un conjunto de plantillas de función y proyecto específicas del lenguaje que facilitan la creación de nuevos proyectos de código y la adición de funciones al proyecto. Puede usar cualquiera de las herramientas que admiten el desarrollo de Azure Functions para generar nuevas aplicaciones y funciones mediante estas plantillas.

Herramientas de desarrollo

Las siguientes herramientas proporcionan una experiencia integrada de desarrollo y publicación para Azure Functions en su lenguaje preferido:

• Visual Studio Code

• Azure Functions Core Tools (símbolo del sistema)

Estas herramientas se integran con las Azure Functions Core Tools para que pueda ejecutar y depurar en su equipo local utilizando el tiempo de ejecución de Functions. Para más información, consulte Codificación y comprobación de las funciones de Azure Functions en un entorno local.

Implementación

Al publicar el proyecto de código en Azure, básicamente va a implementar el proyecto en un recurso de aplicación de funciones existente. 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. Desde una perspectiva de recursos de Azure, una aplicación de funciones es equivalente a un recurso de sitio (Microsoft.Web/sites) en Azure App Service, que es equivalente a una aplicación web.

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 funciones comparten el mismo plan de precios, método de implementación y versión de tiempo de ejecución. Para más información, consulte Cómo administrar una aplicación de funciones.

Cuando la aplicación de funciones y otros recursos necesarios aún no existen en Azure, primero debe crear estos recursos para poder implementar los archivos del proyecto. Puede crear estos recursos de una de estas maneras:

• Mediante Visual Studio Code

• Uso mediante programación de la CLI de Azure, Azure PowerShell, plantillas de ARM o plantillas de Bicep

• En Azure Portal

Además de la publicación basada en herramientas, Functions admite otras tecnologías para implementar código fuente en una aplicación de funciones existente. Para más información, vea Tecnologías de implementación en Azure Functions.

Conexión a los servicios

Un requisito importante de cualquier servicio de proceso basado en la nube es leer datos de y escribir datos en otros servicios en la nube. Functions proporciona un amplio conjunto de enlaces que facilita la conexión a los servicios sin tener que trabajar con los SDK de cliente.

Tanto si usa las extensiones de enlace proporcionadas por Functions como si trabaja directamente con los SDK de cliente, almacena datos de conexión de forma segura y no los incluye en el código. Para obtener más información, consulte Conexiones.

Enlaces

Functions proporciona enlaces para muchos servicios de Azure y algunos servicios de terceros, que se implementan como extensiones. Para obtener más información, consulte la lista completa de enlaces admitidos.

Las extensiones de enlace pueden admitir entradas y salidas, y muchos desencadenadores también actúan como enlaces de entrada. Los enlaces permiten configurar la conexión a los servicios para que el host de Functions pueda controlar el acceso a los datos por usted. Para más información, vea Conceptos básicos sobre los enlaces y desencadenadores de Azure Functions.

Si tiene problemas con errores procedentes de enlaces, consulte la documentación Códigos de error de enlace de Azure Functions.

SDK de cliente

Aunque Functions proporciona enlaces para simplificar el acceso a datos en el código de función, todavía puede usar un SDK de cliente en el proyecto para acceder directamente a un servicio determinado, si lo prefiere. Es posible que tenga que usar los SDK de cliente directamente si las funciones requieren una funcionalidad del SDK subyacente que no es compatible con la extensión de enlace.

Al usar los SDK de cliente, debería usar el mismo proceso para almacenar y acceder a cadenas de conexión usadas por las extensiones de enlace.

Conexiones

Como procedimiento recomendado de seguridad, Azure Functions aprovecha la funcionalidad de configuración de la aplicación de Azure App Service para ayudarle a almacenar cadenas, claves y otros tokens de forma más segura necesarios para conectarse a otros servicios. La configuración de la aplicación en Azure se almacena cifrada y la aplicación puede acceder a ella en tiempo de ejecución como pares de variables de entornonamevalue. En el caso de los desencadenadores y enlaces que requieren una propiedad de conexión, establezca el nombre de la configuración de la aplicación en lugar de la cadena de conexión real. No se puede configurar un enlace directamente con una cadena de conexión o una clave.

Por ejemplo, considere una definición de desencadenador que tenga una propiedadconnection. En su lugar, debería establecer connection la conexión con el nombre de una variable de entorno que contiene la cadena de conexión. El uso de esta estrategia de acceso a secretos hace que las aplicaciones sean más seguras y facilita el cambio de conexiones entre entornos. Para obtener aún más seguridad, puede usar conexiones basadas en identidades.

El proveedor de configuración predeterminado utiliza variables de entorno. Estas variables se definen en la configuración de la aplicación cuando se ejecuta en Azure y en el archivo de configuración local al desarrollar 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 se requiera una cadena de conexión en Functions aunque el servicio al que se conecta 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.

Los siguientes componentes admiten conexiones basadas en identidades:

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. Tenga en cuenta que no se admite la configuración de una identidad asignada por el usuario con un identificador de recurso. 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. Para la mayoría de los servicios de Azure, esto significa que debe asignar un rol en Azure RBAC mediante roles integrados o personalizados que proporcionen esos permisos.

Elija una de estas pestañas 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 otras opciones 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 ejecuta su proyecto de función localmente, la configuración anterior le indica al tiempo de ejecución que use la identidad del desarrollador local. La conexión intenta 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.

Es posible que la identidad ya tenga algunas asignaciones de roles en los recursos de Azure usados para el desarrollo, pero es posible que esos roles no proporcionen el acceso a datos necesario. 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 Microsoft Entra. No se admite esta opción de configuración cuando se hospedan en el servicio Azure Functions. Para usar un Id. y un secreto en su máquina 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 para Azure Blobs:

{
  "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

El host de Azure Functions usa el conjunto de conexiones de almacenamiento en AzureWebJobsStorage para habilitar comportamientos principales, como coordinar la ejecución singleton de desencadenadores de temporizador y almacenamiento de claves de aplicación predeterminado. Esta conexión también se puede configurar para usar 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 configura AzureWebJobsStorage con una cuenta de almacenamiento que utiliza el nombre del servicio y el sufijo DNS predeterminados 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 para cada servicio de almacenamiento se deducen para esta cuenta. Esto no funciona cuando 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. Varias extensiones usan esta conexión como ubicación predeterminada para blobs, colas y tablas, y estos usos pueden agregar requisitos como se indica en la tabla siguiente. Puede que necesite permisos adicionales si usa "AzureWebJobsStorage" para cualquier otro fin.

Problemas de informes

Repositorios de código abierto

El código de Azure Functions es código abierto y puede encontrar componentes clave en estos 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

Pasos siguientes

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

• Escenarios de Azure Functions
• Codificación y comprobación de Azure Functions en un entorno local
• Procedimientos recomendados de Azure Functions