Desarrollo de extensiones de trabajo de Python para Azure Functions

Nota:

A partir de Python 3.13, las extensiones de trabajo de Python ya no se admitirán.

Azure Functions le permite integrar comportamientos personalizados como parte de la ejecución de funciones de Python. Esta característica permite crear lógica de negocios que los clientes puedan usar fácilmente en sus propias aplicaciones de funciones. Las extensiones de trabajo se admiten en los modelos de programación de Python v1 y v2.

En este tutorial, aprenderá a:

Cree una extensión de trabajo de Python de nivel de aplicación para Azure Functions.
Consumir la extensión en una aplicación tal como lo hacen los clientes
Empaquetar y publicar una extensión para su uso.

Prerrequisitos

Antes de empezar, debe cumplir estos requisitos:

Python 3.7 o versiones posteriores. Para consultar la lista completa de las versiones compatibles de Python en Azure Functions, consulte la Guía para desarrolladores de Python.
Azure Functions Core Tools, versión 4.0.5095 o posterior, que admite el uso de la extensión con el modelo de programación de Python v2. Compruebe la versión con func --version.
Tener instalado Visual Studio Code en una de las plataformas compatibles.

Creación de la extensión python Worker

La extensión que crea notifica el tiempo transcurrido de una invocación de desencadenador HTTP en los registros de la consola y en el cuerpo de la respuesta HTTP.

Estructura de carpetas

La carpeta del proyecto de extensión debe ser similar a la estructura siguiente:

<python_worker_extension_root>/
 | - .venv/
 | - python_worker_extension_timer/
 | | - __init__.py
 | - setup.py
 | - readme.md

Carpeta o archivo	Description
.venv/	(Opcional) Contiene un entorno virtual de Python que se usa para el desarrollo local.
python_worker_extension/	Contiene el código fuente de la extensión de trabajo de Python. Esta carpeta contiene el módulo principal de Python que se va a publicar en PyPI.
setup.py	Contiene los metadatos del paquete de extensión de trabajo de Python.
readme.md	Contiene las instrucciones y el uso de tu extensión. Este contenido se muestra como la descripción de la página principal del proyecto pyPI.

Configuración de metadatos del proyecto

En primer lugar, cree setup.py, que proporciona información esencial sobre el paquete. Para asegurarse de que la extensión se distribuya e integre correctamente en las aplicaciones de funciones de su cliente, confirme que 'azure-functions >= 1.7.0, < 2.0.0' está en la sección install_requires.

En la plantilla siguiente, debe cambiar los campos author, author_email, install_requires, license, packages, y url según sea necesario.

from setuptools import find_packages, setup
setup(
    name='python-worker-extension-timer',
    version='1.0.0',
    author='Your Name Here',
    author_email='your@email.here',
    classifiers=[
        'Intended Audience :: End Users/Desktop',
        'Development Status :: 5 - Production/Stable',
        'Intended Audience :: End Users/Desktop',
        'License :: OSI Approved :: Apache Software License',
        'Programming Language :: Python',
        'Programming Language :: Python :: 3.7',
        'Programming Language :: Python :: 3.8',
        'Programming Language :: Python :: 3.9',
        'Programming Language :: Python :: 3.10',
    ],
    description='Python Worker Extension Demo',
    include_package_data=True,
    long_description=open('readme.md').read(),
    install_requires=[
        'azure-functions >= 1.7.0, < 2.0.0',
        # Any additional packages that will be used in your extension
    ],
    extras_require={},
    license='MIT',
    packages=find_packages(where='.'),
    url='https://your-github-or-pypi-link',
    zip_safe=False,
)

A continuación, implementará el código de extensión en el ámbito de nivel de aplicación.

Implementación de la extensión del temporizador

Agregue el código siguiente en python_worker_extension_timer/__init__.py para implementar la extensión de nivel de aplicación:

