Associação de saída de Armazenamento de Blobs do Azure para o Azure Functions

A associação de saída permite que você modifique e exclua dados de armazenamento de blobs em 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

O suporte do Go não está disponível para essa ligação no momento.

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 terminará para o modelo em processo em 10 de novembro de 2026. É altamente recomendável migrar 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 criação de um blob no contêiner test-samples-trigger aciona a função. 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.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace SampleApp
{
    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, usando OutputBinding (Java)

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[]. A anotação BlobOutput associa-se a OutputBinding outputItem, que é usado pela função para gravar o conteúdo do blob de entrada para o contêiner de armazenamento configurado.

  @FunctionName("copyBlobHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage copyBlobHttp(
    @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,
    @BlobOutput(
      name = "target", 
      path = "myblob/{Query.file}-CopyViaHttp")
    OutputBinding<String> outputItem,
    final ExecutionContext context) {
      // Save blob to outputItem
      outputItem.setValue(new String(content, StandardCharsets.UTF_8));

      // 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, usando o valor de retorno de função (Java)

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[]. A anotação BlobOutput associa-se ao valor de retorno da função, que é usado pelo runtime para gravar o conteúdo do blob de entrada para o contêiner de armazenamento configurado.

  @FunctionName("copyBlobQueueTrigger")
  @StorageAccount("Storage_Account_Connection_String")
  @BlobOutput(
    name = "target", 
    path = "myblob/{queueTrigger}-Copy")
  public String copyBlobQueue(
    @QueueTrigger(
      name = "filename", 
      dataType = "string",
      queueName = "myqueue-items") 
    String filename,
    @BlobInput(
      name = "file", 
      path = "samples-workitems/{queueTrigger}") 
    String content,
    final ExecutionContext context) {
      context.getLogger().info("The content of \"" + filename + "\" is: " + content);
      return content;
  }

Na biblioteca de runtime das funções Java , use a anotação @BlobOutput nos parâmetros da função cujo valor seria gravado em um objeto no armazenamento de blobs. O tipo de parâmetro deve ser OutputBinding<T>, onde T é qualquer tipo nativo de Java ou um simples objeto Java (POJO).

O exemplo a seguir mostra uma função TypeScript disparada por fila que faz uma cópia de um blob. Uma mensagem de fila que contém o nome do blob a ser copiado ativa a função. 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. Uma mensagem de fila que contém o nome do blob a ser copiado ativa a função. 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 demonstra como criar uma cópia de um blob de entrada como a saída de uma função do PowerShell.

No arquivo de configuração de função (function.json), a trigger propriedade de metadados é usada para especificar o nome do blob de saída nas propriedades path.

Observação

Para evitar loops infinitos, verifique se os caminhos de entrada e saída são diferentes.

{
  "bindings": [
    {
      "name": "myInputBlob",
      "path": "data/{trigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in",
      "type": "blobTrigger"
    },
    {
      "name": "myOutputBlob",
      "type": "blob",
      "path": "data/copy/{trigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false
}

Aqui está o código do PowerShell:

# Input bindings are passed in via param block.
param([byte[]] $myInputBlob, $TriggerMetadata)
Write-Host "PowerShell Blob trigger function Processed blob Name: $($TriggerMetadata.Name)"
Push-OutputBinding -Name myOutputBlob -Value $myInputBlob

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 construtor BlobOutputAttribute recebe 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.
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.

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

Anotações

O atributo @BlobOutput dá acesso ao blob que disparou a função. Se você usar matriz de bytes com o atributo, defina dataType como binary. Confira o exemplo de saída 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 output.storageBlob().

Propriedade Descrição
caminho O caminho para o contêiner do 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 Descrição
tipo Deve ser definido como blob.
direction Deve ser definido como out para uma associação de saída. 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. Definido como $return para referenciar o valor de retorno da função.
caminho O caminho para o contêiner do 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.

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 seja gravada em um único blob, a associação de saída de blob poderá ser associada aos seguintes tipos:

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

Tipo 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 um BlobClient ou BlobContainerClient com outros tipos diretamente de Azure.Storage.Blobs . Consulte Registrar clientes do Azure para obter um exemplo de como usar a injeção de dependência para criar um tipo de cliente do SDK do Azure.

A associação a string, ou Byte[], só é recomendada quando o blob é pequeno. O uso desses tipos é recomendado porque 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 @BlobOutput dá acesso ao blob que disparou a função. Se você usar matriz de bytes com o atributo, defina dataType como binary. Confira o exemplo de saída para detalhes.

Acesse os dados de blob retornando o valor diretamente ou usando context.extraOutputs.set().

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.

Você pode declarar parâmetros de função como os seguintes tipos para gravar no Armazenamento de Blobs:

  • Cadeias de caracteres como func.Out[str]
  • Fluxos como func.Out[func.InputStream]

Confira o exemplo de saída para detalhes.

conexões

A connection propriedade é definida como uma chave nas configurações da aplicação que retorna um valor usado pelo runtime das Funções para se conectar à conta de armazenamento usada pela extensão. O valor da configuração da propriedade de conexão depende do tipo de conexão:

  • Conexão de identidade gerenciada: A connection propriedade é <CONNECTION_NAME_PREFIX> compartilhada por um grupo de configurações que, juntas, definem uma conexão baseada em identidade com a conta de armazenamento. Para mais informações, veja Definir conexões de identidade.
  • Referência Key Vault: A connection configuração de propriedade retorna uma referência ao Azure Key Vault para o local onde a cadeia de conexão é mantida centralmente. Para mais informações, veja Definir conexões do Key Vault.
  • Referência de App Configuration: A connection configuração de propriedade retorna uma referência ao Configuração de Aplicativos do Azure que retorna uma cadeia de conexão ou uma referência ao Key Vault. Para mais informações, veja Configuração de Aplicativos do Azure no artigo de conexões.
  • Connection string: A connection configuração de propriedade retorna a cadeia de conexão real da conta de armazenamento. Como a cadeia de conexão contém chaves secretas compartilhadas, você deve considerar usar uma conexão de identidade gerenciada, sempre que possível. Para mais informações, veja Definir conexões.

Para saber mais sobre conexões de bindings, veja Gerenciar conexão no Azure Functions. Para obter uma cadeia de conexão, execute as etapas mostradas em Gerenciar as chaves de acesso à conta de armazenamento.

Quando você define connection para uma chave ou prefixo de chave nomeado AzureWebJobsStorage ou para uma string vazia, a extensão de binding usa a conta padrão de armazenamento do host. Para mais informações, veja Otimizar desempenho de armazenamento.

Exceções e códigos de retorno

Associação Referência
Blob Códigos de erro de Blob
Blob, tabela, fila Códigos de erro de armazenamento
Blob, tabela, fila Solução de problemas

Próximas etapas

  • Last updated on