Gatilho do Armazenamento de Blobs do Azure para o Azure Functions

O gatilho de armazenamento de Blob inicia uma função quando é detectado um blob novo ou atualizado. O conteúdo do blob é fornecido como entrada para a função.

Dica

Há várias maneiras de executar seu código de função com base em alterações em blobs em um contêiner de armazenamento, e o gatilho de armazenamento de blobs pode não ser a melhor opção. Para saber mais sobre opções alternativas de gatilho, consulte Trabalhando com blobs.

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.

v2

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.

v1

O modelo de programação v1 do Python requer que você defina as associações em um arquivo function.json separado na pasta de funções. 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.

Modelo de trabalho isolado

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

Modelo em processo

O exemplo a seguir mostra uma função C# que grava um log quando um blob é adicionado ou atualizado no contêiner samples-workitems.

[FunctionName("BlobTriggerCSharp")]        
public static void Run([BlobTrigger("samples-workitems/{name}")] Stream myBlob, string name, ILogger log)
{
    log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name} \n Size: {myBlob.Length} Bytes");
}

A cadeia de caracteres {name} no caminho do disparador de blob samples-workitems/{name} cria uma {name} que você pode usar no código de função para acessar o nome de arquivo do blob disparando. Para obter mais informações, consulte Padrões de nome do blob a seguir neste artigo.

Para obter mais informações sobre o atributo BlobTrigger, consulte Atributos.

Esta função grava um log quando um blob é adicionado ou atualizado no contêiner myblob.

@FunctionName("blobprocessor")
public void run(
  @BlobTrigger(name = "file",
               dataType = "binary",
               path = "myblob/{name}",
               connection = "MyStorageAccountAppSetting") byte[] content,
  @BindingName("name") String filename,
  final ExecutionContext context
) {
  context.getLogger().info("Name: " + filename + " Size: " + content.length + " bytes");
}

Modelo v4

O exemplo a seguir mostra um código TypeScript do gatilho de blob. A função grava um log quando um blob é adicionado ou atualizado no samples-workitems contêiner.

A cadeia de caracteres {name} no caminho do disparador de blob samples-workitems/{name} cria uma {name} que você pode usar no código de função para acessar o nome de arquivo do blob disparando. Para obter mais informações, consulte Padrões de nome do blob a seguir neste artigo.

import { app, InvocationContext } from '@azure/functions';

export async function storageBlobTrigger1(blob: Buffer, context: InvocationContext): Promise<void> {
    context.log(
        `Storage blob function processed blob "${context.triggerMetadata.name}" with size ${blob.length} bytes`
    );
}

app.storageBlob('storageBlobTrigger1', {
    path: 'samples-workitems/{name}',
    connection: 'MyStorageAccountAppSetting',
    handler: storageBlobTrigger1,
});

Modelo v3

Os exemplos de TypeScript não estão documentados para o modelo v3.

Modelo v4

O exemplo a seguir mostra um código JavaScript do gatilho de blob. A função grava um log quando um blob é adicionado ou atualizado no samples-workitems contêiner.

A cadeia de caracteres {name} no caminho do disparador de blob samples-workitems/{name} cria uma {name} que você pode usar no código de função para acessar o nome de arquivo do blob disparando. Para obter mais informações, consulte Padrões de nome do blob a seguir neste artigo.

const { app } = require('@azure/functions');

app.storageBlob('storageBlobTrigger1', {
    path: 'samples-workitems/{name}',
    connection: 'MyStorageAccountAppSetting',
    handler: (blob, context) => {
        context.log(
            `Storage blob function processed blob "${context.triggerMetadata.name}" with size ${blob.length} bytes`
        );
    },
});

Modelo v3

O exemplo a seguir mostra uma associação de gatilho de blob em um arquivo function.json e código JavaScript que usa a associação. A função grava um log quando um blob é adicionado ou atualizado no samples-workitems contêiner.

Aqui está o arquivo function.json:

