title	description	author	ms.topic	ms.date	ms.author	ms.custom
Azure Blob storage trigger for Azure Functions	Learn how to run an Azure Function as Azure Blob storage data changes.	craigshoemaker	reference	02/13/2020	cshoe	tracking-python

Azure Blob storage trigger for Azure Functions

The Blob storage trigger starts a function when a new or updated blob is detected. The blob contents are provided as input to the function.

The Azure Blob storage trigger requires a general-purpose storage account. Storage V2 accounts with hierarchal namespaces are also supported. To use a blob-only account, or if your application has specialized needs, review the alternatives to using this trigger.

For information on setup and configuration details, see the overview.

Alternatives

Event Grid trigger

The Event Grid trigger also has built-in support for blob events. Use Event Grid instead of the Blob storage trigger for the following scenarios:

Blob-only storage accounts: Blob-only storage accounts are supported for blob input and output bindings but not for blob triggers.
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.
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. To avoid this latency, you can switch to an App Service plan with Always On enabled. You can also use an Event Grid trigger with your Blob storage account. For an example, see the Event Grid tutorial.

See the Image resize with Event Grid tutorial of an Event Grid example.

Queue storage trigger

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.

Example

C#

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

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. For more information, see Blob name patterns later in this article.

For more information about the BlobTrigger attribute, see attributes and annotations.

C# Script

The following example shows a blob trigger binding in a function.json file and code that uses the binding. The function writes a log when a blob is added or updated in the samples-workitems container.

Here's the binding data in the function.json file:

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

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. For more information, see Blob name patterns later in this article.

For more information about function.json file properties, see the Configuration section explains these properties.

Here's C# script code that binds to a Stream:

public static void Run(Stream myBlob, string name, ILogger log)
{
   log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name} \n Size: {myBlob.Length} Bytes");
}

Here's C# script code that binds to a CloudBlockBlob:

#r "Microsoft.WindowsAzure.Storage"

using Microsoft.WindowsAzure.Storage.Blob;

public static void Run(CloudBlockBlob myBlob, string name, ILogger log)
{
    log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name}\nURI:{myBlob.StorageUri}");
}

JavaScript

The following example shows a blob trigger binding in a function.json file and JavaScript code that uses the binding. The function writes a log when a blob is added or updated in the samples-workitems container.

Here's the function.json file:

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

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. For more information, see Blob name patterns later in this article.

For more information about function.json file properties, see the Configuration section explains these properties.

Here's the JavaScript code:

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

Python

The following example shows a blob trigger binding in a function.json file and Python code that uses the binding. The function writes a log when a blob is added or updated in the samples-workitems container.

Here's the function.json file:

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

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. For more information, see Blob name patterns later in this article.

For more information about function.json file properties, see the Configuration section explains these properties.

Here's the Python code:

import logging
import azure.functions as func


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

Java

This function writes a log when a blob is added or updated in the myblob container.

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

Attributes and annotations

C#

In C# class libraries, use the following attributes to configure a blob trigger:

BlobTriggerAttribute

The attribute's constructor takes a path string that indicates the container to watch and optionally a blob name pattern. 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)
{
    ....
}

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)
{
   ....
}

For a complete example, see Trigger example.

StorageAccountAttribute

Provides another way to specify the storage account to use. The constructor takes the name of an app setting that contains a storage connection string. The attribute can be applied at the parameter, method, or class level. The following example shows class level and method level:
```
[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("BlobTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ....
}
```

The storage account to use is determined in the following order:

The BlobTrigger attribute's Connection property.
The StorageAccount attribute applied to the same parameter as the BlobTrigger attribute.
The StorageAccount attribute applied to the function.
The StorageAccount attribute applied to the class.
The default storage account for the function app ("AzureWebJobsStorage" app setting).

C# Script

Attributes are not supported by C# Script.

JavaScript

Attributes are not supported by JavaScript.

Python

Attributes are not supported by Python.

Java

The @BlobTrigger attribute is used to give you access to the blob that triggered the function. Refer to the trigger example for details.

Configuration

The following table explains the binding configuration properties that you set in the function.json file and the BlobTrigger attribute.

function.json property	Attribute property	Description
type	n/a	Must be set to `blobTrigger`. This property is set automatically when you create the trigger in the Azure portal.
direction	n/a	Must be set to `in`. This property is set automatically when you create the trigger in the Azure portal. Exceptions are noted in the usage section.
name	n/a	The name of the variable that represents the blob in function code.
path	BlobPath	The container to monitor. May be a blob name pattern.
connection	Connection	The name of an app setting that contains the Storage connection string to use for this binding. If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. For example, if you set `connection` to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." If you leave `connection` empty, the Functions runtime uses the default Storage connection string in the app setting that is named `AzureWebJobsStorage`. The connection string must be for a general-purpose storage account, not a Blob storage account.

