Azure Functions External File bindings (Preview)

This article shows how to manipulate files from different SaaS providers (e.g. OneDrive, Dropbox) within your function utilizing built-in bindings. Azure functions supports trigger, input, and output bindings for external file.

This binding creates API connections to SaaS providers, or uses existing API connections from your Function App's resource group.

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

Supported File connections

Connector Trigger Input Output
Box x x x
Dropbox x x x
FTP x x x
OneDrive x x x
OneDrive for Business x x x
SFTP x x x
Google Drive x x

Note

External File connections can also be used in Azure Logic Apps

External File trigger binding

The Azure external file trigger lets you monitor a remote folder and run your function code when changes are detected.

The external file trigger uses the following JSON objects in the bindings array of function.json

{
  "type": "apiHubFileTrigger",
  "name": "<Name of input parameter in function signature>",
  "direction": "in",
  "path": "<folder to monitor, and optionally a name pattern - see below>",
  "connection": "<name of external file connection - see above>"
}

Name patterns

You can specify a file name pattern in the path property. The folder referenced must exist in the SaaS provider. Examples:

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

This path would find a file named original-File1.txt in the input folder, and the value of the name variable in function code would be File1.txt.

Another example:

"path": "input/{filename}.{fileextension}",

This path would also find a file named original-File1.txt, and the value of the filename and fileextension variables in function code would be original-File1 and txt.

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

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

In this case, only .png files in the samples folder trigger the function.

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

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

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

Handling poison files

When an external file trigger function fails, Azure Functions retries that function up to 5 times by default (including the first try) for a given file. If all 5 tries fail, Functions adds a message to a Storage queue named webjobs-apihubtrigger-poison. The queue message for poison files is a JSON object that contains the following properties:

  • FunctionId (in the format <function app name>.Functions.<function name>)
  • FileType
  • FolderName
  • FileName
  • ETag (a file version identifier, for example: "0x8D1DC6E70A277EF")

Trigger usage

In C# functions, you bind to the input file 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 file data using context.bindings.<name>.

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

  • Any Object - useful for JSON-serialized file 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 file data.

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

  • string
  • byte[]
  • Stream
  • StreamReader
  • TextReader

Trigger sample

Suppose you have the following function.json, that defines an external file trigger:

{
    "disabled": false,
    "bindings": [
        {
            "name": "myFile",
            "type": "apiHubFileTrigger",
            "direction": "in",
            "path": "samples-workitems",
            "connection": "<name of external file connection>"
        }
    ]
}

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

Trigger usage in C#

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

Trigger usage in Node.js

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

External File input binding

The Azure external file input binding enables you to use a file from an external folder in your function.

The external file 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": "apiHubFile",
  "direction": "in",
  "path": "<Path of input file - see below>",
  "connection": "<name of external file connection>"
},

Note the following:

  • path must contain the folder name and the file name. For example, if you have a queue trigger in your function, you can use "path": "samples-workitems/{queueTrigger}" to point to a file in the samples-workitems folder with a name that matches the file name specified in the trigger message.

Input usage

In C# functions, you bind to the input file 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 file data using context.bindings.<name>.

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

  • Any Object - useful for JSON-serialized file 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 file data.

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

  • string
  • byte[]
  • Stream
  • StreamReader
  • TextReader

External File output binding

The Azure external file output binding enables you to write files to an external folder in your function.

The external file 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": "apiHubFile",
  "direction": "out",
  "path": "<Path of input file - see below>",
  "connection": "<name of external file connection>"
}

Note the following:

  • path must contain the folder name and the file 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 file in the samples-workitems folder with a name that matches the file name specified in the trigger message.

Output usage

In C# functions, you bind to the output file 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 file using context.bindings.<name>.

You can write to the output file 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 file as a null object.
  • String - (out string paramName) useful for text file data. the Functions runtime creates a file 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
  • CloudFileStream
  • ICloudFile
  • CloudBlockFile
  • CloudPageFile

Input + Output sample

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

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnection",
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "myInputFile",
      "type": "apiHubFile",
      "path": "samples-workitems/{queueTrigger}",
      "connection": "<name of external file connection>",
      "direction": "in"
    },
    {
      "name": "myOutputFile",
      "type": "apiHubFile",
      "path": "samples-workitems/{queueTrigger}-Copy",
      "connection": "<name of external file connection>",
      "direction": "out"
    }
  ],
  "disabled": false
}

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

Usage in C#

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

Usage in Node.js

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

Next steps