Condividi tramite

Gestione delle variabili per frammenti di criteri

SI APPLICA A: Tutti i livelli di Gestione API

Le variabili di contesto consentono la condivisione dei dati tra frammenti di criteri per scenari di pipeline avanzati. La gestione corretta delle variabili è fondamentale per la creazione di pipeline affidabili con prestazioni ottimali. La gestione non corretta può causare errori di runtime, problemi di prestazioni e comportamento imprevedibile.

Nozioni fondamentali sulle variabili

Le variabili di contesto forniscono la condivisione dei dati thread-safe tra frammenti di criteri e vengono create usando i criteri set-variable predefiniti. Ogni richiesta mantiene il proprio contesto variabile isolato, assicurandosi che le richieste simultanee non interferiscano tra loro.

Gestione del ciclo di vita delle variabili

  • Ambito della richiesta: le variabili esistono solo per la durata di una singola richiesta e vengono automaticamente raccolte al termine della richiesta.

  • Persistenza della fase: le variabili impostate nella fase in ingresso rimangono disponibili in tutte le fasi back-end, in uscita e di errore all'interno della stessa richiesta.

  • Isolamento del thread: l'isolamento del thread rigoroso garantisce che ogni richiesta venga eseguita nel proprio thread con il proprio oggetto di contesto, impedendo l'interferenza dei dati tra richieste.

  • Aggiornamenti sequenziali: qualsiasi frammento può modificare le variabili esistenti, con frammenti successivi sovrascrivendo i valori precedenti. L'esecuzione sequenziale elimina la necessità di meccanismi di blocco.

  • Soglia di archiviazione: la piattaforma ottimizza la gestione delle variabili di contesto per le raccolte di piccole dimensioni, in genere 50 variabili per richiesta o meno.

Impostare e recuperare variabili in frammenti

<!-- Example: Set a request-id context variable that is a required value for other fragments -->
<set-variable name="request-id" value="@{
    var requestId = context.Request.Headers.GetValueOrDefault("X-Request-ID", "");
    if (string.IsNullOrEmpty(requestId)) {
        return Guid.NewGuid().ToString();
    }
    return requestId;
}" />

<!-- Example: Retrieve the same request-id context variable safely in another fragment -->
<set-header name="X-Correlation-ID" value="@{
    return context.Variables.GetValueOrDefault<string>("request-id", "unknown");
}" />

Procedure consigliate

Utilizzare metodi sicuri per l'accesso alle variabili

Prestare sempre attenzione con i valori Null potenziali, usare l'accesso sicuro con GetValueOrDefaulte fornire valori predefiniti significativi per l'accesso a tutte le variabili:

<!-- Safe access with default value -->
<set-variable name="log-level" value="@{
    return context.Variables.GetValueOrDefault<string>("config-log-level", "INFO");
}" />

<!-- Safe string interpolation using GetValueOrDefault -->
<set-variable name="cache-key" value="@{
    var userId = context.Variables.GetValueOrDefault<string>("auth-user-id", "anon");
    var resource = context.Variables.GetValueOrDefault<string>("request-resource", "default");
    
    return $"cache:{userId}:{resource}";
}" />

Controllare l'esistenza della variabile

Assicurarsi che le variabili create dai frammenti dei prerequisiti esistano prima di accedervi. Quando mancano le dipendenze, scegliere tra due strategie:

Strategia 1: Fallire velocemente (dipendenze critiche)

Restituisce una risposta di errore quando mancano le dipendenze critiche:

<choose>
    <when condition="@(!context.Variables.ContainsKey("user-id"))">
        <!-- Critical dependency missing - fail immediately -->
        <return-response>
            <set-status code="500" reason="Internal Server Error" />
            <set-body>{"error": "Required variable missing", "missing_dependency": "user-id"}</set-body>
        </return-response>
    </when>
    <otherwise>
        <!-- Safe to proceed - use the user-id variable -->
        <set-header name="X-User-ID" exists-action="override">
            <value>@(context.Variables.GetValueOrDefault<string>("user-id", ""))</value>
        </set-header>
    </otherwise>
</choose>

Strategia 2: Gestire correttamente (dipendenze facoltative)

Continuare l'esecuzione con il comportamento di fallback appropriato quando mancano dipendenze facoltative:

<choose>
    <when condition="@(context.Variables.ContainsKey("user-id"))">
        <!-- Optional variable available - use it -->
        <set-header name="X-User-ID" exists-action="override">
            <value>@(context.Variables.GetValueOrDefault<string>("user-id", ""))</value>
        </set-header>
    </when>
    <otherwise>
        <!-- Fallback to default when variable unavailable -->
        <set-header name="X-User-ID" exists-action="override">
            <value>unknown</value>
        </set-header>
    </otherwise>
</choose>

Ridurre al minimo l'accesso alle variabili

Ridurre le ricerche delle variabili di contesto consolidando più accessi in singole espressioni:

<!-- Good: Single consolidated access -->
<set-variable name="log-entry" value="@{
    var level = context.Variables.GetValueOrDefault<string>("log-level", "INFO");
    var requestId = context.Variables.GetValueOrDefault<string>("request-id", "unknown");
    return $"[{level}] Request {requestId} completed";
}" />

<!-- Avoid: Multiple separate accesses -->
<set-variable name="level-prefix" value="@("[" + context.Variables.GetValueOrDefault<string>("log-level", "INFO") + "]")" />
<set-variable name="request-suffix" value="@("Request " + context.Variables.GetValueOrDefault<string>("request-id", "unknown") + " completed")" />
<set-variable name="log-entry" value="@(context.Variables.GetValueOrDefault<string>("level-prefix", "") + " " + context.Variables.GetValueOrDefault<string>("request-suffix", ""))" />

Mantenere tipi coerenti

Usare la gestione esplicita dei tipi per ottenere prestazioni e affidabilità ottimali. Quando si utilizzano espressioni di criteri, specificare il tipo previsto con l'operatore @() :

<!-- Set as boolean, use as boolean -->
<set-variable name="should-log-debug" value="@(true)" />
<choose>
    <when condition="@(context.Variables.GetValueOrDefault<bool>("should-log-debug", false))">
        <!-- Include detailed debug information in logs -->
    </when>
</choose>

Contenuti correlati

  • Last updated on