| title | description | ms.topic | ms.date | ms.devlang | ms.custom | zone_pivot_groups |
|---|---|---|---|---|---|---|
Azure Blob storage trigger for Azure Functions | Learn how to use Azure Function to run your custom code based on changes in an Azure Blob storage container. | reference | 05/14/2024 | csharp | devx-track-csharp, devx-track-python, devx-track-extended-java, devx-track-js, devx-track-ts | programming-languages-set-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.
Tip
There are several ways to execute your function code based on changes to blobs in a storage container. If you choose to use the Blob storage trigger, note that there are two implementations offered: a polling-based one (referenced in this article) and an event-based one. It is recommended that you use the event-based implementation as it has lower latency than the other. Also, the Flex Consumption plan supports only the event-based Blob storage trigger.
For details about differences between the two implementations of the Blob storage trigger, as well as other triggering options, see Working with blobs.
For information on setup and configuration details, see the overview.
::: zone pivot="programming-language-javascript,programming-language-typescript"
[!INCLUDE functions-nodejs-model-tabs-description]
::: zone-end
::: zone pivot="programming-language-python"
[!INCLUDE functions-python-model-tabs-description]
::: zone-end
::: zone pivot="programming-language-csharp"
[!INCLUDE functions-bindings-csharp-intro]
[!INCLUDE functions-in-process-model-retirement-note]
The following example is a C# function that runs in an isolated worker process and uses a blob trigger with both blob input and blob output blob bindings. The function is triggered by the creation of a blob in the test-samples-trigger container. It reads a text file from the test-samples-input container and creates a new text file in an output container based on the name of the triggered file.
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/Blob/BlobFunction.cs" range="9-25":::
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")]publicstaticvoidRun([BlobTrigger("samples-workitems/{name}")]StreammyBlob,stringname,ILoggerlog){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.
::: zone-end ::: zone pivot="programming-language-java"
This function writes a log when a blob is added or updated in the myblob container.
@FunctionName("blobprocessor") publicvoidrun( @BlobTrigger(name = "file", dataType = "binary", path = "myblob/{name}", connection = "MyStorageAccountAppSetting") byte[] content, @BindingName("name") Stringfilename, finalExecutionContextcontext ) { context.getLogger().info("Name: " + filename + " Size: " + content.length + " bytes"); }::: zone-end
::: zone pivot="programming-language-typescript"
The following example shows a blob trigger TypeScript code. The function writes a log when a blob is added or updated in the samples-workitems container.
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.
:::code language="typescript" source="~/azure-functions-nodejs-v4/ts/src/functions/storageBlobTrigger1.ts" :::
TypeScript samples are not documented for model v3.
::: zone-end
::: zone pivot="programming-language-javascript"
The following example shows a blob trigger JavaScript code. The function writes a log when a blob is added or updated in the samples-workitems container.
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.
:::code language="javascript" source="~/azure-functions-nodejs-v4/js/src/functions/storageBlobTrigger1.js" :::
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=asyncfunction(context){context.log('Node.js Blob trigger function processed',context.bindings.myBlob);};::: zone-end
::: zone pivot="programming-language-powershell"
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"::: zone-end
::: zone pivot="programming-language-python"
This example uses SDK types to directly access the underlying BlobClient object provided by the Blob storage trigger:
:::code language="python" source="~/functions-python-extensions/azurefunctions-extensions-bindings-blob/samples/blob_samples_blobclient/function_app.py" range="9-14,31-39":::
For examples of using other SDK types, see the ContainerClient and StorageStreamDownloader samples.
To learn more, including how to enable SDK type bindings in your project, see SDK type bindings.
This example logs information from the incoming blob metadata.
importloggingimportazure.functionsasfuncapp=func.FunctionApp() @app.function_name(name="BlobTrigger1")@app.blob_trigger(arg_name="myblob", path="PATH/TO/BLOB",connection="CONNECTION_SETTING")deftest_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")The function writes a log when a blob is added or updated in the samples-workitemscontainer. 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:
importloggingimportazure.functionsasfuncdefmain(myblob: func.InputStream): logging.info('Python Blob trigger function processed %s', myblob.name)::: zone-end
::: zone pivot="programming-language-csharp"
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 as described in the C# scripting guide.
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. |
| Source | Sets the source of the triggering event. Use BlobTriggerSource.EventGrid for an Event Grid-based blob trigger, which provides much lower latency. The default is BlobTriggerSource.LogsAndContainerScan, which uses the standard polling mechanism to detect changes in the container. |
Here's an BlobTrigger attribute in a method signature:
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/Blob/BlobFunction.cs" range="11-16":::
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")]publicstaticvoidRun([BlobTrigger("sample-images/{name}")]Streamimage,[Blob("sample-images-md/{name}",FileAccess.Write)]StreamimageSmall){ .... }[!INCLUDE functions-bindings-storage-attribute]
[!INCLUDE app settings to local.settings.json]
::: zone-end
::: zone pivot="programming-language-python"
Applies only to the Python v2 programming model.
For Python v2 functions defined using decorators, the following properties on the blob_trigger decorator define the Blob Storage trigger:
| Property | Description |
|---|---|
arg_name | Declares the parameter name in the function signature. When the function is triggered, this parameter's value has the contents of the queue message. |
path | The container to monitor. May be a blob name pattern. |
connection | The storage account connection string. |
source | Sets the source of the triggering event. Use EventGrid for an Event Grid-based blob trigger, which provides much lower latency. The default is LogsAndContainerScan, which uses the standard polling mechanism to detect changes in the container. |
For Python functions defined by using function.json, see the Configuration section. ::: zone-end ::: zone pivot="programming-language-java"
The @BlobTrigger attribute is used to give you access to the blob that triggered the function. Refer to the trigger example for details. Use the source property to set the source of the triggering event. Use EventGrid for an Event Grid-based blob trigger, which provides much lower latency. The default is LogsAndContainerScan, which uses the standard polling mechanism to detect changes in the container. | ::: zone-end
::: zone pivot="programming-language-javascript,programming-language-typescript,programming-language-powershell,programming-language-python"
::: zone-end
::: zone pivot="programming-language-python" Applies only to the Python v1 programming model.
::: zone-end ::: zone pivot="programming-language-javascript,programming-language-typescript"
The following table explains the properties that you can set on the options object passed to the app.storageBlob() method.
| Property | Description |
|---|---|
| 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. |
| source | Sets the source of the triggering event. Use EventGrid for an Event Grid-based blob trigger, which provides much lower latency. The default is LogsAndContainerScan, which uses the standard polling mechanism to detect changes in the container. |
The following table explains the binding configuration properties that you set in the function.json file.
| 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. |
| source | Sets the source of the triggering event. Use EventGrid for an Event Grid-based blob trigger, which provides much lower latency. The default is LogsAndContainerScan, which uses the standard polling mechanism to detect changes in the container. |
::: zone-end
::: zone pivot="programming-language-powershell,programming-language-python"
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. |
| source | Sets the source of the triggering event. Use EventGrid for an Event Grid-based blob trigger, which provides much lower latency. The default is LogsAndContainerScan, which uses the standard polling mechanism to detect changes in the container. |
::: zone-end
See the Example section for complete examples.
::: zone pivot="programming-language-csharp"
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 CloudBlob 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:
publicstaticvoidRun(stringmyBlob,stringblobTrigger,ILoggerlog){log.LogInformation($"Full blob path: {blobTrigger}");}::: zone-end ::: zone pivot="programming-language-javascript,programming-language-typescript"
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 triggerMetadata property of the supplied context object, as shown in the following example, which logs the path to the triggering blob (blobTrigger), including the container:
context.log(`Full blob path: ${context.triggerMetadata.blobTrigger}`);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=asyncfunction(context,myBlob){context.log("Full blob path:",context.bindingData.blobTrigger);};::: zone-end
::: zone pivot="programming-language-powershell"
Metadata is available through the $TriggerMetadata parameter. ::: zone-end
::: zone pivot="programming-language-csharp"
The binding types supported by Blob trigger depend on the extension package version and the C# modality used in your function app.
[!INCLUDE functions-bindings-storage-blob-trigger-dotnet-isolated-types]
See Binding types for a list of supported types.
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 BlobClient 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.
[!INCLUDE functions-bindings-blob-storage-attribute] ::: zone-end
::: zone pivot="programming-language-java" The @BlobTrigger attribute is used to give you access to the blob that triggered the function. Refer to the trigger example for details. ::: zone-end
::: zone pivot="programming-language-javascript,programming-language-typescript"
Access the blob data as the first argument to your function.
Access blob data using context.bindings.<NAME> where <NAME> matches the value defined in function.json.
::: zone-end
::: zone pivot="programming-language-powershell"
Access the blob data via a parameter that matches the name designated by binding's name parameter in the function.json file. ::: zone-end
::: zone pivot="programming-language-python" Access blob data via the parameter typed as InputStream. Refer to the trigger example for details.
Functions also supports Python SDK type bindings for Azure Blob storage, which lets you work with blob data using these underlying SDK types:
Important
SDK types support for Python is currently in preview and is only supported for the Python v2 programming model. For more information, see SDK types in Python.
::: zone-end
[!INCLUDE functions-storage-blob-connections]
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.
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.
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.
The following example triggers only on .png files:
"path": "samples/{name}.png",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 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 consider switching your hosting to use an App Service plan with Always On enabled, which may result in increased costs. You might also consider using a trigger other than the classic polling blob trigger. For more information and a comparison of the various triggering options for blob storage containers, see Trigger on a blob container.
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 (
BlockBloborPageBlob) - 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.
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 (
BlockBloborPageBlob) - ContainerName
- BlobName
- ETag (a blob version identifier, for example:
0x8D1DC6E70A277EF)
::: zone pivot="programming-language-csharp" When you bind to an output type that doesn't support streaming, such as string, or Byte[], the runtime must load the entire blob into memory more than one time during processing. This can result in higher-than expected memory usage when processing blobs. When possible, use a stream-supporting type. Type support depends on the C# mode and extension version. For more information, see Binding types. ::: zone-end
::: zone pivot="programming-language-javascript,programming-language-typescript,programming-language-python,programming-language-powershell,programming-language-java" At this time, the runtime must load the entire blob into memory more than one time during processing. This can result in higher-than expected memory usage when processing blobs. ::: zone-end
Memory usage can be further impacted when multiple function instances are concurrently processing blob data. If you are having memory issues using a Blob trigger, consider reducing the number of concurrent executions permitted. Of course, reducing the concurrency can have the side effect of increasing the backlog of blobs waiting to be processed. The memory limits of your function app depends on the plan. For more information, see Service limits.
The way that you can control the number of concurrent executions depends on the version of the Storage extension you are using.
When using version 5.0.0 of the Storage extension or a later version, you control trigger concurrency by using the maxDegreeOfParallelism setting in the blobs configuration in host.json.
Because the blob trigger uses a queue internally, the maximum number of concurrent function invocations is controlled by the queues configuration in host.json.
Limits apply separately to each function that uses a blob trigger.
The host.json file contains settings that control blob trigger behavior. See the host.json settings section for details regarding available settings.
