Vinculação de entrada de armazenamento de Blob do Azure para o Azure Functions

  • Artigo

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

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

Importante

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

O Azure Functions suporta dois modelos de programação para Python. A maneira como você define suas ligações depende do modelo de programação escolhido.

O modelo de programação Python v2 permite definir ligações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor do Python.

Este artigo suporta ambos os modelos de programação.

Exemplo

Uma função C# pode ser criada usando um dos seguintes modos C#:

  • Modelo de trabalho isolado: função C# compilada que é executada em um processo de trabalho isolado do tempo de execução. O processo de trabalho isolado é necessário para suportar funções C# em execução nas versões LTS e não-LTS .NET e .NET Framework. As extensões para funções isoladas do processo de trabalho usam Microsoft.Azure.Functions.Worker.Extensions.* namespaces.
  • Modelo em processo: função C# compilada que é executada no mesmo processo que o tempo de execução do Functions. Em uma variação desse modelo, as funções podem ser executadas usando scripts em C#, que são suportados principalmente para edição de portal em C#. As extensões para funções em processo usam Microsoft.Azure.WebJobs.Extensions.* namespaces.

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

O exemplo a seguir é uma função C# que é executada em um processo de trabalho isolado e usa um gatilho de blob com ligações de blob de entrada e saída de blob. A função é acionada pela criação de um blob no contêiner test-samples-trigger . Ele lê um arquivo de texto do contêiner test-samples-input e cria um novo arquivo de texto em um contêiner de saída com base no nome do arquivo acionado.

    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, procure o nome do blob na cadeia de caracteres de consulta

O exemplo a seguir mostra uma função Java que usa a HttpTrigger anotação para receber um parâmetro contendo o nome de um arquivo em um contêiner de armazenamento de blob. Em BlobInput seguida, a anotação lê o arquivo e passa seu conteúdo para a função como um byte[]arquivo .

  @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 nome de blob da mensagem de fila

O exemplo a seguir mostra uma função Java que usa a QueueTrigger anotação para receber uma mensagem contendo o nome de um arquivo em um contêiner de armazenamento de blob. Em BlobInput seguida, a anotação lê o arquivo e passa seu conteúdo para a função como um byte[]arquivo .

  @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 tempo de execução de funções Java, use a @BlobInput anotação em parâmetros cujo valor viria de um blob. Essa anotação pode ser usada com tipos Java nativos, POJOs ou valores anuláveis usando Optional<T>.

