Associação de entrada de Armazenamento de Blobs do Azure para o Azure Functions

  • Artigo

A associação de entrada permite que você leia dados do armazenamento de blobs como entrada para uma Função do Azure.

Para obter informações sobre a instalação e detalhes de configuração, confira a visão geral.

Importante

Este artigo usa guias para dar suporte a várias versões do modelo de programação Node.js. O modelo v4 normalmente está disponível e foi projetado para oferecer uma experiência mais flexível e intuitiva para desenvolvedores de JavaScript e TypeScript. Para obter mais detalhes sobre como funciona o modelo v4, consulte o Guia do desenvolvedor do Node.js para o Azure Functions. Para saber mais sobre as diferenças entre os modelos v3 e a v4, consulte o Guia de migração.

O Azure Functions dá suporte a dois modelos de programação para Python. A maneira como você define suas associações depende do modelo de programação escolhido.

O modelo de programação v2 do Python permite que você defina associações usando decoradores diretamente no código de função do Python. Para saber mais, confira o Guia do desenvolvedor do Python.

Este artigo dá suporte a ambos os modelos de programação.

Exemplo

A função C# pode ser criada por meio de um dos seguintes modos C#:

  • Modelo de trabalho isolado: função C# compilada executada em um processo de trabalho que está isolado do runtime. É necessário um processo de trabalho isolado para dar suporte às funções C# executadas nas versões LTS e não LTS do .NET e do .NET Framework. As extensões para funções do processo de trabalho isoladas usam namespaces Microsoft.Azure.Functions.Worker.Extensions.*.
  • Modelo em processo: função C# compilada no mesmo processo que o runtime do Functions. Em uma variação desse modelo, o Functions pode ser executado usando scripts C#, que é compatível principalmente com a edição do portal C#. As extensões para funções dentro do processo usam namespaces Microsoft.Azure.WebJobs.Extensions.*.

Importante

O suporte para o modelo em processo terminará em 10 de novembro de 2026. É altamente recomendável que você migre seus aplicativos para o modelo de trabalho isolado para obter suporte completo.

O exemplo a seguir é uma função C# executada em um processo de trabalho isolado e usa um gatilho de blob com as associações de entrada e de saída de blob. A função é disparada pela criação de um blob no contêiner de teste-amostras-disparo. Ele lê um arquivo de texto do contêiner de teste-amostras-disparo e cria um novo arquivo de texto em um contêiner de saída com base no nome do arquivo disparado.

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

Esta seção contém os seguintes exemplos:

Gatilho HTTP, o nome do blob da cadeia de caracteres de consulta

O exemplo a seguir mostra uma função de Java que usa a anotação HttpTrigger para receber um parâmetro que contém o nome de um arquivo em um contêiner de armazenamento de blob. Em seguida, a anotação BlobInput lê o arquivo e passa seu conteúdo para a função como um 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();
  }

Gatilho de fila, receber o nome do blob da mensagem da fila

O exemplo a seguir mostra uma função de Java que usa a anotação QueueTrigger para receber uma mensagem que contém o nome de um arquivo em um contêiner de armazenamento de blob. Em seguida, a anotação BlobInput lê o arquivo e passa seu conteúdo para a função como um 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");
  }

Na biblioteca de runtime de funções Java, use a anotação @BlobInput nos parâmetros cujo valor viria de um blob. Essa anotação pode ser usada com tipos nativos do Java, POJOs ou valores que permitem valor nulos usando Optional<T>.

O exemplo a seguir mostra uma função TypeScript disparada por fila que faz uma cópia de um blob. A função é disparada por uma mensagem da fila que contém o nome do blob para copiar. O novo blob é nomeado {originalblobname}-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,
});

O exemplo a seguir mostra uma função JavaScript acionada por fila que faz uma cópia de um blob. A função é disparada por uma mensagem da fila que contém o nome do blob para copiar. O novo blob é nomeado {originalblobname}-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);
    },
});

