Condividi tramite

Associazione di output dell'archiviazione BLOB di Azure per Funzioni di Azure

  • Articolo

L'associazione di output consente di modificare ed eliminare i dati di archiviazione BLOB in una funzione di Azure.

Per informazioni sui dettagli di impostazione e configurazione, vedere la panoramica.

Importante

Questo articolo usa schede per supportare più versioni del modello di programmazione Node.js. Il modello v4 è disponibile a livello generale ed è progettato per offrire un'esperienza più flessibile e intuitiva per gli sviluppatori JavaScript e TypeScript. Per altre informazioni sul funzionamento del modello v4, vedere la guida per sviluppatori di Funzioni di Azure Node.js. Per altre informazioni sulle differenze tra v3 e v4, vedere la guida alla migrazione.

Funzioni di Azure supporta due modelli di programmazione per Python. Il modo in cui si definiscono le associazioni dipende dal modello di programmazione scelto.

Il modello di programmazione Python v2 consente di definire associazioni usando elementi Decorator direttamente nel codice della funzione Python. Per altre informazioni, vedere la Guida per sviluppatori Python.

Questo articolo supporta entrambi i modelli di programmazione.

Esempio

È possibile creare una funzione C# usando una delle modalità C# seguenti:

  • Modello di lavoro isolato: funzione C# compilata eseguita in un processo di lavoro isolato dal runtime. Il processo di lavoro isolato è necessario per supportare le funzioni C# in esecuzione in LTS e versioni non LTS .NET e .NET Framework. Le estensioni per le funzioni del processo di lavoro isolato usano Microsoft.Azure.Functions.Worker.Extensions.* spazi dei nomi.
  • Modello in-process: funzione C# compilata eseguita nello stesso processo del runtime di Funzioni. In una variante di questo modello, le funzioni possono essere eseguite usando script C#, che è supportato principalmente per la modifica del portale C#. Le estensioni per le funzioni in-process usano Microsoft.Azure.WebJobs.Extensions.* spazi dei nomi.

Importante

Il supporto terminerà per il modello in-process il 10 novembre 2026. È consigliabile eseguire la migrazione delle app al modello di lavoro isolato per il supporto completo.

L'esempio seguente è una funzione C# che viene eseguita in un processo di lavoro isolato e usa un trigger BLOB con associazioni BLOB di input e BLOB di output BLOB. La funzione viene attivata dalla creazione di un BLOB nel contenitore test-samples-trigger . Legge un file di testo dal contenitore test-samples-input e crea un nuovo file di testo in un contenitore di output in base al nome del file attivato.

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

Questa sezione contiene gli esempi seguenti:

Trigger HTTP, uso di OutputBinding (Java)

L'esempio seguente mostra una funzione Java che usa l'annotazione HttpTrigger per ricevere un parametro che contiene il nome di un file in un contenitore di archiviazione BLOB. L'annotazione BlobInput legge quindi il file e passa il relativo contenuto alla funzione come byte[]. L'annotazione BlobOutput viene associata a OutputBinding outputItem, che viene quindi usato dalla funzione per scrivere il contenuto del BLOB di input nel contenitore di archiviazione configurato.

  @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();
  }

Trigger di coda, uso del valore restituito della funzione (Java)

L'esempio seguente mostra una funzione Java che usa l'annotazione QueueTrigger per ricevere un messaggio che contiene il nome di un file in un contenitore di archiviazione BLOB. L'annotazione BlobInput legge quindi il file e passa il relativo contenuto alla funzione come byte[]. L'annotazione BlobOutput viene associata al valore restituito dalla funzione, che viene quindi usato dal runtime per scrivere il contenuto del BLOB di input nel contenitore di archiviazione configurato.

  @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;
  }

Nella libreria di runtime di funzioni Java usare @BlobOutput l'annotazione per i parametri di funzione il cui valore viene scritto in un oggetto nell’archiviazione BLOB. Il tipo di parametro deve essere OutputBinding<T>, dove T è qualsiasi tipo Java nativo o POJO.

L'esempio seguente mostra una funzione TypeScript attivata dalla coda che crea una copia di un BLOB. La funzione viene attivata da un messaggio della coda che contiene il nome del BLOB da copiare. Il nuovo BLOB è denominato {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,
});

L'esempio seguente mostra una funzione JavaScript attivata dalla coda che crea una copia di un BLOB. La funzione viene attivata da un messaggio della coda che contiene il nome del BLOB da copiare. Il nuovo BLOB è denominato {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);
    },
});

L'esempio seguente illustra come creare una copia di un BLOB in ingresso come output da una funzione di PowerShell.