[!INCLUDE app settings to local.settings.json]

Usage

C#

[!INCLUDE functions-bindings-blob-storage-trigger]

C# Script

[!INCLUDE functions-bindings-blob-storage-trigger]

JavaScript

Access blob data using context.bindings.<NAME> where <NAME> matches the value defined in function.json.

Python

Access blob data via the parameter typed as InputStream. Refer to the trigger example for details.

Java

The @BlobTrigger attribute is used to give you access to the blob that triggered the function. Refer to the trigger example for details.

Blob name patterns

You can specify a blob name pattern in the path property in function.json or in the BlobTrigger attribute constructor. The name pattern can be a filter or binding expression. The following sections provide examples.

Get file name and extension

The following example shows how to bind to the blob file name and extension separately:

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

If the blob is named original-Blob1.txt, the values of the blobname and blobextension variables in function code are original-Blob1 and txt.

Filter on blob name

The following example triggers only on blobs in the input container that start with the string "original-":

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

If the blob name is original-Blob1.txt, the value of the name variable in function code is Blob1.

Filter on file type

The following example triggers only on .png files:

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

Filter on curly braces in file names

To look for curly braces in file names, escape the braces by using two braces. The following example filters for blobs that have curly braces in the name:

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

If the blob is named {20140101}-soundfile.mp3, the name variable value in the function code is soundfile.mp3.

Metadata

C#

[!INCLUDE functions-bindings-blob-storage-trigger]

C# Script

[!INCLUDE functions-bindings-blob-storage-trigger]

JavaScript

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

Python

Metadata is not available in Python.

Java

Metadata is not available in Java.

Blob receipts

The Azure Functions runtime ensures that no blob trigger function gets called more than once for the same new or updated blob. To determine if a given blob version has been processed, it maintains blob receipts.

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). A blob receipt has the following information:

The triggered function ("<function app name>.Functions.<function name>", for example: "MyFunctionApp.Functions.CopyBlob")
The container name
The blob type ("BlockBlob" or "PageBlob")
The blob name
The ETag (a blob version identifier, for example: "0x8D1DC6E70A277EF")

To force reprocessing of a blob, delete the blob receipt for that blob from the azure-webjobs-hosts container manually. While reprocessing might not occur immediately, it's guaranteed to occur at a later point in time. To reprocess immediately, the scaninfo blob in azure-webjobs-hosts/blobscaninfo can be updated. Any blobs with a last modified timestamp after the LatestScan property will be scanned again.

Poison blobs

When a blob trigger function fails for a given blob, Azure Functions retries that function a total of 5 times by default.

If all 5 tries fail, Azure Functions adds a message to a Storage queue named webjobs-blobtrigger-poison. The maximum number of retries is configurable. The same MaxDequeueCount setting is used for poison blob handling and poison queue message handling. The queue message for poison blobs is a JSON object that contains the following properties:

FunctionId (in the format <function app name>.Functions.<function name>)
BlobType ("BlockBlob" or "PageBlob")
ContainerName
BlobName
ETag (a blob version identifier, for example: "0x8D1DC6E70A277EF")

Concurrency and memory usage

The blob trigger uses a queue internally, so the maximum number of concurrent function invocations is controlled by the queues configuration in host.json. The default settings limit concurrency to 24 invocations. This limit applies separately to each function that uses a blob trigger.

The Consumption plan limits a function app on one virtual machine (VM) to 1.5 GB of memory. Memory is used by each concurrently executing function instance and by the Functions runtime itself. 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. 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.

JavaScript and Java functions load the entire blob into memory, and C# functions do that if you bind to string, Byte[], or POCO.

Polling

Polling works as a hybrid between inspecting logs and running periodic container scans. Blobs are scanned in groups of 10,000 at a time with a continuation token used between intervals.

Warning

In addition, storage logs are created on a "best effort" basis. There's no guarantee that all events are captured. Under some conditions, logs may be missed.

If you require faster or more reliable blob processing, consider creating a queue message when you create the blob. Then use a queue trigger instead of a blob trigger to process the blob. Another option is to use Event Grid; see the tutorial Automate resizing uploaded images using Event Grid.

Next steps

Read blob storage data when a function runs
Write blob storage data from a function

Files

functions-bindings-storage-blob-trigger.md

Latest commit

History

functions-bindings-storage-blob-trigger.md

File metadata and controls

Azure Blob storage trigger for Azure Functions

Alternatives

Event Grid trigger

Queue storage trigger

Example

Attributes and annotations

Configuration

Usage

Blob name patterns

Get file name and extension

Filter on blob name

Filter on file type

Filter on curly braces in file names

Metadata

Blob receipts

Poison blobs

Concurrency and memory usage

Polling

Next steps