Visão geral das associações de armazenamento de blob do Azure para o Azure Functions

  • Artigo

O Azure Functions integra-se com o Armazenamento do Microsoft Azure por meio de gatilhos e associações. A integração com o armazenamento de blob permite que você crie funções que reajam a alterações nos dados de blob, bem como valores de leitura e gravação.

Ação Type
Executar uma função como alterações de dados do armazenamento de Blobs Gatilho
Ler os dados de armazenamento de blob em uma função Associação de entrada
Permitir que uma função grave os dados de armazenamento de blob Associação de saída

Instalar a extensão

O pacote NuGet da extensão instalado depende do modo C# usado no aplicativo de funções:

As funções são executadas em um processo de trabalho do C# isolado. Para saber mais, confira o Guia para executar C# do Azure Functions em um processo de trabalho isolado.

A funcionalidade da extensão varia de acordo com a versão da extensão:

Essa versão apresenta a capacidade de se conectar usando uma identidade em vez de um segredo. Para ver um tutorial sobre a configuração de aplicativos de funções com identidades gerenciadas, confira o tutorial sobre como criar um aplicativo de funções com conexões baseadas em identidade.

Ela permite que você se associe a tipos do Azure.Storage.Queues. Conheça as diferenças entre os novos tipos e o WindowsAzure.Storage e Microsoft.Azure.Storage e saiba como migrar para eles no Guia de migração do Azure.Storage.Blobs.

Adicione a extensão ao seu projeto instalando o pacote NuGet Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs, versão 5.x ou posterior.

Usando a CLI do .NET:

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

Observação

Agora, os Blobs do Azure, as Filas do Azure e as Tabelas do Azure usam extensões separadas e são referenciados individualmente. Por exemplo, para usar os gatilhos e as associações para os três serviços no aplicativo de processo isolado .NET, você deve adicionar os seguintes pacotes ao projeto:

Anteriormente, as extensões eram enviadas juntas como Microsoft.Azure.Functions.Worker.Extensions.Storage, versão 4.x. Esse mesmo pacote também tem uma versão 5.x, que faz referência apenas aos pacotes divididos para blobs e filas. Ao atualizar as referências de pacote de versões mais antigas, talvez seja necessário também fazer referência ao novo pacote NuGet Microsoft.Azure.Functions.Worker.Extensions.Tables. Além disso, ao referenciar esses pacotes divididos mais recentes, verifique se você não está fazendo referência a uma versão mais antiga do pacote de armazenamento combinado, pois isso resultará em conflitos de duas definições das mesmas associações.

Se você estiver escrevendo seu aplicativo usando F#, também deverá configurar essa extensão como parte da configuração de inicialização do aplicativo. Na chamada para ConfigureFunctionsWorkerDefaults() ou ConfigureFunctionsWebApplication(), adicione um representante que usa um parâmetro IFunctionsWorkerApplication. Em seguida, dentro do corpo desse representante, chame ConfigureBlobStorageExtension() no objeto:

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

Instalar pacote

A associação do armazenamento de blobs faz parte de um pacote de extensão que é especificado no arquivo de projeto host.json. Talvez seja necessário modificar esse pacote se for preciso alterar a versão das associações ou se os pacotes ainda não estiverem instalados. Para saber mais, confira pacotes de extensão.

Essa versão apresenta a capacidade de se conectar usando uma identidade em vez de um segredo. Para ver um tutorial sobre a configuração de aplicativos de funções com identidades gerenciadas, confira o tutorial sobre como criar um aplicativo de funções com conexões baseadas em identidade.

Você pode adicionar esta versão da extensão do pacote de extensão v3 adicionando ou substituindo o seguinte código em seu arquivo host.json:

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

Para saber mais, confira Atualizar suas extensões.

Tipos de associação

Os tipos de associação com suporte para .NET dependem da versão da extensão e do modo de execução do C#, que pode ser um dos seguintes:

Uma função C# compilada da biblioteca de classes do processo de trabalho isolado é executada em um processo isolado do runtime.

Escolha uma versão para ver os detalhes do tipo de associação para o modo e a versão.

O processo de trabalho isolado dá suporte a tipos de parâmetro de acordo com a tabela abaixo.

Gatilho de blob

O gatilho de blob pode ser associado aos seguintes tipos:

