Desencadenador de Azure Blob Storage para Azure Functions

El desencadenador de Blob Storage inicia una función cuando se detecta un blob nuevo o actualizado. El contenido del blob se proporciona a modo de entrada para la función.

Sugerencia

Hay varias maneras de ejecutar el código de función según los cambios en los blobs de un contenedor de almacenamiento. Si decide usar el desencadenador de Blob Storage, tenga en cuenta que se ofrecen dos implementaciones: una basada en sondeo (a la que se hace referencia en este artículo) y una basada en eventos. Se recomienda usar la implementación basada en eventos, ya que tiene una latencia menor que la otra. Además, el plan de consumo flexible solo admite el desencadenador de Blob Storage basado en eventos.

Para más información sobre las diferencias entre las dos implementaciones del desencadenador de Blob Storage, así como otras opciones de desencadenamiento, consulte Trabajar con blobs.

Para obtener información sobre los detalles de instalación y configuración, consulte Introducción.

Importante

En este artículo se usan pestañas para admitir varias versiones del modelo de programación de Node.js. El modelo v4 está disponible de forma general y está diseñado para que los desarrolladores de JavaScript y TypeScript tengan una experiencia más flexible e intuitiva. Para más detalles acerca de cómo funciona el modelo v4, consulte la Guía para desarrolladores de Node.js de Azure Functions. Para más información sobre las diferencias entre v3 y v4, consulte la Guía de migración.

Azure Functions admite dos modelos de programación para Python. La forma en que defina los enlaces depende del modelo de programación seleccionado.

v2

El modelo de programación de Python v2 permite definir enlaces mediante decoradores directamente en el código de función de Python. Para más información, consulte la Guía para desarrolladores de Python.

v1

El modelo de programación de Python v1 requiere que defina enlaces en un archivo function.json independiente en la carpeta de funciones. Para más información, consulte la Guía para desarrolladores de Python.

En este artículo se admiten los modelos de programación.

Ejemplo

Se puede crear una función C# mediante uno de los siguientes modos de C#:

• Modelo de trabajo aislado: función compilada en C# que se ejecuta en un proceso trabajador aislado del tiempo de ejecución. Se requiere un proceso de trabajo aislado para admitir funciones de C# ejecutándose en versiones de .NET que son y no son LTS y .NET Framework. Las extensiones para las funciones de proceso de trabajo aisladas usan espacios de nombres Microsoft.Azure.Functions.Worker.Extensions.*.
• Modelo en curso: función C# compilada que se ejecuta en el mismo proceso que el tiempo de ejecución de Functions. En una variación de este modelo, Functions se puede ejecutar mediante el scripting de C#, que se admite principalmente para la edición del portal de C#. Las extensiones para funciones en proceso utilizan espacios de nombres Microsoft.Azure.WebJobs.Extensions.*.

Importante

El soporte técnico del modelo en proceso finalizará el 10 de noviembre de 2026. Se recomienda encarecidamente migrar las aplicaciones al modelo de trabajo aislado para obtener soporte técnico completo.

Modelo de trabajo aislado

El ejemplo siguiente es una función de C# que se ejecuta en un proceso de trabajo aislado y utiliza un desencadenador de blobs con enlaces de blobs de entrada y de blobs de salida. La función se activa mediante la creación de un blob en el contenedor test-samples-trigger. Lee un archivo de texto del contenedor test-samples-input y crea un nuevo archivo de texto en un contenedor de salida basado en el nombre del archivo desencadenado.

public static class BlobFunction
{
    [Function(nameof(BlobFunction))]
    [BlobOutput("test-samples-output/{name}-output.txt")]
    public static string Run(
        [BlobTrigger("test-samples-trigger/{name}")] string myTriggerItem,
        [BlobInput("test-samples-input/sample1.txt")] string myBlob,
        FunctionContext context)
    {
        var logger = context.GetLogger("BlobFunction");
        logger.LogInformation("Triggered Item = {myTriggerItem}", myTriggerItem);
        logger.LogInformation("Input Item = {myBlob}", myBlob);

        // Blob Output
        return "blob-output content";
    }
}

Modelo de proceso

En el ejemplo siguiente se muestra una función de C# que escribe un registro cuando se agrega o se actualiza un blob en el contenedor samples-workitems.

[FunctionName("BlobTriggerCSharp")]        
public static void Run([BlobTrigger("samples-workitems/{name}")] Stream myBlob, string name, ILogger log)
{
    log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name} \n Size: {myBlob.Length} Bytes");
}

