Guía para desarrolladores de Azure Functions

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

En este artículo se supone que ya ha leído la información general 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 denominadas functions. 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 el proyecto de código de Azure Functions como un mecanismo para organizar, implementar y administrar colectivamente las 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. De manera opcional, 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 obtener más información, consulte Azure Functions desencadenadores y enlaces.

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 Azure Functions Core Tools para poder ejecutar y depurar en el equipo local mediante el runtime de Functions. Para obtener más información, consulte Code y pruebe Azure Functions localmente.

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. Una aplicación de funciones proporciona un contexto de ejecución en Azure en el que se ejecutan las funciones. Por lo tanto, 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 funciones se compone de una o varias funciones individuales que se administran, implementan y se escalan en conjunto. 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. Para obtener más información, consulte Cómo administrar una aplicación de funciones.

Cuando la aplicación de funciones y cualquier otro recurso necesario 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:

• Uso de Visual Studio Code

• Mediante programación mediante CLI de Azure, Azure PowerShell, ARM o Bicep

• En el portal Azure

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 obtener más información, consulte 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 en otros servicios en la nube y escribir datos en estos servicios. 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 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 obtener más información, consulte Azure Functions desencadenadores y enlaces.

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

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 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 variable de entorno namevalue pares. Para desencadenadores y enlaces que requieren una propiedad de conexión, establezca el nombre de configuración de la aplicación en lugar del cadena de conexión real. No se puede configurar un enlace directamente con una clave o un cadena de conexión.

Por ejemplo, considere una definición de desencadenador que tenga una propiedad . En lugar de la cadena de conexión, establezca connection en el nombre de una variable de entorno que contenga el 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 configuración de aplicación cuando se ejecuta en el Azure y en el archivo de configuración local al desarrollar localmente.

Valores de conexión

Cuando el nombre de conexión se resuelve en un único valor exacto, el tiempo de ejecución identifica el valor como un cadena de conexión, que normalmente incluye un secreto. Los detalles de un cadena de conexión dependen del servicio al que se conecte.

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 para una definición de desencadenador de blobs de Azure podría ser Storage1. Siempre que no haya ningún valor de cadena único configurado por una variable de entorno denominada , se podría usar una variable de entorno denominada para informar a la propiedad 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 se pueden configurar para usar una identidad en lugar de un secreto. La compatibilidad depende de la versión en tiempo de ejecución y de la extensión mediante la conexión. En algunos casos, es posible que todavía se requiera un cadena de conexión en Functions, aunque el servicio al que se conecte admite conexiones basadas en identidades. Para examinar un tutorial sobre cómo configurar las aplicaciones de funciones con identidades administradas, consulte Creación de una aplicación de funciones con conexiones basadas en identidades.

Las conexiones basadas en identidades solo se admiten en Functions 4.x, si usa la versión 1.x, primero debe migrar a la versión 4.x.

Los siguientes componentes admiten conexiones basadas en identidades:

Cuando se hospeda en el servicio Azure Functions, las conexiones basadas en identidad 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 y . Tenga en cuenta que no se admite la configuración de una identidad asignada por el usuario mediante un id. 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 Azure, esto significa que debe assignar un rol en Azure RBAC, mediante roles integrados o personalizados que proporcionan 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 identidad para un servicio Azure acepta las siguientes propiedades comunes, donde <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.

variables de entorno de SDK de Azure

También se pueden establecer las variables de entorno asociadas a la EnvironmentCredential de la SDK de Azure, pero el servicio Functions no los procesa para el escalado en planes de consumo. Estas variables de entorno no son específicas de ninguna conexión y se aplicarán como valor predeterminado a menos que no se establezca una propiedad correspondiente para una conexión determinada. Por ejemplo, si se establece , se usaría como si se hubiera configurado . Establecer explícitamente invalidaría este valor predeterminado.

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
• Contexto de usuario actual en Visual Studio
• Contexto de usuario actual en Visual Studio Code
• Contexto de usuario actual en el 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 Azure recursos 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 apunte a la identidad alternativa basada en un identificador de cliente y un secreto de cliente para una entidad de servicio de Microsoft Entra. Esta opción de configuración no se admite cuando se hospeda 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:

Este es un ejemplo de local.settings.json propiedades necesarias para la conexión basada en identidades a 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 , configure las siguientes opciones de la aplicación:

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

Si va a configurar AzureWebJobsStorage mediante una cuenta de almacenamiento que usa el sufijo DNS predeterminado y el nombre del servicio para la Azure global, siguiendo el formato https://<accountName>.[blob|queue|file|table].core.windows.net, puede 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.

Debe crear una asignación de roles que proporcione acceso a la cuenta de almacenamiento para "AzureWebJobsStorage" en tiempo 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. También puede necesitar otros permisos si usa "AzureWebJobsStorage" para cualquier otro propósito.

¹ Para algunos tipos de problemas, Azure Functions puede generar un evento de diagnóstico que pueda ayudar a solucionar problemas, incluso cuando el problema impide que se inicie la aplicación de funciones. Si no se asigna Colaborador de datos de tabla de almacenamiento, podría ver advertencias en los registros sobre la incapacidad de escribir estos eventos.

Conexión a un recurso en otro entorno

Si la función necesita conectarse a un recurso de un inquilino de Microsoft Entra diferente, la conexión debe usar una credencial de identidad federated. Esto requiere una identidad administrada asignada por el usuario y un registro de aplicación de id. de Entra multiinquilino. No se puede usar una identidad administrada asignada por el sistema para las conexiones entre inquilinos.

Para configurar una conexión basada en identidades entre inquilinos, primero debe configurar la infraestructura mediante los pasos siguientes:

1. En el inquilino donde se implementa la aplicación de funciones, cree una nueva identidad administrada asignada por el usuario.
2. Asigne esa identidad a la aplicación de funciones.
3. En el mismo inquilino, cree un registro de aplicación Entra multiinquilino que represente el recurso entre inquilinos al que desea acceder.
4. Agregue la identidad administrada como una credencial de identidad federada para el registro de la aplicación.
5. En el inquilino donde se implementa el recurso, cree una aplicación empresarial para el registro de la aplicación.
6. Asigne permisos para que la aplicación empresarial acceda al recurso.

Una conexión basada en identidades entre inquilinos usa las siguientes propiedades, donde es el valor de la propiedad en la definición de desencadenador o enlace:

1 Cuando se establece en , la conexión debe especificar exactamente uno de , o .

Esto también se documentado por el SDK de Azure en un formato JSON.

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:

• Azure Functions

• Azure Functions host

• plantillas Azure Functions

• Azure SDK de WebJobs

• Azure extensiones del SDK de WebJobs

Pasos siguientes

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

• escenarios de Azure Functions
• Code y pruebe Azure Functions localmente
• Best Practices for Azure Functions