O exemplo a seguir mostra uma associação de entrada de blob, definida no arquivo function.json, que disponibiliza os dados de blob de entrada para a função do PowerShell.

Aqui está a configuração do json:

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

Aqui está o código de função:

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

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

O exemplo a seguir mostra as associações de entrada e saída do blob. O exemplo depende se você utiliza o modelo de programação do Python v1 ou v2.

O código cria uma cópia de um 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

As bibliotecas C# em processo e de processo de trabalho isolado usam atributos para definir a função. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia do script C#.

O processo de trabalho isolado define uma associação de entrada usando um BlobInputAttribute atributo, que usa os seguintes parâmetros:

Parâmetro Descrição
BlobPath O caminho para o blob.
Conexão O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Blobs do Azure. Confira a opção Conexões.

Quando você estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na coleção Values.

Decoradores

Aplica-se apenas ao modelo de programação do Python v2.

Para as funções do Python v2 definidas utilizando decoradores, as seguintes propriedades nos decoradores blob_input e blob_output definem os gatilhos do Armazenamento de Blobs:

Propriedade DESCRIÇÃO
arg_name O nome da variável que representa o blob no código de função.
path O caminho do blob Para o decorador blob_input, é a leitura do blob. Para o decorador blob_output, é a saída ou cópia do blob de entrada.
connection A cadeia de conexão da conta de armazenamento.
data_type Para linguagens tipificadas dinamicamente, especifica o tipo de dados subjacente. Os valores possíveis são string, binary, ou stream. Para obter mais detalhes, consulte conceitos de gatilhos e associações.

Para funções do Python definidas usando function.json, confira a seção Configuração.

Anotações

O atributo @BlobInput dá acesso ao blob que disparou a função. Se você usar matriz de bytes com o atributo, defina dataType como binary. Veja o exemplo de entrada para detalhes.

Configuração

Aplica-se apenas ao modelo de programação v1 do Python.

A tabela a seguir explica as propriedades que você pode definir no objeto options transmitido para o método input.storageBlob().

Propriedade Descrição
caminho O caminho para o blob.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Blobs do Azure. Confira a opção Conexões.

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como blob.
direction Deve ser definido como in. As exceções são mencionadas na seção uso.
name O nome da variável que representa o blob no código de função.
path O caminho para o blob.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Blobs do Azure. Confira a opção Conexões.
dataType Para linguagens tipificadas dinamicamente, especifica o tipo de dados subjacente. Os valores possíveis são string, binary, ou stream. Para obter mais detalhes, consulte conceitos de gatilhos e associações.

Consulte a Seção de exemplo para obter exemplos completos.

Uso

Os tipos de associação compatíveis com a saída de Blob dependem da versão do pacote de extensão e da modalidade C# usada em seu aplicativo de funções.

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.

A associação a string, ou Byte[], só é recomendada quando o blob é pequeno. O motivo é que todo o conteúdo do blob é carregado na memória. Para a maioria dos blobs, use um tipo Stream ou BlobClient. Para obter mais informações, consulte Simultaneidade e uso de memória, adiante neste artigo.

Se você receber uma mensagem de erro ao tentar associar a um dos tipos de SDK de armazenamento, certifique-se de ter uma referência à versão correta do SDK de armazenamento.

Você também pode usar o StorageAccountAttribute para especificar a conta de armazenamento a ser usada. Isso pode ser feito quando for necessário usar uma conta de armazenamento diferente de outras funções na biblioteca. O construtor toma o nome de uma configuração de aplicativo que contenha uma cadeia de conexão de armazenamento. O atributo pode ser aplicado no nível de classe, método ou parâmetro. O exemplo a seguir mostra o nível de classe e método:

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