import typing
from logging import Logger
from time import time
from azure.functions import AppExtensionBase, Context, HttpResponse
class TimerExtension(AppExtensionBase):
    """A Python worker extension to record elapsed time in a function invocation
    """

    @classmethod
    def init(cls):
        # This records the starttime of each function
        cls.start_timestamps: typing.Dict[str, float] = {}

    @classmethod
    def configure(cls, *args, append_to_http_response:bool=False, **kwargs):
        # Customer can use TimerExtension.configure(append_to_http_response=)
        # to decide whether the elapsed time should be shown in HTTP response
        cls.append_to_http_response = append_to_http_response

    @classmethod
    def pre_invocation_app_level(
        cls, logger: Logger, context: Context,
        func_args: typing.Dict[str, object],
        *args, **kwargs
    ) -> None:
        logger.info(f'Recording start time of {context.function_name}')
        cls.start_timestamps[context.invocation_id] = time()

    @classmethod
    def post_invocation_app_level(
        cls, logger: Logger, context: Context,
        func_args: typing.Dict[str, object],
        func_ret: typing.Optional[object],
        *args, **kwargs
    ) -> None:
        if context.invocation_id in cls.start_timestamps:
            # Get the start_time of the invocation
            start_time: float = cls.start_timestamps.pop(context.invocation_id)
            end_time: float = time()
            # Calculate the elapsed time
            elapsed_time = end_time - start_time
            logger.info(f'Time taken to execute {context.function_name} is {elapsed_time} sec')
            # Append the elapsed time to the end of HTTP response
            # if the append_to_http_response is set to True
            if cls.append_to_http_response and isinstance(func_ret, HttpResponse):
                func_ret._HttpResponse__body += f' (TimeElapsed: {elapsed_time} sec)'.encode()

Este código hereda de AppExtensionBase para que la extensión se aplique a todas las funciones de la aplicación. Podrías haber también implementado la extensión en un ámbito de nivel de función heredando de FuncExtensionBase.

El init método es un método de clase al que llama el trabajador cuando se importa la clase de extensión. Puede realizar acciones de inicialización aquí para la extensión. En este caso, se inicializa un mapa hash para registrar el tiempo de inicio de la invocación para cada función.

El configure método está orientado al cliente. En el archivo Léame, puede indicar a los clientes cuándo necesitan llamar a Extension.configure(). El archivo Léame también debe documentar las funcionalidades de la extensión, su posible configuración y su uso. En este ejemplo, los clientes pueden elegir si se notifica el tiempo transcurrido en .HttpResponse

El trabajo de Python llama al método pre_invocation_app_level antes de que se ejecute la función. Proporciona la información de la función, como el contexto de función y los argumentos. En este ejemplo, la extensión registra un mensaje y registra la hora de inicio de una invocación en función de su invocation_id.

Del mismo modo, se llama a post_invocation_app_level después de la ejecución de la función. En este ejemplo se calcula el tiempo transcurrido en función de la hora de inicio y la hora actual. También sobrescribe el valor devuelto de la respuesta HTTP.

Crear un léame.md

Cree un archivo readme.md en la raíz del proyecto de extensión. Este archivo contiene las instrucciones y el uso de la extensión. El contenido readme.md se muestra como la descripción de la página principal del proyecto pyPI.

# Python Worker Extension Timer

In this file, tell your customers when they need to call `Extension.configure()`.

The readme should also document the extension capabilities, possible configuration,
and usage of your extension.

Consumo local de la extensión

Ahora que ha creado una extensión, puede usarla en un proyecto de aplicación para comprobar que funciona según lo previsto.

Creación de una función desencadenada por HTTP

Cree una carpeta para el proyecto de aplicación y vaya a ella.
Desde el shell adecuado, como Bash, ejecute el siguiente comando para inicializar el proyecto:
```
func init --python
```
Use el siguiente comando para crear una nueva función de desencadenador HTTP que permita el acceso anónimo:
```
func new -t HttpTrigger -n HttpTrigger -a anonymous
```

Activación de un entorno virtual

Cree un entorno virtual de Python basado en el sistema operativo como se indica a continuación:
- Linux
- Windows
```
python3 -m venv .venv
```
```
py -m venv .venv
```
Active el entorno virtual de Python, en función del sistema operativo como se indica a continuación:
- Linux
- Windows
```
source .venv/bin/activate
```
```
.venv\Scripts\Activate.ps1
```

