Gatilho de armazenamento de Blob do Azure para o Azure Functions

O gatilho de armazenamento de Blob inicia uma função quando um blob novo ou atualizado é detetado. 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 Blob, bem como outras opções de acionamento, consulte Trabalhando com blobs.

Para obter informações sobre detalhes de instalação e configuração, consulte 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 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);
};

Utilização

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

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:

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

2 O gatilho de blob lida com falhas em várias tentativas gravando blobs venenosos em uma fila. No formulário, a serviceUri AzureWebJobsStorage 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.

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.

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.

Padrões de nome de blob

Você pode especificar um padrão de nome de path blob na propriedade em function.json ou no construtor de atributo BlobTrigger . O padrão de nome pode ser um filtro ou uma expressão de ligação. As seguintes secções fornecem exemplos.

Obter nome de arquivo e extensão

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

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

Se o blob for nomeado original-Blob1.txt, os blobname valores das variáveis e blobextension no código da função serão original-Blob1 e txt.

Filtrar no nome do blob

O exemplo a seguir é acionado somente em blobs no input contêiner que começam com a cadeia de caracteres "original-":

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

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

Filtrar por tipo de ficheiro

O exemplo a seguir é acionado somente em arquivos .png :

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

Filtrar chaves em nomes de arquivo

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

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

Se o blob for nomeado {20140101}-soundfile.mp3, o valor da name variável no código da função será 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 periódicas de contêineres. Os blobs são verificados em grupos de 10.000 de cada vez com um token de continuação usado entre intervalos. Se seu aplicativo de função estiver no plano de consumo, pode haver um atraso de até 10 minutos no processamento de novos blobs se um aplicativo de função estiver 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 o Always On ativado, o que pode resultar em custos maiores. Você também pode considerar o uso de um gatilho diferente do clássico gatilho de blob de sondagem. Para obter mais informações e uma comparação das várias opções de acionamento para contêineres de armazenamento de blob, consulte Gatilho em um contêiner de blob.

Recibos de Blob

O tempo de execução do Azure Functions 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 determinada versão de blob foi processada, ele mantém recibos de blob.

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

• A função acionada (<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 recibo de blob desse blob do contêiner azure-webjobs-hosts . Embora o reprocessamento possa não ocorrer imediatamente, é garantido que ocorrerá em um momento posterior. Para reprocessar imediatamente, o blob scaninfo em azure-webjobs-hosts/blobscaninfo pode ser atualizado. Todos os blobs com um carimbo de data/hora modificado pela última vez após a LatestScan propriedade serão verificados novamente.

Bolhas venenosas

Quando uma função de gatilho de blob falha para um determinado blob, o Azure Functions tenta novamente essa função um total de cinco vezes por padrão.

Se todas as 5 tentativas falharem, o Azure Functions adicionará uma mensagem a uma fila de armazenamento chamada webjobs-blobtrigger-poison. O número máximo de novas tentativas é configurável. A mesma configuração MaxDequeueCount é usada para manipulação de blob venenoso e manipulação de mensagens de fila de veneno. A mensagem de fila para blobs temporários é 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 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 o acúmulo de blobs esperando para serem processados. Os limites de memória do seu aplicativo de função dependem do plano. Para obter mais informações, consulte Limites de 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 aplicam-se separadamente a cada função que usa um gatilho de blob.

host.json propriedades

O arquivo host.json contém configurações que controlam o comportamento do gatilho de blob. Consulte a seção Configurações de host.json para obter detalhes sobre as configurações disponíveis.

Próximos passos

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