{
    "disabled": false,
    "bindings": [
        {
            "name": "myBlob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

A cadeia de caracteres {name} no caminho do disparador de blob samples-workitems/{name} cria uma {name} que você pode usar no código de função para acessar o nome de arquivo do blob disparando. Para obter mais informações, consulte Padrões de nome do blob a seguir neste artigo.

Para obter mais informações sobre as propriedades do arquivo function.json, consulte a seção Configuração que explica essas propriedades.

Aqui está o código JavaScript:

module.exports = async function(context) {
    context.log('Node.js Blob trigger function processed', context.bindings.myBlob);
};

O exemplo a seguir demonstra como criar uma função que é executada quando um arquivo é adicionado ao contêiner de armazenamento de blob source.

O arquivo de configuração de função (function.json) inclui uma associação com o type de blobTrigger e direction definido como in.

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

Aqui está o código associado ao arquivo run.ps1.

param([byte[]] $InputBlob, $TriggerMetadata)

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

O exemplo a seguir mostra uma associação de gatilho de blob. O exemplo depende do modelo de programação v1 ou v2 do Python que você usa.

v2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="BlobTrigger1")
@app.blob_trigger(arg_name="myblob", 
                  path="PATH/TO/BLOB",
                  connection="CONNECTION_SETTING")
def test_function(myblob: func.InputStream):
   logging.info(f"Python blob trigger function processed blob \n"
                f"Name: {myblob.name}\n"
                f"Blob Size: {myblob.length} bytes")

v1

A função grava um log quando um blob é adicionado ou atualizado no samples-workitemssamples-workitems. Aqui está o arquivo function.json:

{
    "scriptFile": "__init__.py",
    "disabled": false,
    "bindings": [
        {
            "name": "myblob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

A cadeia de caracteres {name} no caminho do disparador de blob samples-workitems/{name} cria uma {name} que você pode usar no código de função para acessar o nome de arquivo do blob disparando. Para obter mais informações, consulte Padrões de nome do blob a seguir neste artigo.

Para obter mais informações sobre as propriedades do arquivo function.json, consulte a seção Configuração que explica essas propriedades.

Aqui está o código Python:

import logging
import azure.functions as func


def main(myblob: func.InputStream):
    logging.info('Python Blob trigger function processed %s', myblob.name)

---

Atributos

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

O construtor do atributo 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.
Acesso	Indica se você será leitura ou gravação.
Origem	Define a origem do evento de gatilho. Use BlobTriggerSource.EventGrid para um gatilho de blob baseado na Grade de Eventos, que oferece uma latência muito menor. O padrão é BlobTriggerSource.LogsAndContainerScan, que usa o mecanismo de sondagem padrão para detectar alterações no contêiner.

Modelo de trabalho isolado

Aqui está um atributo BlobTrigger em uma assinatura de método:

[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)

Modelo em processo

Em bibliotecas de classe C#, o construtor do atributo usa uma string de caminho que indica o contêiner a ser observado e, como alternativa, um padrão de nome de blob. Veja um exemplo:

[FunctionName("ResizeImage")]
public static void Run(
  [BlobTrigger("sample-images/{name}")] Stream image,
  [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall)
{
  ....
}

Embora o atributo use uma propriedade Connection, não é possível usar Connection para especificar uma conexão da conta de armazenamento. 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("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

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

• A propriedade Connection do atributo de gatilho ou associação.
• O atributo StorageAccount aplicado ao mesmo parâmetro do atributo de gatilho ou associação.
• 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.

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 v2 do Python definidas utilizando decoradores, as seguintes propriedades no decorador blob_trigger definem os gatilhos do Armazenamento de Blobs:

Propriedade	Descrição
arg_name	Declara o nome do parâmetro na assinatura de função. Quando a função é disparada, o valor desse parâmetro tem o conteúdo da mensagem da fila.
path	O contêiner para monitorar. Pode ser um padrão de nome de blob.
connection	A cadeia de conexão da conta de armazenamento.
source	Define a origem do evento de gatilho. Use EventGrid para um gatilho de blob baseado na Grade de Eventos, que oferece uma latência muito menor. O padrão é LogsAndContainerScan, que usa o mecanismo de sondagem padrão para detectar alterações no contêiner.

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

Anotações

O atributo @BlobTrigger é usado para dar acesso ao blob que disparou a função. Confira o exemplo de gatilho para obter detalhes. Use a propriedade source para definir a origem do evento de gatilho. Use EventGrid para um gatilho de blob baseado na Grade de Eventos, que oferece uma latência muito menor. O padrão é LogsAndContainerScan, que usa o mecanismo de sondagem padrão para detectar alterações no contêiner. |

Configuração

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

Modelo v4

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

Propriedade	Descrição
caminho	O contêiner para monitorar. Pode ser um padrão de nome de 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.
source	Define a origem do evento de gatilho. Use EventGrid para um gatilho de blob baseado na Grade de Eventos, que oferece uma latência muito menor. O padrão é LogsAndContainerScan, que usa o mecanismo de sondagem padrão para detectar alterações no contêiner.

Modelo v3

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 blobTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction	Deve ser definido como in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure. 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 contêiner para monitorar. Pode ser um padrão de nome de 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.
source	Define a origem do evento de gatilho. Use EventGrid para um gatilho de blob baseado na Grade de Eventos, que oferece uma latência muito menor. O padrão é LogsAndContainerScan, que usa o mecanismo de sondagem padrão para detectar alterações no contêiner.

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 blobTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction	Deve ser definido como in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure. 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 contêiner para monitorar. Pode ser um padrão de nome de 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.
source	Define a origem do evento de gatilho. Use EventGrid para um gatilho de blob baseado na Grade de Eventos, que oferece uma latência muito menor. O padrão é LogsAndContainerScan, que usa o mecanismo de sondagem padrão para detectar alterações no contêiner.

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

Metadados

O gatilho de blob fornece várias propriedades de metadados. Essas propriedades podem ser usadas como parte de expressões de associação em outras associações ou como parâmetros em seu código. Esses valores têm a mesma semântica do tipo CloudBlob.

Propriedade	Type	Descrição
BlobTrigger	string	O caminho do blob de gatilho.
Uri	System.Uri	A URI do blob para o local principal.
Properties	BlobProperties	As propriedades do sistema do blob.
Metadata	IDictionary<string,string>	Os metadados definidos pelo usuário para o blob.

O exemplo a seguir registra o caminho para o blob de gatilho, incluindo o contêiner:

public static void Run(string myBlob, string blobTrigger, ILogger log)
{
    log.LogInformation($"Full blob path: {blobTrigger}");
} 

Metadados

O gatilho de blob fornece várias propriedades de metadados. Essas propriedades podem ser usadas como parte de expressões de associação em outras associações ou como parâmetros em seu código.

Propriedade	Descrição
blobTrigger	O caminho do blob de gatilho.
uri	A URI do blob para o local principal.
properties	As propriedades do sistema do blob.
metadata	Os metadados definidos pelo usuário para o blob.

Modelo v4

Os metadados podem ser obtidos na propriedade triggerMetadata do objeto context fornecido, conforme mostrado no seguinte exemplo, que registra o caminho para o blob de gatilho (blobTrigger), incluindo o contêiner:

context.log(`Full blob path: ${context.triggerMetadata.blobTrigger}`);

Modelo v3

Os metadados podem ser obtidos na propriedade bindingData do objeto context fornecido, conforme mostrado no seguinte exemplo, que registra o caminho para o blob de gatilho (blobTrigger), incluindo o contêiner:

module.exports = async function (context, myBlob) {
    context.log("Full blob path:", context.bindingData.blobTrigger);
};

Metadados

Os metadados estão disponíveis por meio do parâmetro $TriggerMetadata.

Uso

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

Modelo de trabalho isolado

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.

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

Modelo em processo

Consulte Tipos de associação para obter uma lista dos tipos compatíveis.

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 @BlobTrigger é usado para dar acesso ao blob que disparou a função. Confira o exemplo de gatilho para obter detalhes.

Modelo v4

Acesse os dados de blob como o primeiro argumento para sua função.

Modelo v3

Acesse dados de blob usando context.bindings.<NAME>, em que <NAME> corresponde ao valor definido em context.bindings.<NAME>.

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. Confira o exemplo de gatilho para obter 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:

• O nome da configuração de um aplicativo contendo uma cadeia de conexão
• O nome de um prefixo compartilhado com várias configurações de aplicativo, definindo juntas uma conexão baseada em identidade.

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

¹<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

² 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

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

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

Padrões de nome de blob

Você pode especificar um padrão de nome de blob na path propriedade em path ou no BlobTrigger construtor de atributo. O nome padrão pode ser uma expressão de associação ou filtro. As seções a seguir fornecem exemplos.

Dica

Um nome de contêiner não pode conter um resolvedor no padrão de nome.

Obtenha o nome de arquivo e extensão

O exemplo a seguir mostra como associar ao nome do arquivo de blob e extensão separadamente:

"path": "input/{blobname}.{blobextension}",

Se um blob é nomeado original-Blob1.txt o valor das variáveis blobname e blobextension no código de função é original-Blob1 e txt.

Filtre por nome de blob

O exemplo a seguir gatilha apenas em blobs no input contêiner que iniciam com a cadeia de caracteres "original-":

"path": "input/original-{name}",

Se o nome do blob for original-Blob1.txt, o valor da name variável no código da função é Blob1.txt.

Filtre por tipo de arquivo

O exemplo a seguir é disparado apenas em arquivos .png:

"path": "samples/{name}.png",

Filtre em chaves em nomes de arquivos

Para procurar as chaves em nomes de arquivos, escape as chaves usando duas chaves. O exemplo a seguir filtra por blobs que têm chaves no nome:

"path": "images/{{20140101}}-{name}",

Se o blob é nomeado {20140101}soundfile.mp3, o valor da variável name no código da função é soundfile.mp3.

Sondagem e latência

A sondagem funciona como um híbrido entre a inspeção de logs e a execução de verificações de contêiner periódicas. Os blobs são examinados em grupos de 10 mil por vez, com um token de continuação usado entre intervalos. Se seu aplicativo de funções está no plano de Consumo, pode haver um atraso de até 10 minutos no processamento de novos blobs se um aplicativo de funções ficar ocioso.

Aviso

Os logs de armazenamento são criados da "melhor maneira possível". Não há nenhuma garantia de que todos os eventos são capturados. Sob algumas condições, logs poderão ser perdidos.

Se você precisar de um processamento de blob mais rápido ou mais confiável, considere mudar sua hospedagem para usar um plano do Serviço de Aplicativo com o Always On habilitado, o que pode resultar em custos maiores. Você também pode considerar o uso de um gatilho diferente do gatilho de blob de sondagem clássico. Para obter mais informações e uma comparação das várias opções de disparo para contêineres de armazenamento de blob, consulte Gatilho em um contêiner de blob.

Recebimentos de blob

O Azure Functions runtime garante que nenhuma função de gatilho de blob seja chamada mais de uma vez para o mesmo blob novo ou atualizado. Para determinar se uma versão de determinado blob foi processada, ele mantém os recebimentos de blob.

O Azure Functions armazena recibos do blob em um contêiner denominado azure-webjobs-hosts na conta de armazenamento do Azure do seu aplicativo de funções (definido na configuração do aplicativo AzureWebJobsStorage). Um recebimento de blob tem as seguintes informações:

• A função disparada (<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>, por exemplo: MyFunctionApp.Functions.CopyBlob)
• O nome do contêiner
• O tipo de blob (BlockBlob ou PageBlob)
• O nome do blob
• O ETag (um identificador de versão de blob, por exemplo: 0x8D1DC6E70A277EF)

Para forçar o reprocessamento de um blob, exclua manualmente o recebimento desse blob do contêiner azure-webjobs-hosts. Embora o reprocessamento possa não ocorrer imediatamente, é garantido que ele ocorra mais tarde. Para reprocessar imediatamente, o blob scaninfo no azure-webjobs-hosts/blobscaninfo pode ser atualizado. Todos os blobs com um carimbo de data/hora da última modificação após da propriedade LatestScan serão verificados novamente.

Blobs suspeitos

Quando uma função de gatilho de blob falhar para um determinado blob, o Azure Functions repete essa função até cinco vezes por padrão.

Se todas as cinco tentativas falharem, o Azure Functions adiciona uma mensagem para uma fila de armazenamento denominada webjobs-blobtrigger-poison. O número máximo de novas tentativas é configurável. A mesma MaxDequeueCount é usada para manipular blob suspeitos e manipular mensagens de filas suspeitas. A mensagem da fila para blobs suspeitos é um objeto JSON que contém as seguintes propriedades:

• FunctionID (no formato <FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>)
• BlobType (BlockBlob ou PageBlob)
• ContainerName
• BlobName
• ETag (um identificador de versão de blob, por exemplo: 0x8D1DC6E70A277EF)

Uso de memória e simultaneidade

Quando você se associa a um tipo de saída que não oferece suporte ao vapor, como string, ou Byte[], o tempo de execução deve carregar o blob inteiro na memória mais de uma vez durante o processamento. Isso pode resultar em um uso de memória maior do que o esperado ao processar blobs. Quando possível, use um tipo de suporte a fluxo. O suporte ao tipo depende do modo C# e da versão da extensão. Para obter mais informações, confira Tipos de associação.

Neste momento, o tempo de execução deve carregar o blob inteiro na memória mais de uma vez durante o processamento. Isso pode resultar em um uso de memória maior do que o esperado ao processar blobs.

O uso de memória pode ser ainda mais afetado quando várias instâncias de função estão processando simultaneamente dados de blob. Se você estiver tendo problemas de memória usando um gatilho de Blob, considere reduzir o número de execuções simultâneas permitidas. É claro que reduzir a simultaneidade pode ter o efeito colateral de aumentar a lista de pendências de blobs esperando para serem processados. Os limites de memória do seu aplicativo de função dependem do plano. Para saber mais, confira Limites do serviço.

A maneira como você pode controlar o número de execuções simultâneas depende da versão da extensão de armazenamento que você está usando.

Extensão 5.x e posteriores

Ao usar a versão 5.0.0 da extensão de armazenamento ou uma versão posterior, você controla a simultaneidade de gatilho usando a maxDegreeOfParallelismconfiguração na configuração de blobs no host.json.

Pré-extensão 5.x

Como o gatilho de blob usa uma fila internamente, o número máximo de chamadas de função simultâneas é controlado pela configuração de filas em host.json.

Os limites se aplicam separadamente a cada função que usa um gatilho de blob.

Propriedades de host.json

O arquivo host.json contém configurações que controlam o comportamento de gatilho de blob. Confira a seção Configurações de host.json para obter detalhes em relação às configurações disponíveis.

Próximas etapas

• Ler dados do armazenamento de blob quando uma função é executada
• Gravar dados de armazenamento de blob de uma função