Associazioni di file esterni in Funzioni di Azure (Anteprima)

Questo articolo illustra come modificare i file da diversi provider di SaaS (ad esempio OneDrive, Dropbox) all'interno della funzione che usa binding incorporati. Funzioni di Azure supporta il trigger e le associazioni di output per i file esterni.

Il binding crea connessioni API ai provider SaaS o usa quelle esistenti prelevandole dal gruppo di risorse dell'app per le funzioni.

Informazioni di riferimento per gli sviluppatori delle Funzioni di Azure. Se non si ha familiarità con le Funzioni di Azure, iniziare con le seguenti risorse:

Connessioni di file supportate

Connettore Trigger Input Output
Box x x x
Dropbox x x x
File system x x x
FTP x x x
OneDrive x x x
OneDrive for Business x x x
SFTP x x x
Archiviazione BLOB di Azure x x
Google Drive x x
Nota

È possibile usare le connessioni ai file esterni anche in App per la logica di Azure

Associazione di trigger di file esterni

Il trigger di file esterni di Azure consente di monitorare una cartella remota ed eseguire il codice della funzione qualora vengano rilevate modifiche.

Tale trigger usa gli oggetti JSON seguenti nella matrice bindings di 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 nome

È possibile specificare un modello di nome per il file nella proprietà path, ad esempio:

"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.

Un altro esempio:

"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.

È possibile limitare il tipo di file dei file usando un valore fisso per l'estensione del file. Ad esempio:

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

In questo caso, la funzione verrà attivata solo dai file .png nella cartella samples.

Le parentesi graffe sono caratteri speciali nei modelli di nome. Per specificare nomi di file con parentesi graffe nel nome, raddoppiare le parentesi graffe. ad esempio:

"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.

Gestione di file non elaborabili

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. Se tutti i 5 tentativi non riescono, Funzioni di Azure aggiunge un messaggio a una coda di archiviazione denominata webjobs-apihubtrigger-poison. Il messaggio di coda per i file non elaborabili è un oggetto JSON che contiene le seguenti proprietà:

  • FunctionId (nel formato <nome dell'app per le funzioni>.Functions.<nome della funzione>)
  • FileType
  • FolderName
  • FileName
  • ETag (identificatore di versione del file, ad esempio: "0x8D1DC6E70A277EF")

Uso dei trigger

Nelle funzioni C# l'associazione ai dati del file di input viene eseguita usando un parametro denominato nella firma funzione, ad esempio <T> <name>. T è il tipo di dati in cui si vogliono deserializzare i dati e paramName è il nome specificato nel JSON del trigger. Nelle funzioni Node.js si accede ai dati del file di input usando context.bindings.<name>.

È possibile deserializzare il file in uno dei tipi seguenti:

  • Qualsiasi oggetto: utile per i dati dei file serializzati con JSON. Se si dichiara un tipo di input personalizzato, ad esempio FooType, Funzioni di Azure tenta di deserializzare i dati JSON nel tipo specificato.
  • Stringa: utile per i dati del file di testo.

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:

  • TextReader
  • Stream
  • ICloudBlob
  • CloudBlockBlob
  • CloudPageBlob
  • CloudBlobContainer
  • CloudBlobDirectory
  • IEnumerable<CloudBlockBlob>
  • IEnumerable<CloudPageBlob>
  • Altri tipi deserializzati da ICloudBlobStreamBinder

Esempio di trigger

Si supponga di avere il function.json seguente, che definisce un trigger di file esterno:

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

Uso dei trigger in C#

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

Uso dei trigger 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 esterni

L'associazione di input di file esterni di Azure consente di usare un file da una cartella esterna nella funzione.

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

  • path deve contenere il nome della cartella e il nome del file. 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.

Uso dell'input

Nelle funzioni C# l'associazione ai dati del file di input viene eseguita usando un parametro denominato nella firma funzione, ad esempio <T> <name>. T è il tipo di dati in cui si vogliono deserializzare i dati e paramName è il nome specificato nell'associazione di input. Nelle funzioni Node.js si accede ai dati del file di input usando context.bindings.<name>.

È possibile deserializzare il file in uno dei tipi seguenti:

  • Qualsiasi oggetto: utile per i dati dei file serializzati con JSON. Se si dichiara un tipo di input personalizzato, ad esempio InputType, Funzioni di Azure tenta di deserializzare i dati JSON nel tipo specificato.
  • Stringa: utile per i dati del file di testo.

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:

  • TextReader
  • Stream
  • ICloudBlob
  • CloudBlockBlob
  • CloudPageBlob

Associazione di output di file esterni

L'associazione di input di file esterni di Azure consente di usare un file da una cartella esterna nella funzione.

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

  • path deve contenere il nome della cartella e il nome del file in cui scrivere. 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.

Uso dell'output

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. Nelle funzioni Node.js si accede al file di output usando context.bindings.<name>.

È possibile scrivere nel file di output usando uno dei tipi seguenti:

  • Qualsiasi oggetto, utile per la serializzazione con JSON. Se si dichiara un tipo di output personalizzato (ad esempio out OutputType paramName), Funzioni di Azure tenta di serializzare l'oggetto in JSON. Se il parametro di output è null quando la funzione viene chiusa, il runtime di Funzioni crea un file come un oggetto null.
  • Stringa: out string paramNameutile per i dati del file di testo. Il runtime di Funzioni crea un file solo se il parametro di stringa è diverso da null quando la funzione viene chiusa.

Nelle funzioni C# è anche possibile eseguire l'output in uno dei tipi seguenti:

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

Esempio di input e output

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:

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

Uso 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.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 successivi

Per informazioni su altre associazioni e altri trigger per Funzioni di Azure, vedere Guida di riferimento per gli sviluppatori di trigger e associazioni di Funzioni di Azure.