Azure Functions Storage blob bindings

This article explains how to configure and code Azure Storage blob bindings in Azure Functions. Azure Functions supports trigger, input, and output bindings for Azure Storage blobs.

This is reference information for Azure Functions developers. If you're new to Azure Functions, start with the following resources:

Note

A blob only storage account is not supported. Azure Functions requires a general-purpose storage account to use with blobs.

Storage blob trigger

The Azure Storage blob trigger lets you monitor a storage container for new and updated blobs and run your function code when changes are detected.

The Storage blob trigger to a function uses the following JSON objects in the bindings array of function.json:

{
    "name": "<Name of input parameter in function signature>",
    "type": "blobTrigger",
    "direction": "in",
    "path": "<container to monitor, and optionally a blob name pattern - see below>",
    "connection":"<Name of app setting - see below>"
}

Note the following:

  • For path, see Name patterns to find out how to format blob name patterns.
  • connection must contain the name of an app setting that contains a storage connection string. In the Azure portal, the standard editor in the Integrate tab configures this app setting for you when you create a storage account or selects an existing one. To manually create this app setting, see [configure this app setting manually]().

When running on a Consumption plan, if a Function App has gone idle, there can be be up to a 10-minute day in processing new blobs. Once the Function App is running, blobs are processed more quickly. To avoid this initial delay, either use a regular App Service Plan with Always On enabled or use another mechanism to trigger the blob processing, such as a queue message that contains the blob name.

Also, see one of the following subheadings for more information:

Name patterns

You can specify a blob name pattern in the path property. For example:

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

This path would find a blob named original-Blob1.txt in the input container, and the value of the name variable in function code would be Blob1.

Another example:

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

This path would also find a blob named original-Blob1.txt, and the value of the blobname and blobextension variables in function code would be original-Blob1 and txt.

You can restrict the file type of blobs by using a fixed value for the file extension. For example:

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

In this case, only .png blobs in the samples container trigger the function.

Curly braces are special characters in name patterns. To specify blob names that have curly braces in the name, double the curly braces. For example:

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

This path would find a blob named {20140101}-soundfile.mp3 in the images container, and the name variable value in the function code would be soundfile.mp3.

Blob receipts

The Azure Functions runtime makes sure that no blob trigger function gets called more than once for the same new or updated blob. It does so by maintaining blob receipts to determine if a given blob version has been processed.

