Trigger di Archiviazione BLOB di Azure per Funzioni di Azure

Il trigger di archiviazione BLOB avvia una funzione quando viene rilevato un BLOB nuovo o aggiornato. Il contenuto del BLOB viene fornito come input per la funzione.

Per informazioni dettagliate sulle differenze tra le due implementazioni del trigger di archiviazione BLOB e altre opzioni di attivazione, vedere Uso dei BLOB.

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

Esempio

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

[FunctionName("BlobTriggerCSharp")]        
public static void Run([BlobTrigger("samples-workitems/{name}")] Stream myBlob, string name, ILogger log)
{
    log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name} \n Size: {myBlob.Length} Bytes");
}

@FunctionName("blobprocessor")
public void run(
  @BlobTrigger(name = "file",
               dataType = "binary",
               path = "myblob/{name}",
               connection = "MyStorageAccountAppSetting") byte[] content,
  @BindingName("name") String filename,
  final ExecutionContext context
) {
  context.getLogger().info("Name: " + filename + " Size: " + content.length + " bytes");
}

import { app, InvocationContext } from '@azure/functions';

export async function storageBlobTrigger1(blob: Buffer, context: InvocationContext): Promise<void> {
    context.log(
        `Storage blob function processed blob "${context.triggerMetadata.name}" with size ${blob.length} bytes`
    );
}

app.storageBlob('storageBlobTrigger1', {
    path: 'samples-workitems/{name}',
    connection: 'MyStorageAccountAppSetting',
    handler: storageBlobTrigger1,
});

const { app } = require('@azure/functions');

app.storageBlob('storageBlobTrigger1', {
    path: 'samples-workitems/{name}',
    connection: 'MyStorageAccountAppSetting',
    handler: (blob, context) => {
        context.log(
            `Storage blob function processed blob "${context.triggerMetadata.name}" with size ${blob.length} bytes`
        );
    },
});