Nel file di configurazione della funzione (function.json), la trigger proprietà dei metadati viene usata per specificare il nome del BLOB di output nelle pathproprietà.

Nota

Per evitare cicli infiniti, assicurarsi che i percorsi di input e output siano diversi.

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

Ecco il codice di PowerShell:

# 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

L'esempio seguente mostra le associazioni di input e output del BLOB. L'esempio dipende dal fatto che si usi il modello di programmazione Python v1 o v2.

Il codice crea una copia di un 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"

Attributi

Sia le librerie C# in-process che il processo di lavoro isolato usano l'attributo per definire la funzione. Lo script C# usa invece un file di configurazione function.json come descritto nella guida per gli script C#.

Il BlobOutputAttribute costruttore accetta i parametri seguenti:

Parametro Descrizione
BlobPath Percorso del BLOB.
Connessione Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi ai BLOB di Azure. Vedere Connessioni.

Quando si sviluppa in locale, aggiungere le impostazioni dell'applicazione nel file local.settings.json nella Values raccolta.

Elementi Decorator

Si applica solo al modello di programmazione Python v2.

Per le funzioni Python v2 definite usando elementi decorator, le proprietà seguenti negli blob_input blob_output elementi Decorator definiscono i trigger di archiviazione BLOB:

Proprietà Descrizione
arg_name Nome della variabile che rappresenta il BLOB nel codice della funzione.
path Percorso del BLOB Per l'elemento blob_input decorator, è il BLOB letto. Per l'elemento blob_output Decorator, si tratta dell'output o della copia del BLOB di input.
connection La stringa di connessione dell'account di archiviazione.
dataType Per i linguaggi tipizzato in modo dinamico, specifica il tipo di dati sottostante. I valori possibili sono string, binaryo stream. Per altri dettagli, vedere i concetti relativi a trigger e associazioni.

Per le funzioni Python definite tramite function.json, vedere la sezione Configurazione .

Annotazioni

L'attributo @BlobOutput consente di accedere al BLOB che ha attivato la funzione. Se si usa una matrice di byte con l'attributo , impostare su dataType binary. Per informazioni dettagliate, vedere l'esempio di output.

Impostazione

Si applica solo al modello di programmazione Python v1.

Nella tabella seguente vengono illustrate le proprietà che è possibile impostare sull'oggetto options passato al output.storageBlob() metodo .

Proprietà Descrizione
path Percorso del contenitore BLOB.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi ai BLOB di Azure. Vedere Connessioni.

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json.

Proprietà Descrizione
type Deve essere impostato su blob.
direction Deve essere impostato su out per un'associazione di output. Le eccezioni sono indicate nella sezione usage.
name Nome della variabile che rappresenta il BLOB nel codice della funzione. Impostare su $return per fare riferimento al valore restituito della funzione.
path Percorso del contenitore BLOB.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi ai BLOB di Azure. Vedere Connessioni.

Per esempi completi, vedere la sezione di esempio.

Utilizzo

I tipi di associazione supportati dall'output del BLOB dipendono dalla versione del pacchetto di estensione e dalla modalità C# usata nell'app per le funzioni.

Quando si vuole che la funzione scriva in un singolo BLOB, l'associazione di output del BLOB può essere associata ai tipi seguenti:

Tipo Descrizione
string Contenuto del BLOB come stringa. Usare quando il contenuto del BLOB è testo semplice.
byte[] Byte del contenuto del BLOB.
Tipi serializzabili JSON Oggetto che rappresenta il contenuto di un BLOB JSON. Funzioni tenta di serializzare un tipo di oggetto CLR (POCO) normale in dati JSON.

Quando si vuole che la funzione scriva in più BLOB, l'associazione di output del BLOB può essere associata ai tipi seguenti:

Tipo Descrizione
T[] dove T è uno dei tipi di associazione di output del BLOB singolo Matrice contenente contenuto per più BLOB. Ogni voce rappresenta il contenuto di un BLOB.

Per altri scenari di output, creare e usare direttamente i tipi da Azure.Storage.Blobs .

L'associazione a stringo Byte[] è consigliata solo quando le dimensioni del BLOB sono ridotte. Questa operazione è consigliata perché l'intero contenuto del BLOB viene caricato in memoria. Per la maggior parte dei BLOB, usare un Stream tipo o BlobClient . Per altre informazioni, vedere Concorrenza e utilizzo della memoria.

Se viene visualizzato un messaggio di errore quando si tenta di eseguire l'associazione a uno dei tipi di Storage SDK, assicurarsi di avere un riferimento alla versione corretta di Storage SDK.