A conta de armazenamento a ser usada é determinada na seguinte ordem:

  • A propriedade BlobTrigger do atributoConnection.
  • O StorageAccount atributo aplicado ao mesmo parâmetro do BlobTrigger atributo.
  • O StorageAccount atributo aplicado à função.
  • O StorageAccount atributo aplicado à classe.
  • A conta de armazenamento padrão do aplicativo de funções, que é definido na configuração do aplicativo AzureWebJobsStorage.

O atributo @BlobInput dá acesso ao blob que disparou a função. Se você usar matriz de bytes com o atributo, defina dataType como binary. Veja o exemplo de entrada para detalhes.

Acesse os dados de blob usando context.extraInputs.get().

Acesse os dados de blob por meio de um parâmetro que corresponde ao nome designado pelo parâmetro de nome da associação no arquivo function.json.

Acesse dados de blob por meio do parâmetro digitado como InputStream. Veja o exemplo de entrada para detalhes.

conexões

A propriedade connection é uma referência à configuração do ambiente que especifica como o aplicativo deve se conectar aos Blobs do Azure. Ela pode especificar:

Se o valor configurado for uma combinação exata para uma única configuração e um correspondência de prefixo para outras configurações, a correspondente exata será usada.

Cadeia de conexão

Para obter uma cadeia de conexão, execute as etapas mostradas em Gerenciar as chaves de acesso à conta de armazenamento. A cadeia de conexão deve ser uma conta de armazenamento para uso geral e não uma conta de Armazenamento de Blobs.

Essa cadeia de conexão deve ser armazenada em uma configuração de aplicativo com um nome que corresponda ao valor especificado pela propriedade connection da configuração de associação.

Se o nome de configuração do aplicativo começar com "AzureWebJobs", você pode especificar apenas o resto do nome aqui. Por exemplo, se você configurar connection para "MyStorage", o runtime do Functions procurará uma configuração de aplicativo chamada "AzureWebJobsMyStorage". Se você deixar connection vazio, o runtime de Functions usa a cadeia de caracteres de conexão de Armazenamento padrão na configuração de aplicativo chamada AzureWebJobsStorage.

Conexões baseadas em identidade

Se você estiver usando a versão 5.x ou superior da extensão (pacote 3.x ou superior para pilhas de idiomas non-.NET), em vez de usar uma cadeia de conexão com um segredo, poderá fazer com que o aplicativo use uma identidade do Microsoft Entra. Para usar uma identidade, você define as configurações sob um prefixo comum que mapeia para a propriedade connection na configuração do gatilho e da vinculação.

Se estiver definindo connection como "AzureWebJobsStorage", confira Como se conectar ao armazenamento host com uma identidade. Para todas as outras conexões, a extensão requer as seguintes propriedades:

Propriedade Modelo de variável de ambiente Descrição Valor de exemplo
URI do Serviço Blob <CONNECTION_NAME_PREFIX>__serviceUri1 O URI do plano de dados do serviço blob ao qual você está se conectando, usando o esquema HTTPS. https://<storage_account_name>.blob.core.windows.net

1<CONNECTION_NAME_PREFIX>__blobServiceUri pode ser usado como um alias. Se a configuração de conexão for usada por um gatilho de blob, blobServiceUri também precisará ser acompanhada de queueServiceUri. Veja abaixo.

O formulário serviceUri não pode ser usado quando a configuração geral da conexão deve ser usada em blobs, filas e/ou tabelas. O URI só pode designar o serviço blob. Como alternativa, você pode fornecer um URI especificamente para cada serviço, permitindo o uso de uma única conexão. Se as duas versões forem fornecidas, o formulário de vários serviços será utilizado. Para configurar a conexão para vários serviços, em vez de <CONNECTION_NAME_PREFIX>__serviceUri, defina:

