Condividi tramite

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

  • Articolo

L'associazione di input consente di leggere i dati di archiviazione BLOB come input in una funzione di Azure.

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

Importante

Questo articolo usa schede per supportare le versioni diverse 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 gli sviluppatori di Node.js per Funzioni di Azure. Altre informazioni sulle differenze tra i modelli v3 e v4 sono disponibili nella 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.

    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, ricerca del nome BLOB da una stringa di query

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[].

  @FunctionName("getBlobSizeHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage blobSize(
    @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,
    final ExecutionContext context) {
      // 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, ricezione del nome BLOB da un messaggio in coda

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[].

  @FunctionName("getBlobSize")
  @StorageAccount("Storage_Account_Connection_String")
  public void blobSize(
    @QueueTrigger(
      name = "filename", 
      queueName = "myqueue-items-sample") 
    String filename,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{queueTrigger}") 
    byte[] content,
    final ExecutionContext context) {
      context.getLogger().info("The size of \"" + filename + "\" is: " + content.length + " bytes");
  }

Nella libreria di runtime di funzioni Java, usare @BlobInput l'annotazione per i parametri il cui valore deriva da BLOB. Questa annotazione è utilizzabile con i tipi Java nativi, con oggetti POJO o con valori nullable tramite Optional<T>.

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 mostra un'associazione di input BLOB, definita nel file function.json , che rende i dati BLOB in ingresso disponibili per la funzione PowerShell .

Ecco la configurazione json:

{
  "bindings": [
    {
      "name": "InputBlob",
      "type": "blobTrigger",
      "direction": "in",
      "path": "source/{name}",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

Ecco il codice della funzione:

# Input bindings are passed in via param block.
param([byte[]] $InputBlob, $TriggerMetadata)

Write-Host "PowerShell Blob trigger: Name: $($TriggerMetadata.Name) Size: $($InputBlob.Length) bytes"

Questo esempio usa i tipi SDK per accedere direttamente all'oggetto sottostante BlobClient fornito dall'associazione di input dell'archiviazione BLOB:

import logging

import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
@app.route(route="file")
@app.blob_input(
    arg_name="client", path="PATH/TO/BLOB", connection="AzureWebJobsStorage"
)
def blob_input(req: func.HttpRequest, client: blob.BlobClient):
    logging.info(
        f"Python blob input function processed blob \n"
        f"Properties: {client.get_blob_properties()}\n"
        f"Blob content head: {client.download_blob().read(size=1)}"
    )
    return "ok"

Per esempi di uso di altri tipi di SDK, vedere gli ContainerClient esempi e StorageStreamDownloader .

Per altre informazioni, tra cui come abilitare le associazioni dei tipi di SDK nel progetto, vedere Associazioni dei tipi di SDK.

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 attributi per definire la funzione. Lo script C# usa invece un file di configurazione function.json come descritto nella guida per gli script C#.

Il processo di lavoro isolato definisce un'associazione di input usando un BlobInputAttribute attributo , che 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.
data_type 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 @BlobInput 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 input.

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 input.storageBlob() metodo .

Proprietà Descrizione
path Percorso del 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à di function.json Descrizione
type Deve essere impostato su blob.
direction Deve essere impostato su in. Le eccezioni sono indicate nella sezione usage.
name Nome della variabile che rappresenta il BLOB nel codice della funzione.
path Percorso del BLOB.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi ai BLOB di Azure. Vedere Connessioni.
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 esempi completi, vedere la sezione di esempio.

Utilizzo

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

Quando si vuole che la funzione elabori un singolo BLOB, l'associazione di input 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 Quando un BLOB contiene dati JSON, Funzioni tenta di deserializzare i dati JSON in un tipo POCO (Plain-Old CLR Object).
Flusso1 Flusso di input del contenuto del BLOB.
BlobClient1,
BlockBlobClient1,
PageBlobClient1,
AppendBlobClient1,
BlobBaseClient1		 Un client connesso al BLOB. Questo set di tipi offre il maggior controllo per l'elaborazione del BLOB e può essere usato per eseguire il writeback in esso se la connessione dispone di autorizzazioni sufficienti.

Quando si vuole che la funzione elabori più BLOB da un contenitore, l'associazione di input BLOB può essere associata ai tipi seguenti:

Tipo Descrizione
T[] o List<T> dove T è uno dei singoli tipi di associazione di input BLOB Matrice o elenco di più BLOB. Ogni voce rappresenta un BLOB dal contenitore. È anche possibile eseguire il binding a qualsiasi interfaccia implementata da questi tipi, ad esempio IEnumerable<T>.
BlobContainerClient1 Un client connesso al contenitore. Questo tipo offre il maggior controllo per l'elaborazione del contenitore e può essere usato per scrivervi se la connessione dispone di autorizzazioni sufficienti.

1 Per usare questi tipi, è necessario fare riferimento a Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 o versione successiva e alle dipendenze comuni per le associazioni di tipi SDK.

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 @BlobInput 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 input.

Accedere ai dati BLOB usando context.extraInputs.get().

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

Accedere ai dati BLOB tramite il parametro digitato come InputStream. Per informazioni dettagliate, vedere l'esempio di input.

Funzioni supporta anche i binding dei tipi di PYTHON SDK per l'archiviazione BLOB di Azure, che consente di usare i dati BLOB usando questi tipi di SDK sottostanti:

Importante

Il supporto dei tipi SDK per Python è attualmente disponibile in anteprima ed è supportato solo per il modello di programmazione Python v2. Per altre informazioni, vedere Tipi di SDK in Python.

Connessioni

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

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

Stringa di connessione

Per ottenere una stringa di connessione, seguire la procedura descritta 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 fornisca l'accesso al contenitore BLOB in fase di esecuzione. I ruoli di gestione come Proprietario non sono sufficienti. Nella tabella seguente vengono illustrati i ruoli predefiniti consigliati quando si usa l'estensione Archiviazione BLOB in condizioni di normale funzionamento. L'applicazione potrebbe richiedere ulteriori autorizzazioni in base al codice scritto.

Tipo di associazione Ruoli predefiniti di esempio
Trigger Proprietario dei dati del BLOB di archiviazione e Collaboratore ai dati della coda di archiviazione1

È 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 dell'account di archiviazione. Per altre informazioni, vedere Connessione all'archiviazione host con un'identità.

Passaggi successivi