Gatilho de armazenamento Azure Blob para funções azureAzure Blob storage trigger for Azure Functions

O gatilho de armazenamento Blob inicia uma função quando é detetada uma bolha nova ou atualizada.The Blob storage trigger starts a function when a new or updated blob is detected. O conteúdo da bolha é fornecido como entrada para a função.The blob contents are provided as input to the function.

O gatilho de armazenamento Azure Blob requer uma conta de armazenamento de uso geral.The Azure Blob storage trigger require a general-purpose storage account. Para utilizar uma conta só para blob, ou se a sua aplicação tiver necessidades especializadas, reveja as alternativas à utilização deste gatilho.To use a blob-only account, or if your application has specialized needs, review the alternatives to using this trigger.

Para obter informações sobre os detalhes da configuração e configuração, consulte a visão geral.For information on setup and configuration details, see the overview.

AlternativasAlternatives

Gatilho da Grelha de EventosEvent Grid trigger

O gatilho da Grelha de Eventos também tem suporte incorporado para eventos de blob.The Event Grid trigger also has built-in support for blob events. Utilize a Grelha de Eventos em vez do gatilho de armazenamento Blob para os seguintes cenários:Use Event Grid instead of the Blob storage trigger for the following scenarios:

  • Contas de armazenamento apenaspara blob : As contas de armazenamento apenas blob são suportadas para encadernações de entrada e saída blob, mas não para gatilhos blob.Blob-only storage accounts: Blob-only storage accounts are supported for blob input and output bindings but not for blob triggers.

  • Alta escala: A alta escala pode ser vagamente definida como recipientes que têm mais de 100.000 blobs ou contas de armazenamento que têm mais de 100 atualizações blob por segundo.High-scale: High scale can be loosely defined as containers that have more than 100,000 blobs in them or storage accounts that have more than 100 blob updates per second.

  • Minimizar a latência: Se a sua aplicação de funções estiver no plano de consumo, pode haver até 10 minutos de atraso no processamento de novas bolhas se uma aplicação de função tiver ficado inativa.Minimizing latency: If your function app is on the Consumption plan, there can be up to a 10-minute delay in processing new blobs if a function app has gone idle. Para evitar esta latência, pode mudar para um plano de Serviço de Aplicações com ativado Always On.To avoid this latency, you can switch to an App Service plan with Always On enabled. Também pode utilizar um gatilho da Grelha de Eventos com a sua conta de armazenamento Blob.You can also use an Event Grid trigger with your Blob storage account. Por exemplo, consulte o tutorial da Grelha de Eventos.For an example, see the Event Grid tutorial.

Consulte o redimensionado da Imagem com tutorial da Grelha de Eventos de um exemplo da Grelha de Eventos.See the Image resize with Event Grid tutorial of an Event Grid example.

Acionador do armazenamento de filasQueue storage trigger

Outra abordagem para processar bolhas é escrever mensagens de fila que correspondam a bolhas que são criadas ou modificadas e, em seguida, usar um gatilho de armazenamento de fila para começar a processar.Another approach to processing blobs is to write queue messages that correspond to blobs being created or modified and then use a Queue storage trigger to begin processing.

ExemploExample

O exemplo seguinte mostra uma função C# que escreve um tronco samples-workitems quando uma bolha é adicionada ou atualizada no recipiente.The following example shows a C# function that writes a log when a blob is added or updated in the samples-workitems container.