La cadena {name} en la ruta de acceso del desencadenador de blobs samples-workitems/{name} crea una {name} que puede usar en el código de función para acceder al nombre de archivo del blob de desencadenamiento. Para más información, consulte Patrones de nombre de blob que aparece más adelante en este artículo.

Para obtener más información sobre el BlobTriggeratributo, consulte Atributos.

Esta función escribe un registro cuando se agrega o actualiza un blob en el contenedor myblob.

@FunctionName("blobprocessor")
public void run(
  @BlobTrigger(name = "file",
               dataType = "binary",
               path = "myblob/{name}",
               connection = "MyStorageAccountAppSetting") byte[] content,
  @BindingName("name") String filename,
  final ExecutionContext context
) {
  context.getLogger().info("Name: " + filename + " Size: " + content.length + " bytes");
}

Model v4

En el ejemplo siguiente se muestra un código de TypeScript de desencadenador de blob. La función escribe un registro cuando se agrega o actualiza un blob en el contenedor samples-workitems.

La cadena {name} en la ruta de acceso del desencadenador de blobs samples-workitems/{name} crea una {name} que puede usar en el código de función para acceder al nombre de archivo del blob de desencadenamiento. Para más información, consulte Patrones de nombre de blob que aparece más adelante en este artículo.

import { app, InvocationContext } from '@azure/functions';

export async function storageBlobTrigger1(blob: Buffer, context: InvocationContext): Promise<void> {
    context.log(
        `Storage blob function processed blob "${context.triggerMetadata.name}" with size ${blob.length} bytes`
    );
}

app.storageBlob('storageBlobTrigger1', {
    path: 'samples-workitems/{name}',
    connection: 'MyStorageAccountAppSetting',
    handler: storageBlobTrigger1,
});

Modelo v3

Los ejemplos de TypeScript no están documentados para el modelo v3.

Model v4

En el ejemplo siguiente se muestra un código de JavaScript de desencadenador de blob. La función escribe un registro cuando se agrega o actualiza un blob en el contenedor samples-workitems.

La cadena {name} en la ruta de acceso del desencadenador de blobs samples-workitems/{name} crea una {name} que puede usar en el código de función para acceder al nombre de archivo del blob de desencadenamiento. Para más información, consulte Patrones de nombre de blob que aparece más adelante en este artículo.

const { app } = require('@azure/functions');

app.storageBlob('storageBlobTrigger1', {
    path: 'samples-workitems/{name}',
    connection: 'MyStorageAccountAppSetting',
    handler: (blob, context) => {
        context.log(
            `Storage blob function processed blob "${context.triggerMetadata.name}" with size ${blob.length} bytes`
        );
    },
});

Modelo v3

En el ejemplo siguiente se muestra un enlace de desencadenador de blob en un archivo function.json y el código de JavaScript que usa el enlace. La función escribe un registro cuando se agrega o actualiza un blob en el contenedor samples-workitems.

Este es el archivo function.json:

