Compartir vía

Introducción a los enlaces de Azure Blob Storage para Azure Functions

  • Artículo

Azure Functions se integra con Azure Storage mediante desencadenadores y enlaces. La integración con Blob Storage permite crear funciones que reaccionan a los cambios en los datos del blob, así como a los valores de lectura y escritura.

Acción Tipo
Ejecución de una función cuando cambian los datos de Blob Storage Desencadenador
Lectura de datos de Blob Storage en una función Enlace de entrada
Escritura de datos de almacenamiento de blobs desde una función Enlace de salida

Instalación de la extensión

El paquete NuGet de la extensión que instale depende del modo de C# que esté usando en la aplicación de funciones:

Las funciones se ejecutan en un proceso de trabajo de C# aislado. Para más información, consulte Guía para ejecutar C# Azure Functions en un proceso de trabajo aislado.

La funcionalidad de la extensión varía en función de la versión de la extensión:

Esta versión presenta la posibilidad de conectarse con una identidad en lugar de un secreto. Para obtener un tutorial sobre cómo configurar las aplicaciones de funciones con identidades administradas, consulte el tutorial Creación de una aplicación de funciones con conexiones basadas en identidades.

Esta versión permite enlazar con tipos de Azure.Storage.Blobs. Obtenga más información sobre las diferencias entre estos nuevos tipos y WindowsAzure.Storage y Microsoft.Azure.Storage, y cómo migrarlos desde la Guía de migración de Azure.Storage.Blobs.

Esta versión admite la configuración de desencadenadores y enlaces a través de la integración de .NET Aspire.

Agregue la extensión al proyecto mediante la instalación del paquete NuGet Microsoft.Azure.Functions.Worker.Extensions.Storage. Blobs, versión 5.x o posterior.

Mediante la CLI de .NET:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs

Nota

Azure Blobs, Azure Queues y Azure Tables ahora usan extensiones diferentes y se les hace referencia por separado. Por ejemplo, para usar los desencadenadores y enlaces de los tres servicios en la aplicación en un proceso aislado de .NET, debe agregar los siguientes paquetes al proyecto:

Antes, las extensiones se distribuían juntas como Microsoft.Azure.Functions.Worker.Extensions.Storage, versión 4.x. Este mismo paquete también tiene una versión 5.x que hace referencia solo a los paquetes divididos para blobs y colas. Al actualizar las versiones anteriores de las referencias del paquete, es posible que tenga que hacer referencia también al nuevo paquete NuGet Microsoft.Azure.Functions.Worker.Extensions.Tables. Además, al hacer referencia a estos paquetes divididos más recientes, asegúrese de que no hace referencia a una versión anterior del paquete de almacenamiento combinado, ya que esto provocaría conflictos por las dos definiciones de los mismos enlaces.

Si va a escribir la aplicación con F#, también debe configurar esta extensión como parte de la configuración de inicio de la aplicación. En la llamada a ConfigureFunctionsWorkerDefaults() o ConfigureFunctionsWebApplication(), agregue un delegado que tome un parámetro IFunctionsWorkerApplication. Después, dentro del cuerpo de ese delegado, llame a ConfigureBlobStorageExtension() en el objeto:

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureBlobStorageExtension() |> ignore
) |> ignore

Instalación del conjunto

El enlace de almacenamiento de Blob forma parte de un conjunto de extensiones, que se especifica en el archivo de proyecto host.json. Es posible que tenga que modificar este conjunto para cambiar la versión de los enlaces o en caso de que los conjuntos aún no estén instalados. Para obtener más información, consulte Conjuntos de extensiones.

Esta versión presenta la posibilidad de conectarse con una identidad en lugar de un secreto. Para obtener un tutorial sobre cómo configurar las aplicaciones de funciones con identidades administradas, consulte el tutorial Creación de una aplicación de funciones con conexiones basadas en identidades.

Para agregar esta versión de la extensión desde el conjunto de extensiones v3, puede agregar o reemplazar el código siguiente en el archivo host.json:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Para obtener más información, consulte Actualización de las extensiones.

Tipos de enlaces

Los tipos de enlace admitidos para .NET dependen de la versión de extensión y del modo de ejecución de C#, que puede ser uno de los siguientes:

Una función de C# compilada de la biblioteca de clases de procesos de trabajo aislados se ejecuta en un proceso aislado del entorno de ejecución.

Seleccione una versión para ver los detalles del tipo de enlace para el modo y la versión.

El proceso de trabajo aislado admite tipos de parámetros según las tablas siguientes.

Desencadenador de blobs

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.

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.

Enlace de entrada de blob

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.

Enlace de salida de blob

Cuando quiera que la función escriba en un único blob, el enlace de salida 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 Un objeto que representa el contenido de un blob JSON. Functions intenta serializar un tipo de objetivo CLR sin formato (POCO) en datos JSON.

Cuando quiera que la función escriba en varios blobs, el enlace de salida del blob podrá enlazarse a los siguientes tipos:

Tipo Descripción
T[], donde T es uno de los tipos de enlace de salida de blob único Una matriz que contiene contenido para varios blobs. Cada entrada representa el contenido de un blob.

Para otros escenarios de salida, cree y use blobClient o BlobContainerClient con otros tipos de Azure.Storage.Blobs directamente. Consulte Registro de clientes de Azure para obtener un ejemplo de uso de la inserción de dependencias para crear un tipo de cliente a partir del SDK de Azure.

configuración de host.json

En esta sección se describen los valores de configuración de la aplicación de funciones disponibles para las funciones que usan este enlace. Esta configuración solo se aplica cuando se usa la versión 5.0.0 de la extensión y versiones posteriores. El siguiente archivo host.json de ejemplo contiene solo la configuración de la versión 2.x+ para este enlace. Para obtener más información sobre la configuración de la aplicación de funciones en las versiones 2.x y posteriores, consulte la referencia de host.json para Azure Functions.

Nota

Esta sección no se aplica a las versiones de extensión anteriores a 5.0.0. Para esas versiones anteriores, no hay ninguna función de configuración para toda la aplicación de blobs.

{
    "version": "2.0",
    "extensions": {
        "blobs": {
            "maxDegreeOfParallelism": 4,
            "poisonBlobThreshold": 1
        }
    }
}
Propiedad Valor predeterminado Descripción
maxDegreeOfParallelism 8* (el número de núcleos disponibles) Número entero de invocaciones simultáneas permitidas para todas las funciones desencadenadas por blobs en una aplicación de funciones determinada. El valor mínimo permitido es 1.
poisonBlobThreshold 5 Número entero de veces que se intenta procesar un mensaje antes de pasarlo a la cola de mensajes dudosos. El valor mínimo permitido es 1.

Pasos siguientes