Vinculação de saída de armazenamento de Blob do Azure para o Azure Functions

  • Artigo

A associação de saída permite modificar e excluir dados de armazenamento de blob em 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.

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 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 . A BlobOutput anotação se liga ao OutputBinding outputItem, que é usado pela função para gravar o conteúdo do blob de entrada no 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 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 . A BlobOutput anotação se liga ao valor de retorno da função, que é usado pelo tempo de execução para gravar o conteúdo do blob de entrada no 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 tempo de execução de funções Java, use a @BlobOutput anotação em parâmetros de 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 Java nativo ou um POJO.

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 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 da função (function.json), a trigger propriedade metadata é usada para especificar o nome do blob de saída nas pathpropriedades.

Nota

Para evitar loops infinitos, certifique-se de que seus caminhos de entrada e saída sejam 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 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 o atributo 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 BlobOutputAttribute construtor 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.
dataType 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 @BlobOutput 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 saída 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 output.storageBlob() método.

Property Description
path O caminho para o contêiner de 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 .

Property Descrição
type Deve ser definido como blob.
direção Deve ser definido como out para uma ligação de saída. 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. Defina como $return para fazer referência ao valor de retorno da função.
path O caminho para o contêiner de 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.

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

Utilização

Os tipos de vinculação suportados pela saída de 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 grave em um único blob, a ligação de saída 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 Um objeto que representa o conteúdo de um blob JSON. As funções tentam serializar um tipo de objeto CLR (POCO) antigo em dados JSON.

Quando você deseja que a função grave em vários blobs, a ligação de saída de blob pode se vincular aos seguintes tipos:

Tipo Description
T[] onde T é um dos tipos de ligaçã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 de Azure.Storage.Blobs diretamente.

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 @BlobOutput 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 saída para obter detalhes.

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

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 .

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

  • Strings como func.Out[str]
  • Fluxos como func.Out[func.InputStream]

Consulte o exemplo de saída 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.

Exceções e códigos de devolução

Enlace Referência
Blob Códigos de erro de blob
Blob, Tabela, Fila Códigos de erro de armazenamento
Blob, Tabela, Fila Resolução de problemas

Próximos passos