Associazioni di file esterni in Funzioni di Azure (Anteprima)Azure Functions External File bindings (Preview)

Questo articolo illustra come modificare i file da diversi provider di SaaS (ad esempio OneDrive, Dropbox) all'interno della funzione che usa binding incorporati.This article shows how to manipulate files from different SaaS providers (e.g. OneDrive, Dropbox) within your function utilizing built-in bindings. Funzioni di Azure supporta il trigger e le associazioni di output per i file esterni.Azure functions supports trigger, input, and output bindings for external file.

Il binding crea connessioni API ai provider SaaS o usa quelle esistenti prelevandole dal gruppo di risorse dell'app per le funzioni.This binding creates API connections to SaaS providers, or uses existing API connections from your Function App's resource group.

Informazioni di riferimento per gli sviluppatori delle Funzioni di Azure.This is reference information for Azure Functions developers. Se non si ha familiarità con le Funzioni di Azure, iniziare con le seguenti risorse:If you're new to Azure Functions, start with the following resources:

Connessioni di file supportateSupported File connections

ConnettoreConnector TriggerTrigger InputInput OutputOutput
BoxBox xx xx xx
DropboxDropbox xx xx xx
FTPFTP xx xx xx
OneDriveOneDrive xx xx xx
OneDrive for BusinessOneDrive for Business xx xx xx
SFTPSFTP xx xx xx
Google DriveGoogle Drive xx xx

Nota

È possibile usare le connessioni ai file esterni anche in App per la logica di AzureExternal File connections can also be used in Azure Logic Apps

Associazione di trigger di file esterniExternal File trigger binding

Il trigger di file esterni di Azure consente di monitorare una cartella remota ed eseguire il codice della funzione qualora vengano rilevate modifiche.The Azure external file trigger lets you monitor a remote folder and run your function code when changes are detected.

Tale trigger usa gli oggetti JSON seguenti nella matrice bindings di function.json: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>"
}

Modelli di nomeName patterns

È possibile specificare un modello di nome per il file nella proprietà path,You can specify a file name pattern in the path property. La cartella a cui si fa riferimento deve esistere nel provider SaaS.The folder referenced must exist in the SaaS provider. Esempi:Examples:

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

Questo percorso individua il file denominato original-File1.txt nella cartella input e il valore della variabile name nel codice della funzione sarà File1.txt.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.

Un altro esempio:Another example:

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

Anche questo percorso individua un file denominato original-File1.txt e i valori delle variabili filename e fileextension nel codice della funzione saranno original-File1 e txt.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.

È possibile limitare il tipo di file dei file usando un valore fisso per l'estensione del file.You can restrict the file type of files by using a fixed value for the file extension. Ad esempio:For example:

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

In questo caso, la funzione verrà attivata solo dai file .png nella cartella samples.In this case, only .png files in the samples folder trigger the function.

Le parentesi graffe sono caratteri speciali nei modelli di nome.Curly braces are special characters in name patterns. Per specificare nomi di file con parentesi graffe nel nome, raddoppiare le parentesi graffe.To specify file names that have curly braces in the name, double the curly braces. ad esempio:For example:

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

Questo percorso troverà un file denominato {20140101}-soundfile.mp3 nella cartella images e il valore della variabile name nel codice della funzione sarà soundfile.mp3.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.

Gestione di file non elaborabiliHandling poison files

Quando una funzione di trigger del file esterno ha esito negativo, per impostazione predefinita Funzioni di Azure ritenta l'esecuzione fino a 5 volte (incluso il primo tentativo) per un dato messaggio.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. Se tutti i 5 tentativi non riescono, Funzioni di Azure aggiunge un messaggio a una coda di archiviazione denominata webjobs-apihubtrigger-poison.If all 5 tries fail, Functions adds a message to a Storage queue named webjobs-apihubtrigger-poison. Il messaggio di coda per i file non elaborabili è un oggetto JSON che contiene le seguenti proprietà:The queue message for poison files is a JSON object that contains the following properties:

  • FunctionId (nel formato <nome dell'app per le funzioni>.Functions.<nome della funzione>)FunctionId (in the format <function app name>.Functions.<function name>)
  • FileTypeFileType
  • FolderNameFolderName
  • FileNameFileName
  • ETag (identificatore di versione del file, ad esempio: "0x8D1DC6E70A277EF")ETag (a file version identifier, for example: "0x8D1DC6E70A277EF")

Uso dei triggerTrigger usage

Nelle funzioni C# l'associazione ai dati del file di input viene eseguita usando un parametro denominato nella firma funzione, ad esempio <T> <name>.In C# functions, you bind to the input file data by using a named parameter in your function signature, like <T> <name>. T è il tipo di dati in cui si vogliono deserializzare i dati e paramName è il nome specificato nel JSON del trigger.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. Nelle funzioni Node.js si accede ai dati del file di input usando context.bindings.<name>.In Node.js functions, you access the input file data using context.bindings.<name>.

È possibile deserializzare il file in uno dei tipi seguenti:The file can be deserialized into any of the following types:

  • Qualsiasi oggetto: utile per i dati dei file serializzati con JSON.Any Object - useful for JSON-serialized file data. Se si dichiara un tipo di input personalizzato, ad esempio FooType, Funzioni di Azure tenta di deserializzare i dati JSON nel tipo specificato.If you declare a custom input type (e.g. FooType), Azure Functions attempts to deserialize the JSON data into your specified type.
  • Stringa: utile per i dati del file di testo.String - useful for text file data.

Nelle funzioni C# è anche possibile eseguire l'associazione a uno dei tipi seguenti e il runtime di Funzioni di Azure tenta di deserializzare i dati del file usando quel tipo: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

Esempio di triggerTrigger sample

Si supponga di avere il function.json seguente, che definisce un trigger di file esterno: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>"
        }
    ]
}

