Redaguoti

Bendrinti naudojant

Azure Blob storage output binding for Azure Functions

  • Straipsnis

The output binding allows you to modify and delete blob storage data in an Azure Function.

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

Important

This article uses tabs to support multiple versions of the Node.js programming model. The v4 model is generally available and is designed to have a more flexible and intuitive experience for JavaScript and TypeScript developers. For more details about how the v4 model works, refer to the Azure Functions Node.js developer guide. To learn more about the differences between v3 and v4, refer to the migration guide.

Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the Python developer guide.

This article supports both programming models.

Example

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

  • Isolated worker model: Compiled C# function that runs in a worker process that's isolated from the runtime. Isolated worker process is required to support C# functions running on LTS and non-LTS versions .NET and the .NET Framework. Extensions for isolated worker process functions use Microsoft.Azure.Functions.Worker.Extensions.* namespaces.
  • In-process model: Compiled C# function that runs in the same process as the Functions runtime. In a variation of this model, Functions can be run using C# scripting, which is supported primarily for C# portal editing. Extensions for in-process functions use Microsoft.Azure.WebJobs.Extensions.* namespaces.

Important

Support will end for the in-process model on November 10, 2026. We highly recommend that you migrate your apps to the isolated worker model for full support.

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.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace SampleApp
{
    public static class BlobFunction
    {
        [Function(nameof(BlobFunction))]
        [BlobOutput("test-samples-output/{name}-output.txt")]
        public static string Run(
            [BlobTrigger("test-samples-trigger/{name}")] string myTriggerItem,
            [BlobInput("test-samples-input/sample1.txt")] string myBlob,
            FunctionContext context)
        {
            var logger = context.GetLogger("BlobFunction");
            logger.LogInformation("Triggered Item = {myTriggerItem}", myTriggerItem);
            logger.LogInformation("Input Item = {myBlob}", myBlob);

            // Blob Output
            return "blob-output content";
        }
    }
}

This section contains the following examples:

HTTP trigger, using OutputBinding (Java)

The following example shows a Java function that uses the HttpTrigger annotation to receive a parameter containing the name of a file in a blob storage container. The BlobInput annotation then reads the file and passes its contents to the function as a byte[]. The BlobOutput annotation binds to OutputBinding outputItem, which is then used by the function to write the contents of the input blob to the configured storage container.

  @FunctionName("copyBlobHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage copyBlobHttp(
    @HttpTrigger(name = "req", 
      methods = {HttpMethod.GET}, 
      authLevel = AuthorizationLevel.ANONYMOUS) 
    HttpRequestMessage<Optional<String>> request,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{Query.file}") 
    byte[] content,
    @BlobOutput(
      name = "target", 
      path = "myblob/{Query.file}-CopyViaHttp")
    OutputBinding<String> outputItem,
    final ExecutionContext context) {
      // Save blob to outputItem
      outputItem.setValue(new String(content, StandardCharsets.UTF_8));

      // build HTTP response with size of requested blob
      return request.createResponseBuilder(HttpStatus.OK)
        .body("The size of \"" + request.getQueryParameters().get("file") + "\" is: " + content.length + " bytes")
        .build();
  }

Queue trigger, using function return value (Java)

The following example shows a Java function that uses the QueueTrigger annotation to receive a message containing the name of a file in a blob storage container. The BlobInput annotation then reads the file and passes its contents to the function as a byte[]. The BlobOutput annotation binds to the function return value, which is then used by the runtime to write the contents of the input blob to the configured storage container.

  @FunctionName("copyBlobQueueTrigger")
  @StorageAccount("Storage_Account_Connection_String")
  @BlobOutput(
    name = "target", 
    path = "myblob/{queueTrigger}-Copy")
  public String copyBlobQueue(
    @QueueTrigger(
      name = "filename", 
      dataType = "string",
      queueName = "myqueue-items") 
    String filename,
    @BlobInput(
      name = "file", 
      path = "samples-workitems/{queueTrigger}") 
    String content,
    final ExecutionContext context) {
      context.getLogger().info("The content of \"" + filename + "\" is: " + content);
      return content;
  }

In the Java functions runtime library, use the @BlobOutput annotation on function parameters whose value would be written to an object in blob storage. The parameter type should be OutputBinding<T>, where T is any native Java type or a POJO.

The following example shows a queue triggered TypeScript function that makes a copy of a blob. The function is triggered by a queue message that contains the name of the blob to copy. The new blob is named {originalblobname}-Copy.

import { app, input, InvocationContext, output } from '@azure/functions';