{
    "disabled": false,
    "bindings": [
        {
            "name": "myBlob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

module.exports = async function(context) {
    context.log('Node.js Blob trigger function processed', context.bindings.myBlob);
};

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

param([byte[]] $InputBlob, $TriggerMetadata)

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

import logging

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

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

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="BlobTrigger1")
@app.blob_trigger(arg_name="myblob", 
                  path="PATH/TO/BLOB",
                  connection="CONNECTION_SETTING")
def test_function(myblob: func.InputStream):
   logging.info(f"Python blob trigger function processed blob \n"
                f"Name: {myblob.name}\n"
                f"Blob Size: {myblob.length} bytes")

{
    "scriptFile": "__init__.py",
    "disabled": false,
    "bindings": [
        {
            "name": "myblob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

import logging
import azure.functions as func


def main(myblob: func.InputStream):
    logging.info('Python Blob trigger function processed %s', myblob.name)

[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)

[FunctionName("ResizeImage")]
public static void Run(
  [BlobTrigger("sample-images/{name}")] Stream image,
  [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall)
{
  ....
}

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

Per esempi completi, vedere la sezione di esempio.

public static void Run(string myBlob, string blobTrigger, ILogger log)
{
    log.LogInformation($"Full blob path: {blobTrigger}");
} 

context.log(`Full blob path: ${context.triggerMetadata.blobTrigger}`);

module.exports = async function (context, myBlob) {
    context.log("Full blob path:", context.bindingData.blobTrigger);
};

Utilizzo

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

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:

¹ <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:

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

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

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

² 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à.

Modelli di nome BLOB

È possibile specificare un modello di nome di BLOB nella proprietà path in function.json o nel costruttore dell'attributo BlobTrigger. Il modello di nome può essere un'espressione di filtro o di associazione. Le sezioni seguenti forniscono esempi.

Ottenere l'estensione e il nome del file

L'esempio seguente illustra come associare il nome e l'estensione del file BLOB separatamente:

"path": "input/{blobname}.{blobextension}",

Se il BLOB è denominato original-Blob1.txt, i valori delle variabili blobname e blobextension nel codice della funzione saranno original-Blob1 e txt.

Filtrare in base al nome del BLOB

L'esempio seguente attiva un trigger solo per i BLOB nel contenitore input che iniziano con la stringa "original-":

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

Se il nome del BLOB è original-Blob1.txt, il valore della variabile name nel codice della funzione sarà Blob1.txt.

Filtrare in base al tipo di file

L'esempio seguente attiva un trigger solo per i file con estensione png:

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

Filtrare in base alle parentesi graffe nei nomi dei file

Per cercare le parentesi graffe nei nomi dei file, raddoppiare le parentesi graffe per eseguirne l'escape. L'esempio seguente filtra i BLOB che contengono parentesi graffe nel nome:

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

Se il BLOB è denominato {20140101}-soundfile.mp3, il valore della variabile name nel codice della funzione sarà soundfile.mp3.

Polling e latenza

Il polling funziona come ibrido tra l'ispezione dei log e l'esecuzione di analisi periodiche dei contenitori. I BLOB vengono analizzati in gruppi di 10.000 alla volta con un token di continuazione usato tra intervalli. Se l'app per le funzioni è inclusa nel piano a consumo, è possibile che si verifichi un ritardo di un massimo di 10 minuti per l'elaborazione di nuovi BLOB in caso di inattività di un'app per le funzioni.

Se è necessaria un'elaborazione BLOB più veloce o affidabile, è consigliabile passare all'hosting per usare un piano di servizio app con Always On abilitato, con conseguente aumento dei costi. È anche possibile prendere in considerazione l'uso di un trigger diverso dal trigger BLOB di polling classico. Per altre informazioni e un confronto delle varie opzioni di attivazione per i contenitori di archiviazione BLOB, vedere Trigger in un contenitore BLOB.

Conferme di BLOB

Il runtime di Funzioni di Azure verifica che nessuna funzione trigger di BLOB venga chiamata più volte per lo stesso BLOB nuovo o aggiornato. Gestisce conferme di BLOB per determinare se una versione di BLOB specifica è stata elaborata.

Funzioni di Azure archivia le conferme di BLOB in un contenitore denominato azure-webjobs-hosts nell'account di archiviazione di Azure per l'app per le funzioni, specificato dall'impostazione app AzureWebJobsStorage. Una conferma di BLOB contiene le seguenti informazioni:

• Funzione attivata (<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>ad esempio: MyFunctionApp.Functions.CopyBlob)
• Il nome del contenitore
• Tipo di BLOB (BlockBlob o PageBlob)
• Il nome del BLOB
• ETag (identificatore di versione del BLOB, ad esempio: 0x8D1DC6E70A277EF)

Per forzare la rielaborazione di un BLOB è possibile eliminare manualmente la conferma del BLOB dal contenitore azure-webjobs-hosts. Anche se la rielaborazione potrebbe non verificarsi immediatamente, è garantito che si verifichi in un secondo momento. Per rielaborare immediatamente, è possibile aggiornare il BLOB scaninfo in azure-webjobs-hosts/blobscaninfo . Tutti i BLOB con un timestamp dell'ultima modifica dopo che la LatestScan proprietà verrà analizzata di nuovo.

BLOB non elaborabili

Quando una funzione trigger BLOB ha esito negativo per un determinato BLOB, Funzioni di Azure ritenta che funzionano per impostazione predefinita per un totale di cinque volte.

Se tutti i 5 tentativi non riescono, Funzioni di Azure aggiunge un messaggio a una coda di archiviazione denominata webjobs-blobtrigger-poison. Il numero massimo di tentativi è configurabile. La stessa impostazione MaxDequeueCount viene usata per la gestione dei BLOB non elaborabili e per la gestione dei messaggi della coda non elaborabile. Il messaggio di coda per i BLOB non elaborabili è un oggetto JSON che contiene le seguenti proprietà:

• FunctionId (nel formato <FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>)
• BlobType (BlockBlob o PageBlob)
• ContainerName
• BlobName
• ETag (identificatore di versione del BLOB, ad esempio: 0x8D1DC6E70A277EF)

Utilizzo e concorrenza della memoria

L'utilizzo della memoria può essere ulteriormente influenzato quando più istanze di funzione elaborano contemporaneamente i dati BLOB. Se si verificano problemi di memoria usando un trigger BLOB, è consigliabile ridurre il numero di esecuzioni simultanee consentite. Naturalmente, la riduzione della concorrenza può avere l'effetto collaterale dell'aumento del backlog dei BLOB in attesa di elaborazione. I limiti di memoria dell'app per le funzioni dipendono dal piano. Per altre informazioni, vedere Limiti del servizio.

Il modo in cui è possibile controllare il numero di esecuzioni simultanee dipende dalla versione dell'estensione di archiviazione in uso.

I limiti si applicano separatamente a ogni funzione che usa un trigger BLOB.

Proprietà di host.json

Il file host.json contiene impostazioni che controllano il comportamento del trigger BLOB. Per informazioni dettagliate sulle impostazioni disponibili, vedere la sezione impostazioni host.json .

Passaggi successivi

• Leggere i dati di archiviazione BLOB quando viene eseguita una funzione
• Scrivere dati di archiviazione BLOB da una funzione