Compartir vía

Enlace de entrada de Azure Blob Storage para Azure Functions

  • Artículo

El enlace de entrada permite leer datos de Blob Storage como entrada para una instancia de Azure Functions.

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.

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.

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.

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

En esta sección se incluyen los ejemplos siguientes:

Desencadenador de HTTP, búsqueda de nombre de blob en la cadena de consulta

El ejemplo siguiente muestra una función de Java que usa la anotación HttpTrigger para recibir un parámetro que contiene el nombre de un archivo en un contenedor de Blob Storage. Posteriormente, la anotación BlobInput lee el archivo y pasa el contenido a la función como byte[].

  @FunctionName("getBlobSizeHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage blobSize(
    @HttpTrigger(name = "req", 
      methods = {HttpMethod.GET}, 
      authLevel = AuthorizationLevel.ANONYMOUS) 
    HttpRequestMessage<Optional<String>> request,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{Query.file}") 
    byte[] content,
    final ExecutionContext context) {
      // build HTTP response with size of requested blob
      return request.createResponseBuilder(HttpStatus.OK)
        .body("The size of \"" + request.getQueryParameters().get("file") + "\" is: " + content.length + " bytes")
        .build();
  }

Desencadenador de cola, recepción del nombre del blob de la cola de mensajes

El ejemplo siguiente muestra una función de Java que usa la anotación QueueTrigger para recibir un mensaje que contiene el nombre de un archivo en un contenedor de Blob Storage. Posteriormente, la anotación BlobInput lee el archivo y pasa el contenido a la función como byte[].

  @FunctionName("getBlobSize")
  @StorageAccount("Storage_Account_Connection_String")
  public void blobSize(
    @QueueTrigger(
      name = "filename", 
      queueName = "myqueue-items-sample") 
    String filename,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{queueTrigger}") 
    byte[] content,
    final ExecutionContext context) {
      context.getLogger().info("The size of \"" + filename + "\" is: " + content.length + " bytes");
  }

En la biblioteca en tiempo de ejecución de funciones de Java, utilice la anotación @BlobInput en los parámetros cuyo valor provendría de un blob. Esta anotación se puede usar con tipos nativos de Java, POJO o valores que aceptan valores NULL mediante Optional<T>.

En el ejemplo siguiente se muestra una función TypeScript desencadenada por cola que realiza una copia de un blob. La función se activa mediante un mensaje de cola que contiene el nombre del blob que se va a copiar. El nuevo blob se denomina {nombreoriginaldelblob}-Copy.

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

const blobInput = input.storageBlob({
    path: 'samples-workitems/{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

const blobOutput = output.storageBlob({
    path: 'samples-workitems/{queueTrigger}-Copy',
    connection: 'MyStorageConnectionAppSetting',
});

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<unknown> {
    return context.extraInputs.get(blobInput);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [blobInput],
    return: blobOutput,
    handler: storageQueueTrigger1,
});

En el ejemplo siguiente se muestra una función JavaScript desencadenada por cola que realiza una copia de un blob. La función se activa mediante un mensaje de cola que contiene el nombre del blob que se va a copiar. El nuevo blob se denomina {nombreoriginaldelblob}-Copy.

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

const blobInput = input.storageBlob({
    path: 'samples-workitems/{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

const blobOutput = output.storageBlob({
    path: 'samples-workitems/{queueTrigger}-Copy',
    connection: 'MyStorageConnectionAppSetting',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [blobInput],
    return: blobOutput,
    handler: (queueItem, context) => {
        return context.extraInputs.get(blobInput);
    },
});

En el ejemplo siguiente se muestra un enlace de entrada de blob, definido en el archivo function.json, que hace que los datos de blobs entrantes estén disponibles para la función de PowerShell.

Esta es la configuración json:

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

Este es el código de la función:

# Input bindings are passed in via param block.
param([byte[]] $InputBlob, $TriggerMetadata)

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

En este ejemplo se usan tipos de SDK para acceder directamente al objeto subyacente BlobClient proporcionado por el enlace de entrada 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.route(route="file")
@app.blob_input(
    arg_name="client", path="PATH/TO/BLOB", connection="AzureWebJobsStorage"
)
def blob_input(req: func.HttpRequest, client: blob.BlobClient):
    logging.info(
        f"Python blob input function processed blob \n"
        f"Properties: {client.get_blob_properties()}\n"
        f"Blob content head: {client.download_blob().read(size=1)}"
    )
    return "ok"

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.

El código crea una copia de un blob.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="BlobOutput1")
@app.route(route="file")
@app.blob_input(arg_name="inputblob",
                path="sample-workitems/test.txt",
                connection="<BLOB_CONNECTION_SETTING>")
@app.blob_output(arg_name="outputblob",
                path="newblob/test.txt",
                connection="<BLOB_CONNECTION_SETTING>")
def main(req: func.HttpRequest, inputblob: str, outputblob: func.Out[str]):
    logging.info(f'Python Queue trigger function processed {len(inputblob)} bytes')
    outputblob.set(inputblob)
    return "ok"

Atributos

Las bibliotecas de C# en proceso y de proceso de trabajo aislado usan atributos 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 proceso de trabajo aislado define un enlace de entrada mediante un BlobInputAttribute atributo , que 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.

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 en los decoradores blob_input y blob_output definen los activadores de Blob Storage:

Propiedad Descripción
arg_name Nombre de la variable que representa el blob en el código de la función.
path La ruta al blob para el decorador blob_input, es la lectura del blob. Para el decorador blob_output, es la salida o copia del blob de entrada.
connection La cadena de conexión de cuenta de almacenamiento.
data_type En el caso de los lenguajes con tipos dinámicos, especifica el tipo de datos subyacente. Los valores posibles son string, binary o stream. Para obtener más información, consulte los conceptos de desencadenadores y enlaces.

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

anotaciones

El atributo @BlobInput da acceso al blob que desencadenó la función. Si utiliza una matriz de bytes con el atributo, establezca dataType en binary. Vea el ejemplo de entrada para más información.

Configuración

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

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

Propiedad Descripción
path 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.

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 blob.
direction Se debe establecer en in. 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 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.
dataType En el caso de los lenguajes con tipos dinámicos, especifica el tipo de datos subyacente. Los valores posibles son string, binary o stream. Para obtener más información, consulte los conceptos de desencadenadores y enlaces.

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

Uso

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

Cuando quiera que la función procese un único blob, el enlace de entrada del blob podrá 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 él si la conexión tiene permisos suficientes.

Cuando quiera que la función procese varios blobs desde un contenedor, el enlace de entrada de blobs podrá enlazarse a los siguientes tipos:

Tipo Descripción
T[] o List<T>, donde T es uno de los tipos de enlace de entrada de blob único Una matriz o lista de varios blobs. Cada entrada representa un blob del contenedor. También es posible enlazar a cualquier interfaz implementada por estos tipos, como IEnumerable<T>.
BlobContainerClient1 Un cliente conectado al contenedor. Este tipo ofrece el mayor control para procesar el contenedor y puede utilizarse para escribir en él si la conexión tiene permisos suficientes.

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

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 @BlobInput da acceso al blob que desencadenó la función. Si utiliza una matriz de bytes con el atributo, establezca dataType en binary. Vea el ejemplo de entrada para más información.

Acceda a los datos de blob mediante context.extraInputs.get().

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

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:

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

1 <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

2 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

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

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

Pasos siguientes