{
    "disabled": false,
    "bindings": [
        {
            "name": "myBlob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

La cadena {name} en la ruta de acceso del desencadenador de blobs samples-workitems/{name} crea una {name} que puede usar en el código de función para acceder al nombre de archivo del blob de desencadenamiento. Para más información, consulte Patrones de nombre de blob que aparece más adelante en este artículo.

Para más información sobre las propiedades del archivo function.json, consulte la sección Configuración donde se explican estas propiedades.

Este es el código de JavaScript:

module.exports = async function(context) {
    context.log('Node.js Blob trigger function processed', context.bindings.myBlob);
};

En el ejemplo siguiente se muestra cómo crear una función que se ejecuta cuando se agrega un archivo al contenedor de almacenamiento de blobs source.

El archivo de configuración de la función (function.json) incluye un enlace con type de blobTrigger y direction está establecido en in.

{
  "bindings": [
    {
      "name": "InputBlob",
      "type": "blobTrigger",
      "direction": "in",
      "path": "source/{name}",
      "connection": "MyStorageAccountConnectionString"
    }
  ]
}

Este es el código asociado del archivo run.ps1.

param([byte[]] $InputBlob, $TriggerMetadata)

Write-Host "PowerShell Blob trigger: Name: $($TriggerMetadata.Name) Size: $($InputBlob.Length) bytes"

v2

En este ejemplo se usan tipos de SDK para acceder directamente al objeto subyacente BlobClient proporcionado por el desencadenador de Blob Storage:

import logging

import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
@app.blob_trigger(
    arg_name="client", path="PATH/TO/BLOB", connection="AzureWebJobsStorage"
)
def blob_trigger(client: blob.BlobClient):
    logging.info(
        f"Python blob trigger function processed blob \n"
        f"Properties: {client.get_blob_properties()}\n"
        f"Blob content head: {client.download_blob().read(size=1)}"
    )

Para obtener ejemplos de uso de otros tipos de SDK, consulte los ContainerClient ejemplos y StorageStreamDownloader .

Para más información, incluido cómo habilitar enlaces de tipos de SDK en el proyecto, consulte Enlaces de tipos de SDK.

En este ejemplo se registra información de los metadatos de blob entrantes.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="BlobTrigger1")
@app.blob_trigger(arg_name="myblob", 
                  path="PATH/TO/BLOB",
                  connection="CONNECTION_SETTING")
def test_function(myblob: func.InputStream):
   logging.info(f"Python blob trigger function processed blob \n"
                f"Name: {myblob.name}\n"
                f"Blob Size: {myblob.length} bytes")

v1

La función escribe un registro cuando se agrega o actualiza un blob en el contenedor samples-workitems. Este es el archivo function.json:

{
    "scriptFile": "__init__.py",
    "disabled": false,
    "bindings": [
        {
            "name": "myblob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

La cadena {name} en la ruta de acceso del desencadenador de blobs samples-workitems/{name} crea una {name} que puede usar en el código de función para acceder al nombre de archivo del blob de desencadenamiento. Para más información, consulte Patrones de nombre de blob que aparece más adelante en este artículo.

Para más información sobre las propiedades del archivo function.json, consulte la sección Configuración donde se explican estas propiedades.

Este es el código de Python:

import logging
import azure.functions as func


def main(myblob: func.InputStream):
    logging.info('Python Blob trigger function processed %s', myblob.name)

---

Atributos

Las bibliotecas de C# de procesos de trabajo aislados y en proceso usan el atributo BlobAttribute para definir la función. En su lugar, el script de C# usa un archivo de configuración function.json como se describe en la Guía de scripting de C#.

El constructor del atributo toma los parámetros siguientes:

Parámetro	Descripción
BlobPath	Ruta de acceso al blob.
Connection	Nombre de una configuración de aplicación o de una colección de configuraciones de aplicación que especifica cómo conectarse a los blobs de Azure. Consulte Conexiones.
Acceder	Indica si va a leer o escribir.
Origen	Establece el origen del evento de desencadenamiento. Use BlobTriggerSource.EventGrid para un desencadenador de blobs basado en Event Grid, que proporciona una latencia mucho menor. El valor predeterminado es BlobTriggerSource.LogsAndContainerScan, que usa el mecanismo de sondeo estándar para detectar cambios en el contenedor.

Modelo de trabajo aislado

A continuación, se muestra un atributo BlobTrigger en una signatura de método:

[Function(nameof(BlobFunction))]
[BlobOutput("test-samples-output/{name}-output.txt")]
public static string Run(
    [BlobTrigger("test-samples-trigger/{name}")] string myTriggerItem,
    [BlobInput("test-samples-input/sample1.txt")] string myBlob,
    FunctionContext context)

Modelo de proceso

En las bibliotecas de clase C#, el constructor del atributo toma una cadena de ruta de acceso que indica al contenedor que inspeccione y, opcionalmente, un patrón de nombre de blob. Este es un ejemplo:

[FunctionName("ResizeImage")]
public static void Run(
  [BlobTrigger("sample-images/{name}")] Stream image,
  [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall)
{
  ....
}

Aunque el atributo toma una propiedad Connection, también puede usar el atributo Connection para especificar una conexión de cuenta de almacenamiento. Puede hacerlo cuando necesite usar una cuenta de almacenamiento diferente a otras funciones de la biblioteca. El constructor toma el nombre de una configuración de aplicación que contiene una cadena de conexión de almacenamiento. El atributo se puede aplicar en el nivel de clase, método o parámetro. En el ejemplo siguiente se muestran el nivel de clase y de método:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

La cuenta de almacenamiento que se debe usar se determina en el orden siguiente:

• La propiedad Connection del atributo de enlace o desencadenador.
• El atributo StorageAccount aplicado al mismo parámetro que el atributo de enlace o desencadenador.
• El atributo StorageAccount aplicado a la función.
• El atributo StorageAccount aplicado a la clase.
• La cuenta de almacenamiento predeterminada de la aplicación de funciones, que se define en la configuración de la aplicación AzureWebJobsStorage.

Cuando esté desarrollando localmente, agregue la configuración de la aplicación en el archivo local.settings.json de la colección Values.

Elementos Decorator

Solo se aplica al modelo de programación de Python v2.

Para las funciones de Python v2 definidas mediante decoradores, las siguientes propiedades del decorador de blob_trigger definen el desencadenador de Blob Storage:

Propiedad	Descripción
arg_name	Declara el nombre del parámetro en la firma de la función. Cuando se desencadena la función, el valor de este parámetro tiene el contenido del mensaje de la cola.
path	El contenedor que se va a supervisar. Puede ser un patrón de nombre de blob.
connection	La cadena de conexión de cuenta de almacenamiento.
source	Establece el origen del evento de desencadenamiento. Use EventGrid para un desencadenador de blobs basado en Event Grid, que proporciona una latencia mucho menor. El valor predeterminado es LogsAndContainerScan, que usa el mecanismo de sondeo estándar para detectar cambios en el contenedor.

Para las funciones de Python definidas mediante function.json, consulte la sección Configuración.

anotaciones

El atributo @BlobTrigger se usa para facilitar el acceso al blob que desencadenó la función. Vea el ejemplo de desencadenador para más información. Use la propiedad sourcepara establecer el origen del evento desencadenador. Use EventGrid para un desencadenador de blobs basado en Event Grid, que proporciona una latencia mucho menor. El valor predeterminado es LogsAndContainerScan, que usa el mecanismo de sondeo estándar para detectar cambios en el contenedor. |

Configuración

Solo se aplica al modelo de programación de Python v1.

Model v4

En la tabla siguiente se explican las propiedades que puede establecer en el objeto options que se pasa al métodoapp.storageBlob().

Propiedad	Descripción
path	El contenedor que se va a supervisar. Puede ser un patrón de nombre de blob.
connection	Nombre de una configuración de aplicación o de una colección de configuraciones de aplicación que especifica cómo conectarse a los blobs de Azure. Consulte Conexiones.
source	Establece el origen del evento de desencadenamiento. Use EventGrid para un desencadenador de blobs basado en Event Grid, que proporciona una latencia mucho menor. El valor predeterminado es LogsAndContainerScan, que usa el mecanismo de sondeo estándar para detectar cambios en el contenedor.

Model v3

En la siguiente tabla se explican las propiedades de configuración de enlace que se establecen en el archivo function.json.

Propiedad	Descripción
type	Se debe establecer en blobTrigger. Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.
direction	Se debe establecer en in. Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal. Las excepciones se indican en la sección uso.
name	Nombre de la variable que representa el blob en el código de la función.
path	El contenedor que se va a supervisar. Puede ser un patrón de nombre de blob.
connection	Nombre de una configuración de aplicación o de una colección de configuraciones de aplicación que especifica cómo conectarse a los blobs de Azure. Consulte Conexiones.
source	Establece el origen del evento de desencadenamiento. Use EventGrid para un desencadenador de blobs basado en Event Grid, que proporciona una latencia mucho menor. El valor predeterminado es LogsAndContainerScan, que usa el mecanismo de sondeo estándar para detectar cambios en el contenedor.

En la siguiente tabla se explican las propiedades de configuración de enlace que se establecen en el archivo function.json.

Propiedad de function.json	Descripción
type	Se debe establecer en blobTrigger. Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.
direction	Se debe establecer en in. Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal. Las excepciones se indican en la sección uso.
name	Nombre de la variable que representa el blob en el código de la función.
path	El contenedor que se va a supervisar. Puede ser un patrón de nombre de blob.
connection	Nombre de una configuración de aplicación o de una colección de configuraciones de aplicación que especifica cómo conectarse a los blobs de Azure. Consulte Conexiones.
source	Establece el origen del evento de desencadenamiento. Use EventGrid para un desencadenador de blobs basado en Event Grid, que proporciona una latencia mucho menor. El valor predeterminado es LogsAndContainerScan, que usa el mecanismo de sondeo estándar para detectar cambios en el contenedor.

Consulte la sección de ejemplos para ver ejemplos completos.

Metadatos

El desencadenador de blobs proporciona varias propiedades de metadatos. Estas propiedades pueden usarse como parte de expresiones de enlace en otros enlaces o como parámetros del código. Estos valores tienen la misma semántica que el tipo CloudBlob.

Propiedad	Tipo	Descripción
BlobTrigger	string	Ruta de acceso del blob de desencadenamiento.
Uri	System.Uri	Es el identificador URI del blob correspondiente a la ubicación principal.
Properties	BlobProperties	Son las propiedades del sistema del blob.
Metadata	IDictionary<string,string>	Son los metadatos definidos por el usuario para el blob.

En el siguiente ejemplo se registra la ruta de acceso al blob desencadenante, incluyendo el contenedor:

public static void Run(string myBlob, string blobTrigger, ILogger log)
{
    log.LogInformation($"Full blob path: {blobTrigger}");
} 

Metadatos

El desencadenador de blobs proporciona varias propiedades de metadatos. Estas propiedades pueden usarse como parte de expresiones de enlace en otros enlaces o como parámetros del código.

Propiedad	Descripción
blobTrigger	Ruta de acceso del blob de desencadenamiento.
uri	Es el identificador URI del blob correspondiente a la ubicación principal.
properties	Son las propiedades del sistema del blob.
metadata	Son los metadatos definidos por el usuario para el blob.

Model v4

Los metadatos se pueden obtener de la triggerMetadatapropiedad del objeto proporcionadocontext, como se muestra en el ejemplo siguiente, que registra la ruta al blob desencadenante (blobTrigger), incluyendo el contenedor:

context.log(`Full blob path: ${context.triggerMetadata.blobTrigger}`);

Model v3

Los metadatos se pueden obtener de la bindingDatapropiedad del objeto proporcionadocontext, como se muestra en el ejemplo siguiente, que registra la ruta al blob desencadenante (blobTrigger), incluyendo el contenedor:

module.exports = async function (context, myBlob) {
    context.log("Full blob path:", context.bindingData.blobTrigger);
};

Metadatos

Los metadatos están disponibles mediante el parámetro $TriggerMetadata.

Uso

Los tipos de enlace admitidos por el desencadenador de blobs dependen de la versión del paquete de extensión y de la modalidad de C# usada en la aplicación de funciones.

Modelo de trabajo aislado

El desencadenador de blobs puede enlazarse a los siguientes tipos:

Tipo	Descripción
string	El contenido del blob como una cadena. Se usa cuando el contenido del blob es de texto simple.
byte[]	Los bytes del contenido del blob.
Tipos serializables con JSON	Cuando un blob contenga datos JSON, Functions intentará deserializar los datos JSON en un tipo de objeto CLR sin formato (POCO).
Stream1	Un flujo de entrada del contenido del blob.
BlobClient1, BlockBlobClient1, PageBlobClient1, AppendBlobClient1, BlobBaseClient1	Un cliente conectado al blob. Este conjunto de tipos ofrece el mayor control para procesar el blob y puede utilizarse para reescribir en el blob si la conexión tiene permisos suficientes.

¹ Para utilizar estos tipos, debe hacer referencia a Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 o posterior y a las dependencias comunes para los enlaces de tipo SDK.

Modelo de proceso

En Tipos de enlace encontrará una lista de los tipos admitidos.

El enlace a string o a Byte[] solo está recomendado cuando el tamaño del blob es pequeño. Esto se recomienda porque todo el contenido del blob se carga en la memoria. Para la mayoría de los blobs, use un tipo Stream o BlobClient. Para obtener más información, consulte Simultaneidad y uso de memoria.

Si recibe un mensaje de error al intentar enlazar a uno de los tipos de Storage SDK, asegúrese de que hace referencia a la versión de Storage SDK correcta.

También puede usar StorageAccountAttribute para especificar la cuenta de almacenamiento que se va a usar. Puede hacerlo cuando necesite usar una cuenta de almacenamiento diferente a otras funciones de la biblioteca. El constructor toma el nombre de una configuración de aplicación que contiene una cadena de conexión de almacenamiento. El atributo se puede aplicar en el nivel de clase, método o parámetro. En el ejemplo siguiente se muestran el nivel de clase y de método:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("BlobTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ....
}

La cuenta de almacenamiento que se debe usar se determina en el orden siguiente:

• La propiedad Connection del atributo BlobTrigger.
• El atributo StorageAccount aplicado al mismo parámetro que el atributo BlobTrigger.
• El atributo StorageAccount aplicado a la función.
• El atributo StorageAccount aplicado a la clase.
• La cuenta de almacenamiento predeterminada de la aplicación de funciones, que se define en la configuración de la aplicación AzureWebJobsStorage.

El atributo @BlobTrigger se usa para facilitar el acceso al blob que desencadenó la función. Vea el ejemplo de desencadenador para más información.

Model v4

Acceda a los datos de blob como primer argumento de la función.

Modelo v3

Acceda a los datos de BLOB mediante context.bindings.<NAME> donde <NAME> coincide con el valor definido en context.bindings.<NAME>.

Acceda a los datos de blob a través de un parámetro que coincida con el nombre designado por el parámetro del nombre del enlace en el archivo function.json.

Acceda a los datos de blob a través del parámetro con el tipo InputStream. Vea el ejemplo de desencadenador para más información.

Functions también admite enlaces de tipos de SDK de Python para Azure Blob Storage, lo que le permite trabajar con datos de blobs mediante estos tipos de SDK subyacentes:

• BlobClient
• ContainerClient
• StorageStreamDownloader

Importante

La compatibilidad con tipos de SDK para Python está actualmente en versión preliminar y solo se admite para el modelo de programación de Python v2. Para más información, consulte Tipos de SDK en Python.

Conexiones

La propiedad connection es una referencia a la configuración del entorno que especifica cómo se debe conectar la aplicación a los blobs de Azure. Puede especificar lo siguiente:

• El nombre de una configuración de la aplicación que contiene una cadena de conexión.
• El nombre de un prefijo compartido para varias configuraciones de la aplicación que juntas definen una conexión basada en identidad.

Si el valor configurado es tanto una coincidencia exacta de una única configuración como una coincidencia de prefijo de otras configuraciones, se usa la coincidencia exacta.

Cadena de conexión

Para obtener una cadena de conexión, siga los pasos mostrados en Administración de las claves de acceso de la cuenta de almacenamiento. La cadena de conexión debe ser para una cuenta de almacenamiento de uso general, no una cuenta de Blob Storage.

La cadena de conexión debe almacenarse en una configuración de la aplicación con un nombre que coincida con el valor especificado por la propiedad connection de la configuración de enlace.

Si el nombre de la configuración de aplicación comienza con "AzureWebJobs", puede especificar solo el resto del nombre aquí. Por ejemplo, si establece connection en "MyStorage", el entorno en tiempo de ejecución de Functions busca una configuración de aplicación denominada "AzureWebJobsMyStorage". Si deja connection vacía, el entorno en tiempo de ejecución de Functions usa la cadena de conexión de almacenamiento predeterminada en la configuración de aplicación que se denomina AzureWebJobsStorage.

Conexiones basadas en identidades

Si usa la versión 5.x o posterior de la extensión (agrupación 3.x o superior para non-.NET pilas de lenguaje), en lugar de usar un cadena de conexión con un secreto, puede hacer que la aplicación use una identidad de Microsoft Entra. Para usar una identidad, se define la configuración con un prefijo común que se asigna a la propiedad de connection en la configuración de desencadenador y enlace.

Si va a establecer connection en "AzureWebJobsStorage", consulte Conexión al almacenamiento de host con una identidad. Para todas las demás conexiones, la extensión requiere las siguientes propiedades:

Propiedad	Plantilla de variable de entorno	Descripción	Valor de ejemplo
URI de Blob service	<CONNECTION_NAME_PREFIX>__serviceUri1	El URI del plano de datos del servicio de blob al que te estás conectando mediante el esquema HTTPS.	https://<storage_account_name>.blob.core.windows.net

¹ <CONNECTION_NAME_PREFIX>__blobServiceUri se puede usar como alias. Si un desencadenador de blob va a usar la configuración de conexión, blobServiceUri también debe ir acompañado de queueServiceUri. Véase a continuación.

El formulario serviceUri no se puede usar cuando la configuración de conexión general se va a usar en blobs, colas o tablas. El URI solo puede designar el servicio de blob. Como alternativa, puede proporcionar un URI específicamente para cada servicio, lo cual permite usar una sola conexión. Si se proporcionan ambas versiones, se utiliza el formulario multiservicio. Para configurar la conexión para varios servicios, en lugar de <CONNECTION_NAME_PREFIX>__serviceUri, establezca:

Propiedad	Plantilla de variable de entorno	Descripción	Valor de ejemplo
URI de Blob service	<CONNECTION_NAME_PREFIX>__blobServiceUri	El URI del plano de datos del servicio de blob al que te estás conectando mediante el esquema HTTPS.	https://<storage_account_name>.blob.core.windows.net
URI de Queue Service (necesario para desencadenadores de blobs2)	<CONNECTION_NAME_PREFIX>__queueServiceUri	URI del plano de datos de un servicio de cola, mediante el esquema HTTPS. Este valor solo es necesario para los desencadenadores de blobs.	https://<storage_account_name>.queue.core.windows.net

² El desencadenador de blobs controla los errores en varios reintentos escribiendo blobs dudosos en una cola. En el formulario serviceUri, se usa la conexión AzureWebJobsStorage. Sin embargo, al especificar blobServiceUri, también se debe proporcionar un URI de Queue service con queueServiceUri. Se recomienda usar el servicio desde la misma cuenta de almacenamiento que el servicio de blob. También debes asegurarte de que el desencadenador pueda leer y escribir mensajes en el servicio de cola configurado mediante la asignación de un rol como Colaborador de datos de cola de almacenamiento.

Se pueden establecer otras propiedades para personalizar la conexión. Consulte Propiedades comunes para 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.

Importante

Es posible que el servicio de destino muestre algunos permisos que no son necesarios para todos los contextos. Siempre que sea posible, respete el principio de privilegios mínimos y conceda solo los privilegios necesarios a la identidad. Por ejemplo, si la aplicación solo necesita poder leer desde un origen de datos, use un rol que solo tenga permiso de lectura. Sería inadecuado asignar un rol que también permita escribir en ese servicio, ya que sería un permiso excesivo para una operación de lectura. De forma similar, le interesa asegurarse de que la asignación de roles esté limitada solo a los recursos que se deben leer.

Debe crear una asignación de roles que proporcione acceso al contenedor de blobs en tiempo de ejecución. Los roles de administración, como Propietario, no son suficientes. En la tabla siguiente se muestran los roles integrados que se recomiendan al usar la extensión Blob Storage en funcionamiento normal. Tu aplicación puede requerir más permisos según el código que escribas.

Tipo de enlace	Roles integrados de ejemplo
Desencadenador	Propietario de datos de blobs de almacenamiento y Colaborador de datos de cola de almacenamiento1 También se deben conceder permisos adicionales a la conexión AzureWebJobsStorage.2
Enlace de entrada	Lector de datos de blobs de almacenamiento
Enlace de salida	Propietario de datos de blobs de almacenamiento

¹ El desencadenador de blobs controla los errores en varios reintentos escribiendo blobs dudosos en una cola en la cuenta de almacenamiento especificada por la conexión.

² La conexión AzureWebJobsStorage se usa internamente para blobs y colas que habilitan el desencadenador. Si está configurado para usar una conexión basada en identidades, necesita permisos adicionales más allá del requisito predeterminado. Los permisos necesarios están cubiertos por los roles Propietario de datos de blobs de almacenamiento, Colaborador de datos de la cola de Storage y Colaborador de la cuenta de almacenamiento. Para obtener más información, consulte Conexión al almacenamiento de host con una identidad.

Patrones de nombre de blobs

Puede especificar un patrón de nombre de blob en la propiedad path en path o en el constructor de atributos BlobTrigger. El patrón de nombre puede ser una expresión de filtro o enlace. En las siguientes secciones se proporcionan ejemplos.

Sugerencia

Un nombre de contenedor no puede contener una resolución en el patrón de nombre.

Obtener el nombre y la extensión de archivo

En el ejemplo siguiente se muestra cómo enlazar a nombre de archivo del blob y la extensión por separado:

"path": "input/{blobname}.{blobextension}",

Si el blob se denomina original-Blob1.txt, los valores de las variables blobname y blobextension del código de la función son original-Blob1 y txt.

Filtrar por nombre de blob

El ejemplo siguiente se desencadena solo en blobs del contenedor input que comienzan con la cadena "original-":

"path": "input/original-{name}",

Si el nombre de blob es original Blob1.txt, el valor de la variable name en el código de la función es Blob1.txt.

Filtrar por tipo de archivo

El siguiente ejemplo se desencadena solo en archivos .png:

"path": "samples/{name}.png",

Filtrar por llaves en nombres de archivo

Para buscar llaves en nombres de archivo, escape las llaves mediante dos llaves. En el ejemplo siguiente se filtran blobs que tienen llaves en el nombre:

"path": "images/{{20140101}}-{name}",

Si el blob se denomina {20140101}-soundfile.mp3, el valor de variable name en el código de la función es soundfile.mp3.

Sondeo y latencia

El sondeo funciona como un híbrido entre la inspección de registros y la ejecución de exámenes periódicos de contenedores. Los blobs se examinan en grupos de 10 000 a la vez con un token de continuación que se usa entre intervalos. Si la aplicación de función está en un plan de consumo, puede haber un retraso de hasta 10 minutos en el procesamiento de nuevos blobs si una aplicación de función ha quedado inactiva.

Advertencia

Los registros de almacenamiento se crean basados en el principio del "mejor esfuerzo". No hay ninguna garantía de que se capturen todos los eventos. En algunos casos, podrían faltar registros.

Si necesita un procesamiento de blobs más rápido o más confiable, considere la posibilidad de cambiar el hospedaje para usar un plan de App Service con AlwaysOn habilitado, lo que puede dar lugar a un aumento de los costos. También puede considerar la posibilidad de usar un desencadenador que no sea el desencadenador de blob de sondeo clásico. Para más información y una comparación de las distintas opciones de desencadenamiento para contenedores de Blob Storage, consulte Desencadenador en un contenedor de blobs.

Recepciones de blobs

El entorno en tiempo de ejecución de Azure Functions garantiza que no se llame más de una vez a ninguna función de desencadenador de blobs para un mismo blob, ya sea nuevo o actualizado. Mantiene recepciones de blobs para determinar si se ha procesado una determinada versión de blob.

Azure Functions almacena confirmaciones de blobs en un contenedor llamado azure-webjobs-hosts en la cuenta de almacenamiento de Azure de la aplicación de función (que se especifica mediante la configuración de la aplicación AzureWebJobsStorage). Una recepción de blobs tiene la información siguiente:

• La función desencadenada (<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>, por ejemplo,MyFunctionApp.Functions.CopyBlob)
• El nombre del contenedor
• El tipo de blob (BlockBlob o PageBlob)
• El nombre del blob
• La etiqueta de entidad (un identificador de la versión del blob, por ejemplo, 0x8D1DC6E70A277EF)

Si desea forzar el reprocesamiento de un blob, puede eliminar manualmente la recepción de ese blob desde el contenedor azure-webjobs-hosts . Al volver a procesar podría no producirse inmediatamente, pero se garantiza que se producirá más adelante en un momento dado. Para volver a procesarlo de inmediato, se puede actualizar el blob scaninfo en azure-webjobs-hosts/blobscaninfo. Cualquier blob con una marca de tiempo de última modificación después de la propiedad LatestScan se volverá a examinar.

Blobs dudosos

Si se produce un error en una función de desencadenador de blob, Azure Functions vuelve a intentar ejecutar esa función hasta cinco veces de forma predeterminada.

Si se produce un error en los 5 intentos, Azure Functions agregará un mensaje a una cola de Storage llamada webjobs-blobtrigger-poison. Es posible configurar el número máximo de reintentos. Se usa la misma configuración de MaxDequeueCount para controlar los blobs dudosos y los mensajes de cola dudosos. El mensaje de cola para los blobs dudosos es un objeto JSON que contiene las siguientes propiedades:

• FunctionId (con formato <FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>)
• BlobType (BlockBlob o PageBlob)
• ContainerName
• BlobName
• ETag (un identificador de la versión del blob, por ejemplo, 0x8D1DC6E70A277EF)

Uso y simultaneidad de memoria

Cuando se enlaza a un tipo de salida que no admite streaming, como string, o Byte[], el tiempo de ejecución debe cargar todo el blob en la memoria más de una vez durante el procesamiento. Esto puede dar lugar a un uso de memoria superior al esperado al procesar blobs. Cuando sea posible, use un tipo compatible con secuencias. La compatibilidad con tipos depende del modo de C# y de la versión de la extensión. Para obtener más información, consulte Tipos de enlace.

En este momento, el tiempo de ejecución debe cargar todo el blob en la memoria más de una vez durante el procesamiento. Esto puede dar lugar a un uso de memoria superior al esperado al procesar blobs.

El uso de memoria puede verse afectado aún más cuando varias instancias de función procesan simultáneamente datos de blobs. Si tiene problemas de memoria mediante un desencadenador de blobs, considere la posibilidad de reducir el número de ejecuciones simultáneas permitidas. Por supuesto, reducir la simultaneidad puede tener el efecto secundario de aumentar el trabajo pendiente de blobs que esperan ser procesados. Los límites de memoria de la aplicación de funciones dependen del plan. Para más información, consulte los límites del servicio.

La forma en que puede controlar el número de ejecuciones simultáneas depende de la versión de la extensión storage que use.

Extensión 5.x y posteriores

Al usar la versión 5.0.0 de la extensión storage o una versión posterior, puede controlar la simultaneidad desencadenando la simultaneidad mediante la maxDegreeOfParallelism configuración de blobs en host.json.

Extensión previa 5.x

Dado que el desencadenador de blobs usa internamente una cola, el número máximo de invocaciones de función simultáneas se controla mediante la configuración de colas en host.json.

Los límites se aplican por separado a cada función que usa un desencadenador de blobs.

Propiedades de host.json

El archivo host.json contiene opciones de configuración que controlan el comportamiento de desencadenador del blob. Consulte la sección de configuración de host.json para más información sobre las opciones de configuración disponibles.

Pasos siguientes

• Lectura de datos de almacenamiento de blobs cuando se ejecuta una función
• Escritura de datos de Blob Storage desde una función