Vedere l'esempio specifico del linguaggio che registra i contenuti di ogni file aggiunto alla cartella monitorata.See the language-specific sample that logs the contents of each file that is added to the monitored folder.

Uso dei trigger in C#Trigger usage in C#

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

Uso dei trigger in Node.jsTrigger usage in Node.js

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

Associazione di input di file esterniExternal File input binding

L'associazione di input di file esterni di Azure consente di usare un file da una cartella esterna nella funzione.The Azure external file input binding enables you to use a file from an external folder in your function.

L'input del file esterno in una funzione usa gli oggetti JSON seguenti nella matrice bindings di function.json: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>"
},

Tenere presente quanto segue:Note the following:

  • path deve contenere il nome della cartella e il nome del file.path must contain the folder name and the file name. Se, ad esempio, nella funzione è presente un trigger della coda, è possibile usare "path": "samples-workitems/{queueTrigger}" in modo che punti a un file nella cartella samples-workitems con un nome che corrisponde al nome di file specificato nel messaggio di trigger.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.

Uso dell'inputInput usage

Nelle funzioni C# l'associazione ai dati del file di input viene eseguita usando un parametro denominato nella firma funzione, ad esempio <T> <name>.In C# functions, you bind to the input file data by using a named parameter in your function signature, like <T> <name>. T è il tipo di dati in cui si vogliono deserializzare i dati e paramName è il nome specificato nell'associazione di input.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. Nelle funzioni Node.js si accede ai dati del file di input usando context.bindings.<name>.In Node.js functions, you access the input file data using context.bindings.<name>.

È possibile deserializzare il file in uno dei tipi seguenti:The file can be deserialized into any of the following types:

  • Qualsiasi oggetto: utile per i dati dei file serializzati con JSON.Any Object - useful for JSON-serialized file data. Se si dichiara un tipo di input personalizzato, ad esempio InputType, Funzioni di Azure tenta di deserializzare i dati JSON nel tipo specificato.If you declare a custom input type (e.g. InputType), Azure Functions attempts to deserialize the JSON data into your specified type.
  • Stringa: utile per i dati del file di testo.String - useful for text file data.

Nelle funzioni C# è anche possibile eseguire l'associazione a uno dei tipi seguenti e il runtime di Funzioni di Azure tenta di deserializzare i dati del file usando quel tipo: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

Associazione di output di file esterniExternal File output binding

L'associazione di input di file esterni di Azure consente di usare un file da una cartella esterna nella funzione.The Azure external file output binding enables you to write files to an external folder in your function.

L'output del file esterno per una funzione usa gli oggetti JSON seguenti nella matrice bindings di function.json: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>"
}

Tenere presente quanto segue:Note the following:

  • path deve contenere il nome della cartella e il nome del file in cui scrivere.path must contain the folder name and the file name to write to. Se, ad esempio, nella funzione è presente un trigger della coda, è possibile usare "path": "samples-workitems/{queueTrigger}" in modo che punti a un file nella cartella samples-workitems con un nome che corrisponde al nome di file specificato nel messaggio di trigger.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.

Uso dell'outputOutput usage

Nelle funzioni C# è possibile eseguire l'associazione al file di output usando il parametro denominato out nella firma funzione, ad esempio out <T> <name>, dove T è il tipo di dati in cui si vuole serializzare i dati e paramName è il nome specificato nell'associazione di output.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. Nelle funzioni Node.js si accede al file di output usando context.bindings.<name>.In Node.js functions, you access the output file using context.bindings.<name>.

È possibile scrivere nel file di output usando uno dei tipi seguenti:You can write to the output file using any of the following types:

  • Qualsiasi oggetto, utile per la serializzazione con JSON.Any Object - useful for JSON-serialization. Se si dichiara un tipo di output personalizzato (ad esempio out OutputType paramName), Funzioni di Azure tenta di serializzare l'oggetto in JSON.If you declare a custom output type (e.g. out OutputType paramName), Azure Functions attempts to serialize object into JSON. Se il parametro di output è null quando la funzione viene chiusa, il runtime di Funzioni crea un file come un oggetto null.If the output parameter is null when the function exits, the Functions runtime creates a file as a null object.
  • Stringa: out string paramNameutile per i dati del file di testo.String - (out string paramName) useful for text file data. Il runtime di Funzioni crea un file solo se il parametro di stringa è diverso da null quando la funzione viene chiusa.the Functions runtime creates a file only if the string parameter is non-null when the function exits.

Nelle funzioni C# è anche possibile eseguire l'output in uno dei tipi seguenti:In C# functions you can also output to any of the following types:

  • TextWriter
  • Stream
  • CloudFileStream
  • ICloudFile
  • CloudBlockFile
  • CloudPageFile

Esempio di input e outputInput + Output sample

Si supponga di avere il function.json seguente, che definisce un trigger della coda di archiviazione, un input del file esterno e un output del file esterno: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
}

Vedere l'esempio specifico del linguaggio che copia il file di input nel file di output.See the language-specific sample that copies the input file to the output file.

Utilizzo in C#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;
}

Uso in Node.jsUsage 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();
};

Passaggi successiviNext steps