Configuración de la extensión

Instale paquetes remotos para el proyecto de aplicación de funciones mediante el comando siguiente:
```
pip install -r requirements.txt
```
Instale la extensión desde la ruta de acceso del archivo local, en modo editable como se indica a continuación:
```
pip install -e <PYTHON_WORKER_EXTENSION_ROOT>
```
En este ejemplo, reemplace por <PYTHON_WORKER_EXTENSION_ROOT> la ubicación del archivo raíz del proyecto de extensión.

Cuando un cliente usa la extensión, en su lugar agregará la ubicación del paquete de extensión al archivo requirements.txt, como en los ejemplos siguientes:
- PyPI
- GitHub
```
# requirements.txt
python_worker_extension_timer==1.0.0
```
```
# requirements.txt
git+https://github.com/Azure-Samples/python-worker-extension-timer@main
```
Abra el archivo de proyecto local.settings.json y agregue el siguiente campo a Values:
```
"PYTHON_ENABLE_WORKER_EXTENSIONS": "1" 
```
Cuando se ejecuta en Azure, en su lugar se agrega PYTHON_ENABLE_WORKER_EXTENSIONS=1 a la configuración de la aplicación en la aplicación de funciones.
Agregue las dos líneas siguientes antes de la main función en el archivo __init.py__ para el modelo de programación v1 o en el archivo function_app.py para el modelo de programación v2:
```
from python_worker_extension_timer import TimerExtension
TimerExtension.configure(append_to_http_response=True)
```
Este código importa el módulo TimerExtension y establece el valor de configuración append_to_http_response.

Verifica la extensión

En la carpeta raíz de tu proyecto de aplicación, inicia el host de funciones mediante func host start --verbose. Debería ver el endpoint local de su función en la salida como https://localhost:7071/api/HttpTrigger.
En el explorador, envíe una solicitud GET a https://localhost:7071/api/HttpTrigger. Debería ver una respuesta similar a la siguiente, con los datos TimeElapsed para la solicitud anexada.
```
This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response. (TimeElapsed: 0.0009996891021728516 sec)
```

Publica tu extensión

Después de crear y comprobar la extensión, todavía debe completar estas tareas de publicación restantes:

Elija una licencia.
Cree una readme.md y otra documentación.
Publique la biblioteca de extensiones en un registro de paquetes de Python o en un sistema de control de versiones (VCS).

PyPI
GitHub

Para publicar la extensión en PyPI:

Ejecute el siguiente comando para instalar twine y wheel en el entorno de Python predeterminado o en un entorno virtual:
```
pip install twine wheel
```
Quite la carpeta antigua dist/ del repositorio de extensiones.
Ejecute el siguiente comando para generar un nuevo paquete dentro dist/de :
```
python setup.py sdist bdist_wheel
```
Ejecute el siguiente comando para cargar el paquete en PyPI:
```
twine upload dist/*
```
Es posible que tenga que proporcionar las credenciales de la cuenta de PyPI durante la carga. También puede probar la carga del paquete con twine upload -r testpypi dist/*. Para más información, consulte la documentación de Twine.

Después de estos pasos, los clientes pueden usar la extensión mediante la inclusión del nombre del paquete en su requirements.txt.

Para más información, consulte el tutorial oficial de empaquetado de Python.

Examples

Puede ver el proyecto de extensión de ejemplo completado relacionado con este artículo en el repositorio de ejemplo python_worker_extension_timer.
La integración de OpenCensus es un proyecto de código abierto que usa la interfaz de extensión para integrar el seguimiento de telemetría en aplicaciones de Python de Azure Functions. Consulte el repositorio opencensus-python-extensions-azure para revisar la implementación de esta extensión de trabajo de Python.

Pasos siguientes

Para obtener más información sobre el desarrollo de Python de Azure Functions, consulte los siguientes recursos:

Ohar-bidaltzea

Lagungarria izan al da orrialde hau?

Last updated on 2026-01-16