Associazioni di file esterni in Funzioni di Azure (sperimentale)Azure Functions External File bindings (experimental)

Questo articolo illustra come modificare i file di diversi provider SaaS (ad esempio Dropbox o Google Drive) in Funzioni di Azure.This article shows how to manipulate files from different SaaS providers (such as Dropbox or Google Drive) in Azure Functions. Funzioni di Azure supporta associazioni di input, output e trigger per i file esterni.Azure Functions supports trigger, input, and output bindings for external files. Queste associazioni creano connessioni API ai provider SaaS o usano le connessioni API esistenti del gruppo di risorse dell'app per le funzioni.These bindings create API connections to SaaS providers, or use existing API connections from your Function App's resource group.

Importante

Le associazioni di file esterni sono sperimentali e potrebbero non diventare mai disponibili a livello generale.The External File bindings are experimental and might never reach Generally Available (GA) status. Sono incluse solo in Funzioni di Azure 1.x e non è prevista la loro aggiunta in Funzioni di Azure 2. x.They are included only in Azure Functions 1.x, and there are no plans to add them to Azure Functions 2.x. Per gli scenari che richiedono l'accesso ai dati nei provider SaaS, è consigliabile usare app per la logica che chiamano funzioni.For scenarios that require access to data in SaaS providers, consider using logic apps that call into functions. Vedere l'articolo relativo al connettore del file system di App per la logica.See the Logic Apps File System connector.

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 file disponibiliAvailable 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 Azure.External File connections can also be used in Azure Logic Apps.

TriggerTrigger

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

Trigger - esempioTrigger - example

Vedere l'esempio specifico per ciascun linguaggio:See the language-specific example:

Trigger - esempio di script C#Trigger - C# script example

L'esempio seguente mostra un'associazione di trigger di file esterno in un file function.json e una funzione script C# che usa l'associazione.The following example shows an external file trigger binding in a function.json file and a C# script function that uses the binding. La funzione registra i contenuti di ogni file aggiunto alla cartella monitorata.The function logs the contents of each file that is added to the monitored folder.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

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

Ecco il codice script C#:Here's the C# script code:

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

Trigger - esempio JavaScriptTrigger - JavaScript example

L'esempio seguente mostra un'associazione di trigger di file esterno in un file function.json e una funzione JavaScript che usa l'associazione.The following example shows an external file trigger binding in a function.json file and a JavaScript function that uses the binding. La funzione registra i contenuti di ogni file aggiunto alla cartella monitorata.The function logs the contents of each file that is added to the monitored folder.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

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

Ecco il codice JavaScript:Here's the JavaScript code:

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

Trigger - configurazioneTrigger - configuration

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json.The following table explains the binding configuration properties that you set in the function.json file.

Proprietà di function.jsonfunction.json property DESCRIZIONEDescription
typetype Il valore deve essere impostato su apiHubFileTrigger.Must be set to apiHubFileTrigger. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection Il valore deve essere impostato su in.Must be set to in. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
nomename Nome della variabile che rappresenta l'elemento evento nel codice della funzione.The name of the variable that represents the event item in function code.
connessioneconnection Identifica l'impostazione dell'app che archivia la stringa di connessione.Identifies the app setting that stores the connection string. L'impostazione dell'app viene creata automaticamente quando si aggiunge una connessione nell'interfaccia utente integrata nel portale di Azure.The app setting is created automatically when you add a connection in the integrate UI in the Azure portal.
pathpath Cartella da monitorare e, facoltativamente, un modello di nome.The folder to monitor, and optionally a name pattern.

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.

Trigger - usoTrigger - 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

Trigger - file non elaborabiliTrigger - 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")

InputInput

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.

Input - esempioInput - example

Vedere l'esempio specifico per ciascun linguaggio:See the language-specific example:

Input - esempio di script C#Input - C# script example

L'esempio seguente mostra associazioni di input e output di file esterno in un file function.json e una funzione script C# che usa l'associazione.The following example shows external file input and output bindings in a function.json file and a C# script function that uses the binding. La funzione copia un file di input in un file di output.The function copies an input file to an output file.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

{
  "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
}

Ecco il codice script C#:Here's the C# script code:

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

Input - esempio JavaScriptInput - JavaScript example

L'esempio seguente mostra associazioni di input e output di file esterno in un file function.json e una funzione JavaScript che usa l'associazione.The following example shows external file input and output bindings in a function.json file and a JavaScript function that uses the binding. La funzione copia un file di input in un file di output.The function copies an input file to an output file.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

{
  "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
}

Ecco il codice JavaScript:Here's the JavaScript code:

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

Input - configurazioneInput - configuration

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json.The following table explains the binding configuration properties that you set in the function.json file.

Proprietà di function.jsonfunction.json property DESCRIZIONEDescription
typetype Il valore deve essere impostato su apiHubFile.Must be set to apiHubFile. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection Il valore deve essere impostato su in.Must be set to in. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
nomename Nome della variabile che rappresenta l'elemento evento nel codice della funzione.The name of the variable that represents the event item in function code.
connessioneconnection Identifica l'impostazione dell'app che archivia la stringa di connessione.Identifies the app setting that stores the connection string. L'impostazione dell'app viene creata automaticamente quando si aggiunge una connessione nell'interfaccia utente integrata nel portale di Azure.The app setting is created automatically when you add a connection in the integrate UI in the Azure portal.
pathpath Deve contenere il nome della cartella e il nome del file.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.

Input - usoInput - 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 deserializzare i dati e name è il nome specificato nell'associazione di input.T is the data type that you want to deserialize the data into, and name 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

OutputOutput

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.

Output - esempioOutput - example

Vedere l'esempio di associazione di input.See the input binding example.

Output - configurazioneOutput - configuration

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json.The following table explains the binding configuration properties that you set in the function.json file.

Proprietà di function.jsonfunction.json property DESCRIZIONEDescription
typetype Il valore deve essere impostato su apiHubFile.Must be set to apiHubFile. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection Il valore deve essere impostato su out.Must be set to out. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
nomename Nome della variabile che rappresenta l'elemento evento nel codice della funzione.The name of the variable that represents the event item in function code.
connessioneconnection Identifica l'impostazione dell'app che archivia la stringa di connessione.Identifies the app setting that stores the connection string. L'impostazione dell'app viene creata automaticamente quando si aggiunge una connessione nell'interfaccia utente integrata nel portale di Azure.The app setting is created automatically when you add a connection in the integrate UI in the Azure portal.
pathpath Deve contenere il nome della cartella e il nome del file.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.

Output - usoOutput - usage

Nelle funzioni C# è possibile eseguire l'associazione al file di output usando il parametro denominato out nella firma della funzione, ad esempio out <T> <name>, dove T è il tipo di dati in cui serializzare i dati e name è 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 name 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

Passaggi successiviNext steps