const blobInput = input.storageBlob({
    path: 'samples-workitems/{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

const blobOutput = output.storageBlob({
    path: 'samples-workitems/{queueTrigger}-Copy',
    connection: 'MyStorageConnectionAppSetting',
});

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<unknown> {
    return context.extraInputs.get(blobInput);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [blobInput],
    return: blobOutput,
    handler: storageQueueTrigger1,
});

The following example shows a queue triggered JavaScript function that makes a copy of a blob. The function is triggered by a queue message that contains the name of the blob to copy. The new blob is named {originalblobname}-Copy.

const { app, input, output } = require('@azure/functions');

const blobInput = input.storageBlob({
    path: 'samples-workitems/{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

const blobOutput = output.storageBlob({
    path: 'samples-workitems/{queueTrigger}-Copy',
    connection: 'MyStorageConnectionAppSetting',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [blobInput],
    return: blobOutput,
    handler: (queueItem, context) => {
        return context.extraInputs.get(blobInput);
    },
});

The following example demonstrates how to create a copy of an incoming blob as the output from a PowerShell function.

In the function's configuration file (function.json), the trigger metadata property is used to specify the output blob name in the path properties.

Note

To avoid infinite loops, make sure your input and output paths are different.

{
  "bindings": [
    {
      "name": "myInputBlob",
      "path": "data/{trigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in",
      "type": "blobTrigger"
    },
    {
      "name": "myOutputBlob",
      "type": "blob",
      "path": "data/copy/{trigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false
}

Here's the PowerShell code:

# Input bindings are passed in via param block.
param([byte[]] $myInputBlob, $TriggerMetadata)
Write-Host "PowerShell Blob trigger function Processed blob Name: $($TriggerMetadata.Name)"
Push-OutputBinding -Name myOutputBlob -Value $myInputBlob

The following example shows blob input and output bindings. The example depends on whether you use the v1 or v2 Python programming model.

The code creates a copy of a blob.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="BlobOutput1")
@app.route(route="file")
@app.blob_input(arg_name="inputblob",
                path="sample-workitems/test.txt",
                connection="<BLOB_CONNECTION_SETTING>")
@app.blob_output(arg_name="outputblob",
                path="newblob/test.txt",
                connection="<BLOB_CONNECTION_SETTING>")
def main(req: func.HttpRequest, inputblob: str, outputblob: func.Out[str]):
    logging.info(f'Python Queue trigger function processed {len(inputblob)} bytes')
    outputblob.set(inputblob)
    return "ok"

Attributes

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

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

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

Decorators

Applies only to the Python v2 programming model.

For Python v2 functions defined using decorators, the following properties on the blob_input and blob_output decorators define the Blob Storage triggers:

Property Description
arg_name The name of the variable that represents the blob in function code.
path The path to the blob For the blob_input decorator, it's the blob read. For the blob_output decorator, it's the output or copy of the input blob.
connection The storage account connection string.
dataType For dynamically typed languages, specifies the underlying data type. Possible values are string, binary, or stream. For more detail, refer to the triggers and bindings concepts.

For Python functions defined by using function.json, see the Configuration section.

Annotations

The @BlobOutput attribute gives you access to the blob that triggered the function. If you use a byte array with the attribute, set dataType to binary. Refer to the output example for details.

Configuration

Applies only to the Python v1 programming model.

The following table explains the properties that you can set on the options object passed to the output.storageBlob() method.

Property Description
path The path to the blob container.
connection The name of an app setting or setting collection that specifies how to connect to Azure Blobs. See Connections.

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

Property Description
type Must be set to blob.
direction Must be set to out for an output binding. Exceptions are noted in the usage section.
name The name of the variable that represents the blob in function code. Set to $return to reference the function return value.
path The path to the blob container.
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.

Usage

The binding types supported by blob output depend on the extension package version and the C# modality used in your function app.

When you want the function to write to a single blob, the blob output binding can bind to the following types:

Type Description
string The blob content as a string. Use when the blob content is simple text.
byte[] The bytes of the blob content.
JSON serializable types An object representing the content of a JSON blob. Functions attempts to serialize a plain-old CLR object (POCO) type into JSON data.

When you want the function to write to multiple blobs, the blob output binding can bind to the following types:

Type Description
T[] where T is one of the single blob output binding types An array containing content for multiple blobs. Each entry represents the content of one blob.

For other output scenarios, create and use a BlobClient or BlobContainerClient with other types from Azure.Storage.Blobs directly. See Register Azure clients for an example of using dependency injection to create a client type from the Azure SDK.

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.

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.

The @BlobOutput attribute gives you access to the blob that triggered the function. If you use a byte array with the attribute, set dataType to binary. Refer to the output example for details.

Access the blob data by returning the value directly or using context.extraOutputs.set().

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

You can declare function parameters as the following types to write out to blob storage:

  • Strings as func.Out[str]
  • Streams as func.Out[func.InputStream]

Refer to the output example for details.

Connections

The connection property is a reference to environment configuration that 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're using version 5.x or higher of the extension (bundle 3.x or higher for non-.NET language stacks), instead of using a connection string with a secret, you can have the app use an Microsoft Entra identity. To use an identity, you define settings under a common prefix that maps to the connection property in the trigger and binding configuration.

If you're 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're 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 can't be used when the overall connection configuration is to be used across blobs, queues, and/or tables. The URI 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 is 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're 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's recommended that you use the service from the same storage account as the blob service. You 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.

Other 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 need to create a role assignment that provides access to your blob container at runtime. Management roles like Owner aren't sufficient. The following table shows built-in roles that are recommended when using the Blob Storage extension in normal operation. Your application may require further permissions based on the code you write.

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

Extra 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's configured to use an identity-based connection, it needs extra permissions beyond the default requirement. The required permissions 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.

Exceptions and return codes

Binding Reference
Blob Blob Error Codes
Blob, Table, Queue Storage Error Codes
Blob, Table, Queue Troubleshooting

Next steps