È anche possibile usare StorageAccountAttribute per specificare l'account di archiviazione da usare. Questa operazione può essere eseguita quando è necessario usare un account di archiviazione diverso da altre funzioni della libreria. Il costruttore accetta il nome di un'impostazione dell'app che contiene una stringa di connessione di archiviazione. L'attributo può essere applicato a livello di parametro, metodo o classe. L'esempio seguente illustra il livello classe e il livello metodo:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("BlobTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ....
}

L'account di archiviazione da usare è determinato nell'ordine seguente:

  • La proprietà Connection dell'attributo BlobTrigger.
  • L'attributo StorageAccount applicato allo stesso parametro dell'attributo BlobTrigger.
  • L'attributo StorageAccount applicato alla funzione.
  • L'attributo StorageAccount applicato alla classe.
  • L'account di archiviazione predefinito per l'app per le funzioni, definito nell'impostazione dell'applicazione AzureWebJobsStorage .

L'attributo @BlobOutput consente di accedere al BLOB che ha attivato la funzione. Se si usa una matrice di byte con l'attributo , impostare su dataType binary. Per informazioni dettagliate, vedere l'esempio di output.

Accedere ai dati BLOB restituendo direttamente il valore o usando context.extraOutputs.set().

Accedere ai dati DEL BLOB tramite un parametro che corrisponde al nome designato dal parametro name dell'associazione nel file function.json .

È possibile dichiarare i parametri di funzione come tipi seguenti per scrivere nell'archivio BLOB:

  • Stringhe come func.Out[str]
  • Flussi come func.Out[func.InputStream]

Per informazioni dettagliate, vedere l'esempio di output.

Connessioni

La connection proprietà è un riferimento alla configurazione dell'ambiente che specifica come l'app deve connettersi ai BLOB di Azure. Può specificare:

  • Nome di un'impostazione dell'applicazione contenente un stringa di connessione
  • Nome di un prefisso condiviso per più impostazioni dell'applicazione, definendo insieme una connessione basata sull'identità.

Se il valore configurato è una corrispondenza esatta per una singola impostazione e una corrispondenza di prefisso per altre impostazioni, viene usata la corrispondenza esatta.

Stringa di connessione

Per ottenere un stringa di connessione, seguire la procedura illustrata in Gestire le chiavi di accesso dell'account di archiviazione. La stringa di connessione deve essere relativa a un account di archiviazione di uso generico, non a un account di archiviazione BLOB.

Questo stringa di connessione deve essere archiviato in un'impostazione dell'applicazione con un nome corrispondente al valore specificato dalla connection proprietà della configurazione dell'associazione.

Se il nome dell'impostazione dell'app inizia con "AzureWebJobs", è possibile specificare solo il resto del nome. Ad esempio, se si imposta connection su "MyStorage", il runtime di Funzioni cerca un'impostazione dell'app denominata "AzureWebJobsMyStorage". Se si lascia vuoto connection, il runtime di Funzioni di Azure usa la stringa di connessione di archiviazione predefinita nell'impostazione dell'app denominata AzureWebJobsStorage.

Connessioni basate su identità

Se si usa la versione 5.x o successiva dell'estensione (bundle 3.x o versione successiva per gli stack di linguaggi non-.NET), anziché usare un stringa di connessione con un segreto, è possibile che l'app usi un'identità di Microsoft Entra. Per usare un'identità, definire le impostazioni con un prefisso comune che esegue il connection mapping alla proprietà nella configurazione del trigger e dell'associazione.

Se si imposta connection su "AzureWebJobsStorage", vedere Connessione all'archiviazione host con un'identità. Per tutte le altre connessioni, l'estensione richiede le proprietà seguenti:

Proprietà Modello di variabile di ambiente Descrizione Valore di esempio
URI del servizio BLOB <CONNECTION_NAME_PREFIX>__serviceUri1 URI del piano dati del servizio BLOB a cui ci si connette usando lo schema HTTPS. <https:// storage_account_name.blob.core.windows.net>

1 <CONNECTION_NAME_PREFIX>__blobServiceUri può essere usato come alias. Se la configurazione della connessione verrà usata da un trigger BLOB, blobServiceUri deve essere accompagnata anche da queueServiceUri. Vedere di seguito.

Il serviceUri modulo non può essere usato quando la configurazione di connessione complessiva deve essere usata tra BLOB, code e/o tabelle. L'URI può designare solo il servizio BLOB. In alternativa, è possibile fornire un URI specifico per ogni servizio, consentendo l'uso di una singola connessione. Se vengono fornite entrambe le versioni, viene utilizzato il modulo multiservizio. Per configurare la connessione per più servizi, invece di <CONNECTION_NAME_PREFIX>__serviceUri, impostare:

