Persistenza e serializzazione dei dati in Durable Functions per Funzioni di Azure

Il runtime di Durable Functions mantiene automaticamente i parametri della funzione, restituisce valori e altro stato all'hub task per garantire un'esecuzione affidabile. Tuttavia, la quantità e la frequenza dei dati resi persistenti nell'archiviazione durevole possono influire sulle prestazioni dell'applicazione e sui costi delle transazioni di archiviazione. A seconda del tipo di dati archiviati dall'applicazione, potrebbe essere necessario considerare anche i criteri di conservazione e privacy dei dati.

Questo articolo illustra i dati salvati in modo permanente, come gestire payload di grandi dimensioni e dati sensibili e come personalizzare la serializzazione per ogni linguaggio supportato.

Contenuto dell'articolo:

Contenuti dell'hub di attività

L'hub delle attività archivia lo stato corrente delle istanze e i messaggi in sospeso.

  • Gli stati dell'istanza archiviano lo stato corrente e la cronologia di un'istanza. Per le istanze di orchestrazione, questo stato include lo stato di runtime, la cronologia dell'orchestrazione, gli input, gli output e lo stato personalizzato. Per le istanze di entità, include lo stato dell'entità.
  • I messaggi archiviano gli input o gli output della funzione, i payload degli eventi e i metadati usati per scopi interni, ad esempio il routing e la correlazione end-to-end.

I messaggi vengono eliminati dopo l'elaborazione, ma gli stati dell'istanza vengono mantenuti a meno che non vengano eliminati in modo esplicito dall'applicazione o da un operatore. In particolare, una cronologia di orchestrazione rimane in archiviazione anche dopo il completamento dell'orchestrazione.

Per un esempio di come gli stati e i messaggi rappresentano l'avanzamento di un'orchestrazione, vedere l'esempio di esecuzione dell'hub di attività.

La posizione e il modo in cui gli stati e i messaggi vengono rappresentati nell'archiviazione dipendono dal provider di archiviazione. Il provider predefinito di Durable Functions è Archiviazione di Azure, che rende permanenti i dati in code, tabelle e BLOB in un account Archiviazione di Azure specificato.

Tipi di dati serializzati e persistenti

L'elenco seguente mostra i diversi tipi di dati che verranno serializzati e salvati in modo permanente quando si usano le funzionalità di Durable Functions:

  • Tutti gli input e gli output dell'orchestratore, dell'attività e delle funzioni di entità, inclusi gli ID e le eccezioni non gestite
  • Nomi di orchestratore, attività e funzioni di entità
  • Nomi di eventi esterni e carichi utili
  • Payload personalizzato dello stato di orchestrazione
  • Messaggi di terminazione dell'orchestrazione
  • Payload di timer durevoli
  • Gli URL delle richieste e risposte HTTP durevoli, le intestazioni e i payload
  • Payload di chiamata e segnale di entità
  • Payload di stato dell'entità

Per indicazioni sulla gestione delle dimensioni del payload e sulla protezione degli elementi sensibili in questo elenco, vedere le sezioni seguenti.

Mantenere gli input e gli output di Durable Functions ridotti

Se si forniscono input e output di grandi dimensioni da e verso le API di Durable Functions, è possibile che si verifichino problemi di memoria. Gli input e gli output vengono serializzati nella cronologia dell'orchestrazione, il che significa che i payload di grandi dimensioni possono, col tempo, contribuire notevolmente alla crescita illimitata della cronologia. Questa crescita rischia di causare eccezioni di memoria durante la fase di riproduzione.

Per ridurre l'impatto di input e output di grandi dimensioni, è possibile:

  • Delegare il lavoro ai sottorchestratori per bilanciare il carico di memoria della cronologia tra più orchestratori, mantenendo ridotto il footprint di memoria delle singole cronologie.
  • Archiviare dati di grandi dimensioni nell'archiviazione esterna (ad esempio Archiviazione BLOB di Azure) e passare identificatori leggeri che consentono di recuperare i dati all'interno delle funzioni di attività quando necessario.

Se si utilizza il Durable Task Scheduler, è possibile anche utilizzare il supporto per payload di grandi dimensioni per eseguire l'offload di payload più grandi nell'Archiviazione Blob di Azure.

Tip

La procedura consigliata per gestire dati di grandi dimensioni consiste nel mantenerli nell'archiviazione esterna e materializzare i dati solo all'interno delle attività, quando necessario.

Lavorare con i dati sensibili

Gli input e gli output (incluse le eccezioni) sia in ingresso che in uscita dalle Durable Functions API vengono persistentemente memorizzati nel provider di archiviazione a scelta. Se questi input, output o eccezioni contengono dati sensibili (ad esempio segreti, stringhe di connessione o informazioni personali), chiunque abbia accesso in lettura alle risorse del provider di archiviazione potrebbe ottenerli.

Per gestire in modo sicuro i dati sensibili, ottenere i dati all'interno delle funzioni di attività da Azure Key Vault o da variabili di ambiente e non comunicare mai i dati direttamente da o verso orchestratori o entità. Questo approccio consente di evitare la perdita di dati sensibili nelle risorse di archiviazione.