O exemplo a seguir mostra uma função TypeScript acionada por fila que faz uma cópia de um blob. A função é acionada por uma mensagem de fila que contém o nome do blob a ser copiado. O novo blob é chamado {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 é acionada por uma mensagem de fila que contém o nome do blob a ser copiado. O novo blob é chamado {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 torna os dados de blob de entrada disponíveis para a função do PowerShell .

Aqui está a configuração json:

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

Aqui está o código da 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 ligações de entrada e saída de blob. O exemplo depende se você usa o modelo de programação 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# do processo de trabalho em processo e isoladas 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 de script C#.

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

Parâmetro Description
BlobPath O caminho para o blob.
Ligação O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar aos Blobs do Azure. Consulte Conexões.

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

Decoradores

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

Para funções Python v2 definidas usando decoradores, as seguintes propriedades no blob_input e blob_output decoradores definem os gatilhos de armazenamento de Blob:

Property Description
arg_name O nome da variável que representa o blob no código da função.
path O caminho para o blob Para o blob_input decorador, é o blob lido. Para o blob_output decorador, é a saída ou cópia do blob de entrada.
connection A cadeia de ligação da conta de armazenamento.
data_type Para idiomas digitados dinamicamente, especifica o tipo de dados subjacente. Os valores possíveis são string, binary, ou stream. Para obter mais detalhes, consulte os conceitos de gatilhos e vinculações.

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

Anotações

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

Configuração

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

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

Property Description
path 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 aos Blobs do Azure. Consulte Conexões.

A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json .

function.json propriedade Description
type Deve ser definido como blob.
direção Deve ser definido como in. As exceções são observadas na seção de uso .
Designação O nome da variável que representa o blob no código da função.
path 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 aos Blobs do Azure. Consulte Conexões.
Tipo de dados Para idiomas digitados dinamicamente, especifica o tipo de dados subjacente. Os valores possíveis são string, binary, ou stream. Para obter mais detalhes, consulte os conceitos de gatilhos e vinculações.

Consulte a seção Exemplo para obter exemplos completos.

Utilização

Os tipos de associação suportados pela entrada Blob dependem da versão do pacote de extensão e da modalidade C# usada em seu aplicativo de função.

Quando você deseja que a função processe um único blob, a ligação de entrada de blob pode se vincular aos seguintes tipos:

Tipo Description
string O conteúdo de blob como uma cadeia de caracteres. Use quando o conteúdo do blob for 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 (POCO) simples.
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 o maior controle para processar o blob e pode ser usado para gravar nele se a conexão tiver permissão suficiente.

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

Tipo Description
T[] ou List<T> onde T é um dos tipos de ligaçã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 vincular a quaisquer interfaces implementadas 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 fazer referência a Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 ou posterior e às dependências comuns para associações de tipo SDK.

A ligação ao string, ou Byte[] só é recomendada quando o tamanho do blob é pequeno. Isso é recomendado porque todo o conteúdo do blob é carregado na memória. Para a maioria dos blobs, use um Stream ou BlobClient tipo. Para obter mais informações, consulte Simultaneidade e uso de memória.

Se você receber uma mensagem de erro ao tentar vincular 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. Você pode fazer isso quando precisar usar uma conta de armazenamento diferente de outras funções na biblioteca. O construtor leva o nome de uma configuração de aplicativo que contém uma cadeia de conexão de armazenamento. O atributo pode ser aplicado no nível de parâmetro, método ou classe. O exemplo a seguir mostra o nível da classe e o nível do 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 BlobTrigger propriedade do Connection atributo.
  • O StorageAccount atributo aplicado ao mesmo parâmetro que o BlobTrigger atributo.
  • O StorageAccount atributo aplicado à função.
  • O StorageAccount atributo aplicado à classe.
  • A conta de armazenamento padrão para o aplicativo de função, que é definida na configuração do AzureWebJobsStorage aplicativo.

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

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

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

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

Ligações

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

  • O nome de uma configuração de aplicativo que contém uma cadeia de conexão
  • O nome de um prefixo compartilhado para várias configurações de aplicativo, definindo em conjunto uma conexão baseada em identidade.

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

Connection string

Para obter uma cadeia de conexão, siga as etapas mostradas em Gerenciar chaves de acesso da conta de armazenamento. A cadeia de conexão deve ser para uma conta de armazenamento de uso geral, não uma conta de armazenamento de Blob.

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

Se o nome da configuração do aplicativo começar com "AzureWebJobs", você poderá especificar apenas o restante do nome aqui. Por exemplo, se você definir connection como "MyStorage", o tempo de execução do Functions procurará uma configuração de aplicativo chamada "AzureWebJobsMyStorage". Se você deixar connection vazio, o tempo de execução do Functions usará a cadeia de conexão de armazenamento padrão na configuração do 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, você pode fazer com que o aplicativo use uma identidade do Microsoft Entra. Para usar uma identidade, defina as configurações sob um prefixo comum que mapeia para a connection propriedade na configuração de gatilho e ligação.

Se você estiver definindo connection como "AzureWebJobsStorage", consulte Conectando-se ao armazenamento de host com uma identidade. Para todas as outras conexões, a extensão requer as seguintes propriedades:

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

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

O serviceUri formulário 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 de blob. Como alternativa, você pode fornecer um URI especificamente para cada serviço, permitindo que uma única conexão seja usada. Se ambas as versões forem fornecidas, o formulário multisserviço será usado. Para configurar a conexão para vários serviços, em vez de <CONNECTION_NAME_PREFIX>__serviceUri, defina:

Property Modelo de variável de ambiente Description Valor de exemplo
URI do serviço de Blob <CONNECTION_NAME_PREFIX>__blobServiceUri O URI do plano de dados do serviço de blob ao qual você está se conectando, usando o esquema HTTPS. https://< storage_account_name.blob.core.windows.net>
URI do Serviço de Fila (necessário para gatilhos deblob 2) <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://< storage_account_name.queue.core.windows.net>

2 O gatilho de blob lida com falhas em várias tentativas gravando blobs venenosos em uma fila. No formulário, a serviceUriAzureWebJobsStorage conexão é usada. No entanto, ao especificar blobServiceUri, um URI de serviço de fila também deve ser fornecido com queueServiceUri. É recomendável que você use o serviço da mesma conta de armazenamento que o serviço de blob. Você também precisa certificar-se de que o gatilho pode ler e gravar mensagens no serviço de fila configurado atribuindo uma função como Colaborador de Dados da Fila de Armazenamento.

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

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

Conceder permissão à 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 você precisa atribuir uma função no RBAC do Azure, usando funções internas ou personalizadas que fornecem essas permissões.

Importante

Algumas permissões podem ser expostas pelo serviço de destino que não são necessárias para todos os contextos. Sempre que possível, aderir ao princípio do menor privilégio, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo só precisa ser capaz de ler de uma fonte de dados, use uma função que só tenha permissão para ler. Seria inadequado atribuir uma função que também permita escrever a esse serviço, pois isso seria uma permissão excessiva para uma operação de leitura. Da mesma forma, convém garantir que a atribuição de função tenha 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 blob em tempo de execução. Funções de gerenciamento como Proprietário não são suficientes. A tabela a seguir mostra as funções internas recomendadas ao usar a extensão de Armazenamento de Blob em operação normal. Seu aplicativo pode exigir permissões adicionais com base no código que você escreve.

Tipo de vinculação Exemplo de funções internas
Acionador Proprietáriode dados de blob de armazenamento econtribuidorde dados da fila de armazenamento 1

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

1 O gatilho de blob lida com falhas em várias tentativas gravando blobs venenosos 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 Blob de Armazenamento, Colaborador de Dados da Fila de Armazenamento e Colaborador de Conta de Armazenamento. Para saber mais, consulte Conectando-se ao armazenamento do host com uma identidade.

Próximos passos