Proprietà Modello di variabile di ambiente Descrizione Valore di esempio
URI del servizio BLOB <CONNECTION_NAME_PREFIX>__blobServiceUri URI del piano dati del servizio BLOB a cui ci si connette usando lo schema HTTPS. <https:// storage_account_name.blob.core.windows.net>
URI del servizio di accodamento (obbligatorio per itrigger BLOB 2) <CONNECTION_NAME_PREFIX>__queueServiceUri URI del piano dati di un servizio di accodamento, usando lo schema HTTPS. Questo valore è necessario solo per i trigger BLOB. <https:// storage_account_name.queue.core.windows.net>

2 Il trigger blob gestisce l'errore tra più tentativi scrivendo BLOB non elaborabili in una coda. serviceUri Nel modulo viene utilizzata la AzureWebJobsStorage connessione. Tuttavia, quando si specifica , è necessario specificare blobServiceUrianche un URI del servizio di accodamento con queueServiceUri. È consigliabile usare il servizio dallo stesso account di archiviazione del servizio BLOB. È anche necessario assicurarsi che il trigger possa leggere e scrivere messaggi nel servizio di accodamento configurato assegnando un ruolo come Collaboratore ai dati della coda di archiviazione.

È possibile impostare altre proprietà per personalizzare la connessione. Vedere Proprietà comuni per le connessioni basate su identità.

Quando sono ospitate nel servizio Azure Functions, le connessioni basate su identità usano una identità gestita. Per impostazione predefinita, viene usata l’identità assegnata a livello di sistema, ma è comunque possibile specificare un’identità assegnata dall’utente a cui siano associate le proprietà credential e clientID. Si noti che la configurazione di un'identità assegnata dall'utente con un ID risorsa non è supportata. Quando viene eseguita in altri contesti, ad esempio lo sviluppo locale, viene usata l'identità dello sviluppatore, anche se può essere personalizzata. Vedere Sviluppo locale con connessioni basate su identità.

Concedere l'autorizzazione all'identità

Qualsiasi identità usata deve avere le autorizzazioni necessarie per eseguire le azioni previste. Per la maggior parte dei servizi di Azure, questo significa che è necessario assegnare un ruolo nel controllo degli accessi in base al ruolo di Azure, usando ruoli predefiniti o personalizzati che forniscono tali autorizzazioni.

Importante

È possibile che alcune autorizzazioni esposte dal servizio di destinazione non siano necessarie per tutti i contesti. Laddove possibile, rispettare il principio dei privilegi minimi e concedere all’identità solo i privilegi necessari. Ad esempio, se l'app deve essere in grado di leggere solo da un'origine dati, usare un ruolo che disponga solo dell'autorizzazione per la lettura. Sarebbe inappropriato assegnare un ruolo che consenta anche la scrittura in tale servizio, in quanto sarebbe eccessiva l'autorizzazione per un'operazione di lettura. Analogamente, è consigliabile assicurarsi che l'assegnazione di ruolo sia con ambito solo sulle risorse che devono essere lette.

È necessario creare un'assegnazione di ruolo che fornisce l'accesso al contenitore BLOB in fase di esecuzione. I ruoli di gestione come proprietario non sono sufficienti. La tabella seguente illustra i ruoli predefiniti consigliati quando si usa l'estensione archiviazione BLOB nel normale funzionamento. L'applicazione potrebbe richiedere ulteriori autorizzazioni in base al codice scritto.

Tipo di associazione Ruoli predefiniti di esempio
Trigger Proprietario dei dati dei BLOB di archiviazione e Collaboratorecoda archiviazione 1

È necessario concedere autorizzazioni aggiuntive anche alla connessione AzureWebJobsStorage.2
Associazione di input Lettore dei dati del BLOB di archiviazione
Associazione di output Proprietario dei dati del BLOB di archiviazione

1 Il trigger BLOB gestisce l'errore tra più tentativi scrivendo BLOB non elaborabili in una coda nell'account di archiviazione specificato dalla connessione.

2 La connessione AzureWebJobsStorage viene usata internamente per BLOB e code che abilitano il trigger. Se è configurato per l'uso di una connessione basata su identità, sono necessarie autorizzazioni aggiuntive oltre il requisito predefinito. Le autorizzazioni necessarie sono coperte dai ruoli Proprietario dei dati del BLOB di archiviazione, Collaboratore ai dati della coda di archiviazione e Collaboratore account di archiviazione. Per altre informazioni, vedere Connessione all'archiviazione host con un'identità.

Eccezioni e codici restituiti

Binding Riferimento
BLOB Codici di errore BLOB
Blob, Table, Queue Codici di errore di archiviazione
Blob, Table, Queue Risoluzione dei problemi

Passaggi successivi