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.

There are several ways to execute your function code based on changes to blobs in a storage container. Use the following table to determine which function trigger best fits your needs:

Blob Storage (standard) Blob Storage (event-based) Queue Storage Event Grid
Latency High (up to 10 min) Low Medium Low
Storage account limitations Blob-only accounts not supported¹ general purpose v1 not supported none general purpose v1 not supported
Extension version Any Storage v5.x+ Any Any
Processes existing blobs Yes No No No
Filters Blob name pattern Event filters n/a Event filters
Requires event subscription No Yes No Yes
Supports high-scale² No Yes Yes Yes
Description Default trigger behavior, which relies on polling the container for updates. For more information, see the examples in this article. Consumes blob storage events from an event subscription. Requires a Source parameter value of EventGrid. For more information, see Tutorial: Trigger Azure Functions on blob containers using an event subscription. Blob name string is manually added to a storage queue when a blob is added to the container. This value is passed directly by a Queue Storage trigger to a Blob Storage input binding on the same function. Provides the flexibility of triggering on events besides those coming from a storage container. Use when need to also have non-storage events trigger your function. For more information, see How to work with Event Grid triggers and bindings in Azure Functions.

1 Blob Storage input and output bindings support blob-only accounts.

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

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

Example

A C# function can be created using one of the following C# modes:

  • In-process class library: compiled C# function that runs in the same process as the Functions runtime.
  • Isolated worker process class library: compiled C# function that runs in a worker process that is isolated from the runtime. Isolated worker process is required to support C# functions running on non-LTS versions .NET and the .NET Framework.
  • C# script: used primarily when creating C# functions in the Azure portal.

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.

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

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 = async function(context) {
    context.log('Node.js Blob trigger function processed', context.bindings.myBlob);
};

The following example demonstrates how to create a function that runs when a file is added to source blob storage container.

The function configuration file (function.json) includes a binding with the type of blobTrigger and direction set to in.

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

Here's the associated code for the run.ps1 file.

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

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

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)

Attributes

Both in-process and isolated worker process C# libraries use the BlobAttribute attribute to define the function. C# script instead uses a function.json configuration file.

The attribute's constructor takes the following parameters:

Parameter Description
BlobPath The path to the blob.
Connection The name of an app setting or setting collection that specifies how to connect to Azure Blobs. See Connections.
Access Indicates whether you will be reading or writing.

In C# class libraries, 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)
{
  ....
}

While the attribute takes a Connection property, you can also use the StorageAccountAttribute to specify a storage account connection. You can do this when you need to use a different storage account than other functions in the library. 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("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

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

  • The trigger or binding attribute's Connection property.
  • The StorageAccount attribute applied to the same parameter as the trigger or binding attribute.
  • The StorageAccount attribute applied to the function.
  • The StorageAccount attribute applied to the class.
  • The default storage account for the function app, which is defined in the AzureWebJobsStorage application setting.

When you're developing locally, add your application settings in the local.settings.json file in the Values collection.

Annotations

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.

function.json property Description
type Must be set to blobTrigger. This property is set automatically when you create the trigger in the Azure portal.
direction 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 The name of the variable that represents the blob in function code.
path The container to monitor. May be a blob name pattern.
connection The name of an app setting or setting collection that specifies how to connect to Azure Blobs. See Connections.

See the Example section for complete examples.

Metadata

The blob trigger provides several metadata properties. These properties can be used as part of binding expressions in other bindings or as parameters in your code. These values have the same semantics as the Cloud​Blob type.

Property Type Description
BlobTrigger string The path to the triggering blob.
Uri System.Uri The blob's URI for the primary location.
Properties BlobProperties The blob's system properties.
Metadata IDictionary<string,string> The user-defined metadata for the blob.

The following example logs 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}");
} 

Metadata

The blob trigger provides several metadata properties. These properties can be used as part of binding expressions in other bindings or as parameters in your code.

Property Description
blobTrigger The path to the triggering blob.
uri The blob's URI for the primary location.
properties The blob's system properties.
metadata The user-defined metadata for the blob.

Metadata can be obtained from the bindingData property of the supplied context object, as shown in the following example, which logs the path to the triggering blob (blobTrigger), including the container:

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

Metadata

Metadata is available through the $TriggerMetadata parameter.

Usage

The usage of the Blob trigger depends on the extension package version, and the C# modality used in your function app, which can be one of the following:

An in-process class library is a compiled C# function runs in the same process as the Functions runtime.

Choose a version to see usage details for the mode and version.

The following parameter types are supported for all versions:

  • Stream
  • TextReader
  • string
  • Byte[]

The following parameter types are extension version-specific and require FileAccess.ReadWrite in your C# class library:

For examples using these types, see the GitHub repository for the extension. Learn more about these new types are different and how to migrate to them from the Azure.Storage.Blobs Migration Guide.

You can also use the StorageAccountAttribute to specify the storage account to use. You can do this when you need to use a different storage account than other functions in the library. 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, which is defined in the AzureWebJobsStorage application setting.

Binding to string, or Byte[] is only recommended when the blob size is small. This is recommended because the entire blob contents are loaded into memory. For most blobs, use a Stream or CloudBlockBlob type. For more information, see Concurrency and memory usage.