Analogamente, l'accesso in scrittura alle risorse di archiviazione deve essere strettamente controllato, poiché i dati manomessi nell'archiviazione potrebbero modificare il comportamento dell'orchestrazione. Per ulteriori informazioni su come proteggere l'archiviazione del task hub, vedere Proteggere l'archiviazione del task hub.

Tip

Queste indicazioni si applicano anche all'API dell'agente CallHttp di orchestrazione, che rende persistenti i payload di richiesta e risposta nell'archiviazione. Se gli endpoint HTTP di destinazione richiedono l'autenticazione, implementare la chiamata HTTP all'interno di un'attività o usare il supporto predefinito dell'identità gestita offerta da CallHttp, che non rende persistenti le credenziali per l'archiviazione.

Note

Evitare di registrare i dati contenenti segreti come chiunque abbia accesso in lettura ai log (ad esempio in Application Insights) potrebbe ottenere tali segreti.

Crittografia di dati inattivi

Quando si utilizza il provider di Archiviazione di Azure, tutti i dati vengono crittografati automaticamente a riposo. Tuttavia, chiunque abbia accesso all'account di archiviazione può leggere i dati nel formato non crittografato. Se è necessaria una protezione più avanzata per i dati sensibili, è consigliabile prima crittografare i dati usando chiavi di crittografia personalizzate in modo che i dati vengano salvati in modo permanente nel formato pre-crittografato.

In alternativa, gli utenti di .NET hanno l'opzione di implementare provider di serializzazione personalizzati che forniscono la crittografia automatica. Un esempio di serializzazione personalizzata con crittografia è disponibile in questo esempio di GitHub.

Note

Se si decide di implementare la crittografia a livello di applicazione, tenere presente che le orchestrazioni e le entità possono esistere per quantità illimitate di tempo. Questo aspetto è importante quando si tratta di ruotare le chiavi di crittografia perché un'orchestrazione o delle entità possono operare più a lungo dei criteri di rotazione delle chiavi. Se si verifica una rotazione delle chiavi, la chiave usata per crittografare i dati potrebbe non essere più disponibile per decrittografarli alla successiva esecuzione dell'orchestrazione o dell'entità. Pertanto, si consiglia di utilizzare la crittografia personalizzata solo quando si prevede che le orchestrazioni e le entità vengano eseguite per periodi di tempo relativamente brevi.

Proteggi l'archiviazione dell'hub delle attività

Il backend di archiviazione che ospita il task hub è un confine di attendibilità critico. Durable Task Framework considera affidabili i dati letti dall'archiviazione durante la riesecuzione dell'orchestrazione e l'elaborazione dei messaggi. Chiunque abbia accesso in scrittura all'archiviazione dell'hub delle attività può manomettere lo stato di orchestrazione, i messaggi in sospeso o i dati archiviati. Ciò può modificare il comportamento dell'applicazione, attivare azioni indesiderate o ottenere l'esecuzione di codice remoto all'interno del contesto dell'app per le funzioni.

Importante

Non esporre le credenziali di archiviazione del Task Hub né concedere l'accesso in scrittura a soggetti non attendibili. L'accesso in scrittura all'archivio del task hub può essere usato per alterare il comportamento dell'applicazione, compresa l'esecuzione di codice arbitrario.

Responsabilità condivisa

La protezione del back-end di archiviazione è responsabilità dell'utente, come la protezione di qualsiasi database che archivia lo stato o il codice dell'applicazione. Durable Task Framework non esegue la verifica dell'integrità sui dati archiviati, quindi si basa sui controlli di accesso del livello di archiviazione per impedire modifiche non autorizzate.

Se si utilizza il Durable Task Scheduler, il backend di archiviazione è completamente gestito e protetto dal servizio, tramite autenticazione dell'identità gestita e controllo degli accessi basato sui ruoli (RBAC). Per i back-end di archiviazione BYO (Bring Your Own Storage), ad esempio Archiviazione di Azure, MSSQL o Netherite, è necessario proteggere manualmente le risorse di archiviazione sottostanti.

Note

Non condividere un unico hub di attività tra tenant non attendibili. Un hub attività non impone limiti di accesso tra gli utenti, quindi qualsiasi tenant in grado di leggere o scrivere nell'hub attività può influire su tutte le orchestrazioni e le entità all'interno di esso. Allo stesso modo, non fare affidamento su hub di attività separati all'interno dello stesso backend come limite di sicurezza. Anche se Durable Task Scheduler supporta il RBAC con ambito limitato ai singoli task hub, i controlli di rete, come gli elenchi di indirizzi IP consentiti e gli endpoint privati, si applicano solo a livello di scheduler, quindi i task hub all'interno di uno scheduler non costituiscono un confine di isolamento della sicurezza. Lo stesso vale per i provider di archiviazione BYO: qualsiasi tenant con accesso all'account di archiviazione o al database può raggiungere tutti gli hub di attività in tale back-end. Quando è necessario un isolamento a livello di sicurezza tra tenant, eseguire il provisioning di un'infrastruttura separata per ogni tenant: account di archiviazione o database separati per i provider BYO, oppure istanze separate di Durable Task Scheduler.