Blob receipts are stored in a container named azure-webjobs-hosts in the Azure storage account for your function app (specified by the AzureWebJobsStorage app setting). A blob receipt has the following information:

  • The triggered function ("<function app name>.Functions.<function name>", for example: "functionsf74b96f7.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.

Handling poison blobs

When a blob trigger function fails, Azure Functions retries that function up to 5 times by default (including the first try) for a given blob. If all 5 tries fail, Functions adds a message to a Storage queue named webjobs-blobtrigger-poison. 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")

Blob polling for large containers

If the blob container watched by the binding contains more than 10,000 blobs, the Functions runtime scans log files to watch for new or changed blobs. This process is not real time. A function might not get triggered until several minutes or longer after the blob is created. In addition, storage logs are created on a "best efforts" basis. There is no guarantee that all events are captured. Under some conditions, logs may be missed. If the speed and reliability limitations of blob triggers for large containers are not acceptable for your application, the recommended method is to create a queue message when you create the blob, and use a queue trigger instead of a blob trigger to process the blob.

Trigger usage

In C# functions, you bind to the input blob data by using a named parameter in your function signature, like <T> <name>. Where T is the data type that you want to deserialize the data into, and paramName is the name you specified in the trigger JSON. In Node.js functions, you access the input blob data using context.bindings.<name>.

The blob can be deserialized into any of the following types:

  • Any Object - useful for JSON-serialized blob data. If you declare a custom input type (e.g. FooType), Azure Functions attempts to deserialize the JSON data into your specified type.
  • String - useful for text blob data.

In C# functions, you can also bind to any of the following types, and the Functions runtime will attempt to deserialize the blob data using that type:

  • TextReader
  • Stream
  • ICloudBlob
  • CloudBlockBlob
  • CloudPageBlob
  • CloudBlobContainer
  • CloudBlobDirectory
  • IEnumerable<CloudBlockBlob>
  • IEnumerable<CloudPageBlob>
  • Other types deserialized by ICloudBlobStreamBinder

Trigger sample

Suppose you have the following function.json, that defines a Storage blob trigger:

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

See the language-specific sample that logs the contents of each blob that is added to the monitored container.

Trigger usage in C#

public static void Run(string myBlob, TraceWriter log)
{
    log.Info($"C# Blob trigger function processed: {myBlob}");
}

Trigger usage in Node.js

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

Storage Blob input binding

The Azure Storage blob input binding enables you to use a blob from a storage container in your function.

The Storage blob input to a function uses the following JSON objects in the bindings array of function.json:

{
  "name": "<Name of input parameter in function signature>",
  "type": "blob",
  "direction": "in"
  "path": "<Path of input blob - see below>",
  "connection":"<Name of app setting - see below>"
},

Note the following:

  • path must contain the container name and the blob name. For example, if you have a queue trigger in your function, you can use "path": "samples-workitems/{queueTrigger}" to point to a blob in the samples-workitems container with a name that matches the blob name specified in the trigger message.
  • connection must contain the name of an app setting that contains a storage connection string. In the Azure portal, the standard editor in the Integrate tab configures this app setting for you when you create a Storage account or selects an existing one. To manually create this app setting, see [configure this app setting manually]().

Input usage

In C# functions, you bind to the input blob data by using a named parameter in your function signature, like <T> <name>. Where T is the data type that you want to deserialize the data into, and paramName is the name you specified in the input binding. In Node.js functions, you access the input blob data using context.bindings.<name>.

The blob can be deserialized into any of the following types:

  • Any Object - useful for JSON-serialized blob data. If you declare a custom input type (e.g. InputType), Azure Functions attempts to deserialize the JSON data into your specified type.
  • String - useful for text blob data.

In C# functions, you can also bind to any of the following types, and the Functions runtime will attempt to deserialize the blob data using that type:

  • TextReader
  • Stream
  • ICloudBlob
  • CloudBlockBlob
  • CloudPageBlob

Input sample

Suppose you have the following function.json, that defines a Storage queue trigger, a Storage blob input, and a Storage blob output:

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnection",
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "connection": "MyStorageConnection",
      "direction": "in"
    },
    {
      "name": "myOutputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}-Copy",
      "connection": "MyStorageConnection",
      "direction": "out"
    }
  ],
  "disabled": false
}

See the language-specific sample that copies the input blob to the output blob.

Input usage in C#

public static void Run(string myQueueItem, string myInputBlob, out string myOutputBlob, TraceWriter log)
{
    log.Info($"C# Queue trigger function processed: {myQueueItem}");
    myOutputBlob = myInputBlob;
}

Input usage in Node.js

module.exports = function(context) {
    context.log('Node.js Queue trigger function processed', context.bindings.myQueueItem);
    context.bindings.myOutputBlob = context.bindings.myInputBlob;
    context.done();
};

Storage Blob output binding

The Azure Storage blob output binding enables you to write blobs to a Storage container in your function.

The Storage blob output for a function uses the following JSON objects in the bindings array of function.json:

{
  "name": "<Name of output parameter in function signature>",
  "type": "blob",
  "direction": "out",
  "path": "<Path of input blob - see below>",
  "connection": "<Name of app setting - see below>"
}

Note the following:

  • path must contain the container name and the blob name to write to. For example, if you have a queue trigger in your function, you can use "path": "samples-workitems/{queueTrigger}" to point to a blob in the samples-workitems container with a name that matches the blob name specified in the trigger message.
  • connection must contain the name of an app setting that contains a storage connection string. In the Azure portal, the standard editor in the Integrate tab configures this app setting for you when you create a storage account or selects an existing one. To manually create this app setting, see [configure this app setting manually]().

Output usage

In C# functions, you bind to the output blob by using the named out parameter in your function signature, like out <T> <name>, where T is the data type that you want to serialize the data into, and paramName is the name you specified in the output binding. In Node.js functions, you access the output blob using context.bindings.<name>.

You can write to the output blob using any of the following types:

  • Any Object - useful for JSON-serialization. If you declare a custom output type (e.g. out OutputType paramName), Azure Functions attempts to serialize object into JSON. If the output parameter is null when the function exits, the Functions runtime creates a blob as a null object.
  • String - (out string paramName) useful for text blob data. the Functions runtime creates a blob only if the string parameter is non-null when the function exits.

In C# functions you can also output to any of the following types:

  • TextWriter
  • Stream
  • CloudBlobStream
  • ICloudBlob
  • CloudBlockBlob
  • CloudPageBlob

Output sample

See input sample.

Next steps

For information about other bindings and triggers for Azure Functions, see Azure Functions triggers and bindings developer reference