[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 {name} cadeia no caminho samples-workitems/{name} do gatilho da bolha cria uma expressão de ligação que pode usar no código de função para aceder ao nome de ficheiro da bolha de desencadeamento.The string {name} in the blob trigger path samples-workitems/{name} creates a binding expression that you can use in function code to access the file name of the triggering blob. Para mais informações, consulte os padrões de nome Blob mais tarde neste artigo.For more information, see Blob name patterns later in this article.

Para obter mais BlobTrigger informações sobre o atributo, consulte atributos e anotações.For more information about the BlobTrigger attribute, see attributes and annotations.

Atributos e anotaçõesAttributes and annotations

Nas bibliotecas da classe C#,utilize os seguintes atributos para configurar um gatilho de bolha:In C# class libraries, use the following attributes to configure a blob trigger:

  • BlobTriggerAttributeBlobTriggerAttribute

    O construtor do atributo pega numa corda de caminho que indica o recipiente para observar e opcionalmente um padrão de nome blob.The attribute's constructor takes a path string that indicates the container to watch and optionally a blob name pattern. Segue-se um exemplo:Here's an example:

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

    Pode definir Connection a propriedade para especificar a conta de armazenamento a utilizar, como mostra o seguinte exemplo:You can set the Connection property to specify the storage account to use, as shown in the following example:

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

    Para um exemplo completo, consulte o exemplo do Gatilho.For a complete example, see Trigger example.

  • ArmazenamentoAccountAttributeStorageAccountAttribute

    Fornece outra forma de especificar a conta de armazenamento a utilizar.Provides another way to specify the storage account to use. O construtor tem o nome de uma definição de aplicação que contém uma cadeia de ligação de armazenamento.The constructor takes the name of an app setting that contains a storage connection string. O atributo pode ser aplicado no parâmetro, método ou nível de classe.The attribute can be applied at the parameter, method, or class level. O exemplo que se segue mostra o nível de classe e o nível de método:The following example shows class level and method level:

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

A conta de armazenamento a utilizar é determinada na seguinte ordem:The storage account to use is determined in the following order:

  • A BlobTrigger propriedade do Connection atributo.The BlobTrigger attribute's Connection property.
  • O StorageAccount atributo aplicado ao mesmo BlobTrigger parâmetro que o atributo.The StorageAccount attribute applied to the same parameter as the BlobTrigger attribute.
  • O StorageAccount atributo aplicado à função.The StorageAccount attribute applied to the function.
  • O StorageAccount atributo aplicado à classe.The StorageAccount attribute applied to the class.
  • A conta de armazenamento padrão para a aplicação de função (definição de aplicação "AzureWebJobsStorage").The default storage account for the function app ("AzureWebJobsStorage" app setting).

ConfiguraçãoConfiguration

A tabela a seguir explica as propriedades de configuração de ligação que definiu no ficheiro função.json e no BlobTrigger atributo.The following table explains the binding configuration properties that you set in the function.json file and the BlobTrigger attribute.

propriedade fun.jsonfunction.json property Propriedade de atributoAttribute property DescriçãoDescription
tipotype n/dn/a Tem de blobTriggerser definido para.Must be set to blobTrigger. Esta propriedade é definida automaticamente quando cria o gatilho no portal Azure.This property is set automatically when you create the trigger in the Azure portal.
direçãodirection n/dn/a Tem de inser definido para.Must be set to in. Esta propriedade é definida automaticamente quando cria o gatilho no portal Azure.This property is set automatically when you create the trigger in the Azure portal. As exceções são observadas na secção de utilização.Exceptions are noted in the usage section.
nomename n/dn/a O nome da variável que representa a bolha no código de função.The name of the variable that represents the blob in function code.
caminhopath BlobPathBlobPath O recipiente para monitorizar.The container to monitor. Pode ser um padrão de nome blob.May be a blob name pattern.
conexãoconnection ConexãoConnection O nome de uma definição de aplicação que contém a cadeia de ligação de armazenamento a utilizar para esta ligação.The name of an app setting that contains the Storage connection string to use for this binding. Se o nome de definição da aplicação começar com "AzureWebJobs", pode especificar apenas o restante do nome aqui.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. Por exemplo, se connection definir para "MyStorage", o tempo de execução das Funções procura uma definição de aplicação que se chama "AzureWebJobsMyStorage".For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." Se deixar connection vazio, o tempo de funcionamento das funções utiliza AzureWebJobsStoragea cadeia de ligação de armazenamento predefinida na definição da aplicação que é denominada .If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

A cadeia de ligação deve ser para uma conta de armazenamento geral, não para uma conta de armazenamento Blob.The connection string must be for a general-purpose storage account, not a Blob storage account.

Quando está a desenvolver-se localmente, as definições de aplicativos vão para o ficheiro local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

UtilizaçãoUsage

Pode utilizar os seguintes tipos de parâmetros para a bolha de desencadeamento:You can use the following parameter types for the triggering blob:

  • Stream
  • TextReader
  • string
  • Byte[]
  • Um POCO serializável como JSONA POCO serializable as JSON
  • ICloudBlob1ICloudBlob1
  • CloudBlockBlob1CloudBlockBlob1
  • CloudPageBlob1CloudPageBlob1
  • CloudAppendBlob1CloudAppendBlob1

1 Requer encadernação direction "inout" em FileAccess.ReadWrite função.json ou numa biblioteca da classe C#.1 Requires "inout" binding direction in function.json or FileAccess.ReadWrite in a C# class library.

Se tentar ligar-se a um dos tipos de SDK de armazenamento e obter uma mensagem de erro, certifique-se de que tem uma referência à versão SDK de armazenamento correta.If you try to bind to one of the Storage SDK types and get an error message, make sure that you have a reference to the correct Storage SDK version.

A stringligação a , Byte[]ou POCO só é recomendada se o tamanho da bolha for pequeno, uma vez que todo o conteúdo blob é carregado na memória.Binding to string, Byte[], or POCO is only recommended if the blob size is small, as the entire blob contents are loaded into memory. Geralmente, é preferível utilizar Stream CloudBlockBlob um ou tipo.Generally, it is preferable to use a Stream or CloudBlockBlob type. Para mais informações, consulte a Concurrency e o uso da memória mais tarde neste artigo.For more information, see Concurrency and memory usage later in this article.

Padrões de nome blobBlob name patterns

Pode especificar um padrão de path nome blob na propriedade em BlobTrigger função.json ou no construtor de atributos.You can specify a blob name pattern in the path property in function.json or in the BlobTrigger attribute constructor. O padrão de nome pode ser um filtro ou expressão de encadernação.The name pattern can be a filter or binding expression. As seguintes secções fornecem exemplos.The following sections provide examples.

Obtenha o nome do ficheiro e a extensãoGet file name and extension

O exemplo que se segue mostra como se ligar ao nome do ficheiro blob e à extensão separadamente:The following example shows how to bind to the blob file name and extension separately:

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

Se a bolha for denominada original-Blob1.txt, os valores blobname do código de função e variáveis blobextension são originais-Blob1 e txt.If the blob is named original-Blob1.txt, the values of the blobname and blobextension variables in function code are original-Blob1 and txt.

Filtro no nome blobFilter on blob name

O exemplo seguinte dispara apenas em input bolhas no recipiente que começam com a corda "original":The following example triggers only on blobs in the input container that start with the string "original-":

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

Se o nome blob for original-Blob1.txt, o valor da name variável no código de função é Blob1.If the blob name is original-Blob1.txt, the value of the name variable in function code is Blob1.

Filtro no tipo de ficheiroFilter on file type

O exemplo seguinte dispara apenas em ficheiros .png:The following example triggers only on .png files:

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

Filtrar em aparelhos encaracolados em nomes de ficheirosFilter on curly braces in file names

Para procurar aparelhos encaracolados em nomes de ficheiros, escape do aparelho utilizando dois aparelhos.To look for curly braces in file names, escape the braces by using two braces. Os filtros de exemplo seguintes para bolhas que tenham aparelhos encaracolados no nome:The following example filters for blobs that have curly braces in the name:

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

Se a bolha for denominada name * {20140101}-soundfile.mp3,* o valor variável no código de função é soundfile.mp3.If the blob is named {20140101}-soundfile.mp3, the name variable value in the function code is soundfile.mp3.

MetadadosMetadata

O gatilho blob fornece várias propriedades de metadados.The blob trigger provides several metadata properties. Estas propriedades podem ser usadas como parte de expressões de ligação noutras encadernações ou como parâmetros no seu código.These properties can be used as part of binding expressions in other bindings or as parameters in your code. Estes valores têm a mesma semântica que o tipo CloudBlob.These values have the same semantics as the CloudBlob type.

PropriedadeProperty TipoType DescriçãoDescription
BlobTrigger string O caminho para a bolha de desencadeamento.The path to the triggering blob.
Uri System.Uri O URI da bolha para a localização primária.The blob's URI for the primary location.
Properties BlobPropertiesBlobProperties As propriedades do sistema da bolha.The blob's system properties.
Metadata IDictionary<string,string> Os metadados definidos pelo utilizador para a bolha.The user-defined metadata for the blob.

Por exemplo, os exemplos de script C# e JavaScript slog e JavaScript registam o caminho para a bolha de desencadeamento, incluindo o recipiente:For example, the following C# script and JavaScript examples log the path to the triggering blob, including the container:

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

Recibos blobBlob receipts

O tempo de funcionamento das Funções Azure garante que nenhuma função de gatilho blob é chamada mais de uma vez para a mesma bolha nova ou atualizada.The Azure Functions runtime ensures that no blob trigger function gets called more than once for the same new or updated blob. Para determinar se uma determinada versão blob foi processada, mantém recibos blob.To determine if a given blob version has been processed, it maintains blob receipts.

A Azure Functions armazena recibos blob num contentor chamado azure-webjobs-hosts na conta AzureWebJobsStoragede armazenamento Azure para a sua aplicação de funções (definida pela definição da aplicação).Azure Functions stores blob receipts in a container named azure-webjobs-hosts in the Azure storage account for your function app (defined by the app setting AzureWebJobsStorage). Um recibo blob tem as seguintes informações:A blob receipt has the following information:

  • A função desencadeada*< *(" nome da aplicação de função>. Funções. *nome de função>", por exemplo: "MyFunctionApp.Functions.CopyBlob") < *The triggered function ("<function app name>.Functions.<function name>", for example: "MyFunctionApp.Functions.CopyBlob")
  • O nome do recipienteThe container name
  • O tipo de bolha ("BlockBlob" ou "PageBlob")The blob type ("BlockBlob" or "PageBlob")
  • O nome blobThe blob name
  • O ETag (um identificador de versão blob, por exemplo: "0x8D1DC6E70A277EF")The ETag (a blob version identifier, for example: "0x8D1DC6E70A277EF")

Para forçar o reprocessamento de uma bolha, elimine manualmente o recibo de bolha desse recipiente de anfitriões de azure-webjobs.To force reprocessing of a blob, delete the blob receipt for that blob from the azure-webjobs-hosts container manually. Embora o reprocessamento possa não ocorrer imediatamente, é garantido que ocorra em um ponto posterior no tempo.While reprocessing might not occur immediately, it's guaranteed to occur at a later point in time.

Bolhas venenosasPoison blobs

Quando uma função de gatilho blob falha para uma determinada bolha, as funções Azure retestam que funcionam um total de 5 vezes por padrão.When a blob trigger function fails for a given blob, Azure Functions retries that function a total of 5 times by default.

Se todas as 5 tentativas falharem, a Azure Functions adiciona uma mensagem a uma fila de armazenamento chamada webjobs-blobtrigger-poison.If all 5 tries fail, Azure Functions adds a message to a Storage queue named webjobs-blobtrigger-poison. O número máximo de repetições é configurável.The maximum number of retries is configurable. A mesma definição MaxDequeueCount é usada para manuseamento de bolhas venenosas e tratamento de mensagens de fila venenosa.The same MaxDequeueCount setting is used for poison blob handling and poison queue message handling. A mensagem de fila para bolhas venenosas é um objeto JSON que contém as seguintes propriedades:The queue message for poison blobs is a JSON object that contains the following properties:

  • FunçãoId (no nome da * <função *de formato>. Funções. *nome da função>) < *FunctionId (in the format <function app name>.Functions.<function name>)
  • BlobType ("BlockBlob" ou "PageBlob")BlobType ("BlockBlob" or "PageBlob")
  • ContainerNameContainerName
  • BlobNameBlobName
  • ETag (um identificador de versão blob, por exemplo: "0x8D1DC6E70A277EF")ETag (a blob version identifier, for example: "0x8D1DC6E70A277EF")

Utilização de moeda sintetária e de memóriaConcurrency and memory usage

O gatilho de bolha utiliza uma fila internamente, pelo que o número máximo de invocações de função simultânea é controlado pela configuração das filas em host.json.The blob trigger uses a queue internally, so the maximum number of concurrent function invocations is controlled by the queues configuration in host.json. As definições predefinidas limitam a moeda a 24 invocações.The default settings limit concurrency to 24 invocations. Este limite aplica-se separadamente a cada função que utiliza um gatilho de bolha.This limit applies separately to each function that uses a blob trigger.

O plano de consumo limita uma aplicação de função numa máquina virtual (VM) a 1,5 GB de memória.The Consumption plan limits a function app on one virtual machine (VM) to 1.5 GB of memory. A memória é utilizada por cada instância de função de execução simultânea e pelas próprias funções.Memory is used by each concurrently executing function instance and by the Functions runtime itself. Se uma função desencadeada por bolhas carregar toda a bolha na memória, a memória máxima utilizada por essa função apenas para bolhas é de 24 * tamanho máximo de bolha.If a blob-triggered function loads the entire blob into memory, the maximum memory used by that function just for blobs is 24 * maximum blob size. Por exemplo, uma aplicação de função com três funções desencadeadas por bolhas e as definições predefinidas teriam uma conmoeda máxima por VM de 3*24 = 72 invocações de função.For example, a function app with three blob-triggered functions and the default settings would have a maximum per-VM concurrency of 3*24 = 72 function invocations.

As funções JavaScript e Java carregam toda a bolha na memória, string Byte[]e as funções De C# fazem isso se se ligar a , ou POCO.JavaScript and Java functions load the entire blob into memory, and C# functions do that if you bind to string, Byte[], or POCO.

SondagemPolling

As sondagens funcionam como um híbrido entre a inspeção dos registos e a realização de varreduras periódicas de contentores.Polling works as a hybrid between inspecting logs and running periodic container scans. As bolhas são digitalizadas em grupos de 10.000 de cada vez com um token de continuação usado entre intervalos.Blobs are scanned in groups of 10,000 at a time with a continuation token used between intervals.

Aviso

Além disso, os registos de armazenamento são criados numa base de "melhor esforço".In addition, storage logs are created on a "best effort" basis. Não há garantias de que todos os eventos sejam capturados.There's no guarantee that all events are captured. Sob algumas condições, os registos podem ser perdidos.Under some conditions, logs may be missed.

Se necessitar de um processamento de bolha mais rápido ou fiável, considere criar uma mensagem de fila quando criar a bolha.If you require faster or more reliable blob processing, consider creating a queue message when you create the blob. Em seguida, use um gatilho de fila em vez de um gatilho de bolha para processar a bolha.Then use a queue trigger instead of a blob trigger to process the blob. Outra opção é utilizar a Grelha de Eventos; ver o tutorial Automate redimensionando imagens carregadas usando a Grelha de Eventos.Another option is to use Event Grid; see the tutorial Automate resizing uploaded images using Event Grid.

Passos seguintesNext steps