Lista di controllo per l'irrobustimento dell'archiviazione

Applica le seguenti buone pratiche per proteggere lo spazio di archiviazione dell'hub di attività:

  • Usare connessioni basate su identità anziché stringhe di connessione con chiavi di archiviazione. Le identità gestite forniscono un controllo di accesso granulare ed eliminano il rischio di perdita di credenziali. Vedere Configurare un'identità gestita per Durable Functions.
  • Applicare ruoli RBAC con privilegi minimi. Concedere solo le autorizzazioni minime necessarie. Evitare di concedere l'accesso all'account di archiviazione generale a utenti o servizi che non ne hanno bisogno.
  • Limita l'accesso di rete al tuo account di archiviazione tramite endpoint privati o endpoint di servizio. In questo modo si impedisce l'accesso non autorizzato a livello di rete ai dati dell'hub attività.
  • Monitora l'accesso all'archiviazione abilitando i log delle risorse Monitoraggio di Azure per l'account di archiviazione, in particolare la categoria di log StorageWrite. Indirizzare questi log a una destinazione esterna all'account di archiviazione monitorato, ad esempio Log Analytics, in modo che non possano essere manomessi. Vedere Log di archiviazione.
  • Ruotare le credenziali regolarmente se si usano stringhe di connessione. Trattate le chiavi dell'account di archiviazione con la stessa cura riservata a qualsiasi altra credenziale con privilegi elevati.
  • Si consideri un back-end di archiviazione gestito. Durable Task Scheduler gestisce automaticamente la sicurezza dell'archiviazione, tra cui crittografia, autenticazione e isolamento di rete.

Personalizzare la serializzazione e la deserializzazione

Le opzioni di personalizzazione della serializzazione variano in base alla lingua. Selezionare la scheda lingua per visualizzare le opzioni disponibili.

Logica di serializzazione predefinita

Durable Functions in-process per .NET utilizza internamente Json.NET per serializzare i dati di orchestrazione e delle entità in JSON. Le impostazioni Json.NET predefinite usate sono:

Ingressi, uscite e stati:

JsonSerializerSettings
{
    TypeNameHandling = TypeNameHandling.None,
    DateParseHandling = DateParseHandling.None,
}

Eccezioni:

JsonSerializerSettings
{
    ContractResolver = new ExceptionResolver(),
    TypeNameHandling = TypeNameHandling.Objects,
    ReferenceLoopHandling = ReferenceLoopHandling.Ignore,
}

Leggere la documentazione più dettagliata qui JsonSerializerSettings.

Personalizzare la serializzazione con attributi .NET

Durante la serializzazione, Json.NET cerca vari attributi su classi e proprietà che controllano il modo in cui i dati vengono serializzati e deserializzati da JSON. Se si è proprietari del codice sorgente per il tipo di dati passato alle API Durable Functions, è consigliabile aggiungere questi attributi al tipo per personalizzare la serializzazione e la deserializzazione.

Personalizzare la serializzazione con iniezione delle dipendenze

Le app per le funzioni destinate a .NET ed eseguite nel runtime di Funzioni V3 possono usare Dependency Injection (DI) per personalizzare la modalità di serializzazione dei dati e delle eccezioni. Il seguente codice di esempio dimostra come utilizzare il Dependency Injection per eseguire l'override delle impostazioni di serializzazione predefinite di Json.NET, utilizzando implementazioni personalizzate delle interfacce dei servizi IMessageSerializerSettingsFactory e IErrorSerializerSettingsFactory.

using Microsoft.Azure.Functions.Extensions.DependencyInjection;
using Microsoft.Azure.WebJobs.Extensions.DurableTask;
using Microsoft.Extensions.DependencyInjection;
using Newtonsoft.Json;
using System.Collections.Generic;

[assembly: FunctionsStartup(typeof(MyApplication.Startup))]
namespace MyApplication
{
    public class Startup : FunctionsStartup
    {
        public override void Configure(IFunctionsHostBuilder builder)
        {
            builder.Services.AddSingleton<IMessageSerializerSettingsFactory, CustomMessageSerializerSettingsFactory>();
            builder.Services.AddSingleton<IErrorSerializerSettingsFactory, CustomErrorSerializerSettingsFactory>();
        }

        /// <summary>
        /// A factory that provides the serialization for all inputs and outputs for activities and
        /// orchestrations, as well as entity state.
        /// </summary>
        internal class CustomMessageSerializerSettingsFactory : IMessageSerializerSettingsFactory
        {
            public JsonSerializerSettings CreateJsonSerializerSettings()
            {
                // Return your custom JsonSerializerSettings here
            }
        }

        /// <summary>
        /// A factory that provides the serialization for all exceptions thrown by activities
        /// and orchestrations
        /// </summary>
        internal class CustomErrorSerializerSettingsFactory : IErrorSerializerSettingsFactory
        {
            public JsonSerializerSettings CreateJsonSerializerSettings()
            {
                // Return your custom JsonSerializerSettings here
            }
        }
    }
}

Passaggi successivi

  • Last updated on