If you get an error message when trying to bind to one of the Storage SDK types, make sure that you have a reference to the correct Storage SDK version.

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

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

Access the blob data via a parameter that matches the name designated by binding's name parameter in the function.json file.

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

Connections

The connection property is a reference to environment configuration which specifies how the app should connect to Azure Blobs. It may specify:

If the configured value is both an exact match for a single setting and a prefix match for other settings, the exact match is used.

Connection string

To obtain a connection string, follow the steps shown at Manage storage account access keys. The connection string must be for a general-purpose storage account, not a Blob storage account.

This connection string should be stored in an application setting with a name matching the value specified by the connection property of the binding configuration.

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.

Identity-based connections

If you are using version 5.x or higher of the extension, instead of using a connection string with a secret, you can have the app use an Azure Active Directory identity. To do this, you would define settings under a common prefix which maps to the connection property in the trigger and binding configuration.

If you are setting connection to "AzureWebJobsStorage", see Connecting to host storage with an identity. For all other connections, the extension requires the following properties:

Property Environment variable template Description Example value
Blob Service URI <CONNECTION_NAME_PREFIX>__serviceUri1 The data plane URI of the blob service to which you are connecting, using the HTTPS scheme. https://<storage_account_name>.blob.core.windows.net

1 <CONNECTION_NAME_PREFIX>__blobServiceUri can be used as an alias. If the connection configuration will be used by a blob trigger, blobServiceUri must also be accompanied by queueServiceUri. See below.

The serviceUri form cannot be used when the overall connection configuration is to be used across blobs, queues, and/or tables. The URI itself can only designate the blob service. As an alternative, you can provide a URI specifically for each service, allowing a single connection to be used. If both versions are provided, the multi-service form will be used. To configure the connection for multiple services, instead of <CONNECTION_NAME_PREFIX>__serviceUri, set:

Property Environment variable template Description Example value
Blob Service URI <CONNECTION_NAME_PREFIX>__blobServiceUri The data plane URI of the blob service to which you are connecting, using the HTTPS scheme. https://<storage_account_name>.blob.core.windows.net
Queue Service URI (required for blob triggers2) <CONNECTION_NAME_PREFIX>__queueServiceUri The data plane URI of a queue service, using the HTTPS scheme. This value is only needed for blob triggers. https://<storage_account_name>.queue.core.windows.net

2 The blob trigger handles failure across multiple retries by writing poison blobs to a queue. In the serviceUri form, the AzureWebJobsStorage connection is used. However, when specifying blobServiceUri, a queue service URI must also be provided with queueServiceUri. It is recommended that you use the service from the same storage account as the blob service. You will also need to make sure the trigger can read and write messages in the configured queue service by assigning a role like Storage Queue Data Contributor.

Additional properties may be set to customize the connection. See Common properties for identity-based connections.

When hosted in the Azure Functions service, identity-based connections use a managed identity. The system-assigned identity is used by default, although a user-assigned identity can be specified with the credential and clientID properties. Note that configuring a user-assigned identity with a resource ID is not supported. When run in other contexts, such as local development, your developer identity is used instead, although this can be customized. See Local development with identity-based connections.

Grant permission to the identity

Whatever identity is being used must have permissions to perform the intended actions. For most Azure services, this means you need to assign a role in Azure RBAC, using either built-in or custom roles which provide those permissions.

Important

Some permissions might be exposed by the target service that are not necessary for all contexts. Where possible, adhere to the principle of least privilege, granting the identity only required privileges. For example, if the app only needs to be able to read from a data source, use a role that only has permission to read. It would be inappropriate to assign a role that also allows writing to that service, as this would be excessive permission for a read operation. Similarly, you would want to ensure the role assignment is scoped only over the resources that need to be read.

You will need to create a role assignment that provides access to your blob container at runtime. Management roles like Owner are not sufficient. The following table shows built-in roles that are recommended when using the Blob Storage extension in normal operation. Your application may require additional permissions based on the code you write.

Binding type Example built-in roles
Trigger Storage Blob Data Owner and Storage Queue Data Contributor1

Additional permissions must also be granted to the AzureWebJobsStorage connection.2
Input binding Storage Blob Data Reader
Output binding Storage Blob Data Owner

1 The blob trigger handles failure across multiple retries by writing poison blobs to a queue on the storage account specified by the connection.

2 The AzureWebJobsStorage connection is used internally for blobs and queues that enable the trigger. If it is configured to use an identity-based connection, it will need additional permissions beyond the default requirement. These are covered by the Storage Blob Data Owner, Storage Queue Data Contributor, and Storage Account Contributor roles. To learn more, see Connecting to host storage with an identity.

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.

Tip

A container name can't contain a resolver in the name pattern.

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

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.

Polling and latency

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

Warning

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, you should instead implement one of the following strategies:

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

Note

For apps using the 5.0.0 or higher version of the Storage extension, the queues configuration in host.json only applies to queue triggers. The blob trigger concurrency is instead controlled by blobs configuration in host.json.

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, or Byte[].

host.json properties

The host.json file contains settings that control blob trigger behavior. See the host.json settings section for details regarding available settings.

Next steps