Propriedade Modelo de variável de ambiente Descrição Valor de exemplo
URI do Serviço Blob <CONNECTION_NAME_PREFIX>__blobServiceUri O URI do plano de dados do serviço blob ao qual você está se conectando, usando o esquema HTTPS. https://<storage_account_name>.blob.core.windows.net
URI do Serviço Fila (necessário para gatilhos de blob2) <CONNECTION_NAME_PREFIX>__queueServiceUri O URI do plano de dados de um serviço de fila, usando o esquema HTTPS. Esse valor só é necessário para gatilhos de blob. https://<nome_da_conta_de_armazenamento>.queue.core.windows.net

2 O gatilho de blob lida com a falha em várias repetições gravando blobs suspeitos em uma fila. No formulário serviceUri, a conexão AzureWebJobsStorage é usada. No entanto, ao especificar blobServiceUri, um URI do serviço de fila também precisa ser fornecido com queueServiceUri. É recomendável que você utilize o serviço da mesma conta de armazenamento que o serviço blob. Você também precisa garantir que o gatilho possa ler e gravar mensagens no serviço de fila configurado atribuindo uma função do tipo Colaborador de Dados da Fila de Armazenamento.

Outras propriedades podem ser definidas para personalizar a conexão. Confira Propriedades comuns para conexões baseadas em identidade.

Quando hospedadas no serviço de Azure Functions, as conexões baseadas em identidade usam uma identidade gerenciada. A identidade atribuída pelo sistema é usada por padrão, embora a identidade atribuída pelo usuário possa ser especificada com as propriedades credential e clientID. Observe que não há suporte para configurar uma identidade atribuída pelo usuário com uma ID de recurso. Quando executado em outros contextos, como desenvolvimento local, a identidade do desenvolvedor é usada, embora isso possa ser personalizado. Confira Desenvolvimento local com conexões baseadas em identidade.

Conceder permissão para a identidade

Qualquer identidade que esteja sendo usada deve ter permissões para executar as ações pretendidas. Para a maioria dos serviços do Azure, isso significa que será necessário atribuir uma função no Azure RBAC, usando as funções internas ou as personalizadas que fornecem essas permissões.

Importante

Algumas permissões que não são necessárias em todos os contextos podem ser expostas pelo serviço de destino. Sempre que possível, siga o princípio do privilégio mínimo, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo precisar apenas ser capaz de ler uma fonte de dados, use uma função que só tenha permissão de leitura. Seria inapropriado atribuir uma função que também permitisse a gravação nesse serviço, pois seria um excesso de permissões para uma operação de leitura. Da mesma forma, seria melhor garantir que a atribuição da função tivesse o escopo apenas sobre os recursos que precisam ser lidos.

Você precisa criar uma atribuição de função que forneça acesso ao seu contêiner de blobs no runtime. As funções de gerenciamento como a de Proprietário não são suficientes. A tabela a seguir mostra as funções internas recomendadas ao usar a extensão do Armazenamento de Blobs em operação normal. Seu aplicativo pode exigir mais permissões com base no código que você escrever.

Tipo de associação Exemplo de funções internas
Gatilho Proprietário de dados do blob de armazenamento e Colaborador de dados da fila de armazenamento1

Permissões extras também devem ser concedidas à conexão AzureWebJobsStorage.2
Associação de entrada Leitor de Dados do Blob de Armazenamento
Associação de saída Proprietário de Dados do Blob de Armazenamento

1 O gatilho de blob lida com a falha em várias tentativas gravando blobs suspeitos em uma fila na conta de armazenamento especificada pela conexão.

2 A conexão AzureWebJobsStorage é usada internamente para blobs e filas que habilitam o gatilho. Se estiver configurado para usar uma conexão baseada em identidade, ele precisará de permissões extras além do requisito padrão. As permissões necessárias são cobertas pelas funções Proprietário de Dados de Blobs de Armazenamento, Colaborador de Dados da Fila de Armazenamento e Colaborador da Conta de Armazenamento. Para saber mais, confira Conectar-se ao armazenamento de host com uma identidade.

Próximas etapas