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.

Para obter detalhes sobre as diferenças entre as duas implementações do gatilho de armazenamento de blobs, bem como outras opções de gatilho, consulte Trabalhando com blobs.

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

Exemplo

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

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

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

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,
});

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`
        );
    },
});

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

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

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

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

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

import logging

import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
@app.blob_trigger(
    arg_name="client", path="PATH/TO/BLOB", connection="AzureWebJobsStorage"
)
def blob_trigger(client: blob.BlobClient):
    logging.info(
        f"Python blob trigger function processed blob \n"
        f"Properties: {client.get_blob_properties()}\n"
        f"Blob content head: {client.download_blob().read(size=1)}"
    )

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

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

import logging
import azure.functions as func


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

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

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

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

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

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

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

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

Uso

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

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:

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

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

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.

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

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.

Se você precisar de um processamento de blob mais rápido ou confiável, considere mudar sua hospedagem para usar um plano do Serviço de Aplicativo com 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 gatilho para contêineres de armazenamento de blobs, 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

O uso de memória pode ser afetado ainda mais quando várias instâncias de função estão processando dados de blob simultaneamente. 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 aguardando para serem processados. Os limites de memória do aplicativo de funções 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.

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