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.

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.

Ejemplo

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";
    }
}

[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");
}

@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");
}

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,
});

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`
        );
    },
});

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

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

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

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

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

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)}"
    )

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

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

import logging
import azure.functions as func


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

[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)

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

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

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

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

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

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

Uso

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

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:

¹ <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:

² 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.

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.

¹ 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.

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.

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

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.

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