Type Descrição
string O conteúdo do blob como uma cadeia de caracteres. Use quando o conteúdo do blob for de texto simples.
byte[] Os bytes do conteúdo do blob.
Tipos serializáveis JSON Quando um blob contém dados JSON, o Functions tenta desserializar os dados JSON em um tipo de objeto CLR básico (POCO).
Fluxo1 Um fluxo de entrada do conteúdo do blob.
BlobClient1,
BlockBlobClient1,
PageBlobClient1,
AppendBlobClient1,
BlobBaseClient1		 Um cliente conectado ao blob. Esse conjunto de tipos oferece maior controle para processar o blob e pode ser usado para fazer write-back no blob se a conexão tiver permissão suficiente.

1 Para usar esses tipos, você precisa referenciar Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 ou posterior e as dependências comuns para associações do tipo SDK.

Associação de entrada de blob

Quando você quiser que a função processe um único blob, a associação de entrada de blob poderá ser associada aos seguintes tipos:

Type Descrição
string O conteúdo do blob como uma cadeia de caracteres. Use quando o conteúdo do blob for de texto simples.
byte[] Os bytes do conteúdo do blob.
Tipos serializáveis JSON Quando um blob contém dados JSON, o Functions tenta desserializar os dados JSON em um tipo de objeto CLR básico (POCO).
Fluxo1 Um fluxo de entrada do conteúdo do blob.
BlobClient1,
BlockBlobClient1,
PageBlobClient1,
AppendBlobClient1,
BlobBaseClient1		 Um cliente conectado ao blob. Esse conjunto de tipos oferece maior controle para processar o blob e pode ser usado para fazer write-back no blob se a conexão tiver permissão suficiente.

Quando você deseja que a função processe vários blobs de um contêiner, a associação de entrada de blob pode ser associada aos seguintes tipos:

Type Descrição
T[] ou List<T> em que T é um dos tipos de associação de entrada de blob único Uma matriz ou lista de vários blobs. Cada entrada representa um blob do contêiner. Você também pode associar a qualquer interface implementada por esses tipos, como IEnumerable<T>.
BlobContainerClient1 Um cliente conectado ao contêiner. Esse tipo oferece o maior controle para processar o contêiner e pode ser usado para gravar nele se a conexão tiver permissão suficiente.

1 Para usar esses tipos, você precisa referenciar Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0-preview2 ou posterior e as dependências comuns para associações do tipo SDK.

Associação de saída de blob

Quando você quiser que a função escreva em um único blob, a associação de saída de blob poderá ser associada aos seguintes tipos:

Type Descrição
string O conteúdo do blob como uma cadeia de caracteres. Use quando o conteúdo do blob for de texto simples.
byte[] Os bytes do conteúdo do blob.
Tipos serializáveis JSON Um objeto que representa o conteúdo de um blob JSON. O Functions tenta serializar um tipo de objeto CLR básico (POCO) em dados JSON.

Quando você desejar que a função escreva em vários blobs, a associação de saída de blob poderá ser associada aos seguintes tipos:

Type Descrição
T[] em que T é um dos tipos de associação de saída de blob único Uma matriz que contém conteúdo para vários blobs. Cada entrada representa o conteúdo de um blob.

Para outros cenários de saída, crie e use tipos diretamente de Azure.Storage.Blobs.

configurações de host.json

Esta seção descreve as definições de configuração do aplicativo de funções disponíveis para funções que usam essa associação. Essas configurações se aplicam somente ao usar a extensão versão 5.0.0 e superior. O arquivo host.json de exemplo abaixo contém apenas as configurações das versões 2.x e superiores para a associação. Para saber mais sobre as definições de configuração do aplicativo de funções nas versões 2.x e superiores, confira a referência de host.json para o Azure Functions.

Observação

Esta seção não se aplica a versões de extensão anteriores à 5.0.0. Para essas versões anteriores, não há nenhuma definição de configuração em todo o aplicativo de funções para blobs.

{
    "version": "2.0",
    "extensions": {
        "blobs": {
            "maxDegreeOfParallelism": 4,
            "poisonBlobThreshold": 1
        }
    }
}
Propriedade Padrão Descrição
maxDegreeOfParallelism 8 (o número de núcleos disponíveis) O número inteiro de invocações simultâneas permitidas para todas as funções disparadas por blob em um determinado aplicativo de funções. O valor mínimo permitido é 1.
poisonBlobThreshold 5 O número inteiro de vezes para tentar processar uma mensagem antes de movê-la para a fila de mensagens suspeitas. O valor mínimo permitido é 1.

Próximas etapas