Freigeben über

Variable Verwaltung für Richtlinienfragmente

GILT FÜR: Alle API Management-Ebenen

Kontextvariablen ermöglichen das Teilen von Daten zwischen Richtlinienfragmenten in fortgeschrittenen Pipeline-Szenarien. Die ordnungsgemäße Variablenverwaltung ist entscheidend für die Erstellung zuverlässiger Pipelines mit optimaler Leistung. Falsche Behandlung kann zu Laufzeitfehlern, Leistungsproblemen und unvorhersehbarem Verhalten führen.

Variablengrundsätze

Kontextvariablen ermöglichen eine threadsichere Datenfreigabe zwischen Richtlinienfragmenten und werden mit der integrierten set-variable Richtlinie erstellt. Jede Anforderung verwaltet einen eigenen isolierten Variablenkontext, um sicherzustellen, dass gleichzeitige Anforderungen nicht miteinander stören.

Verwaltung des variablen Lebenszyklus

  • Anforderungsbereich: Variablen existieren nur während einer einzigen Anfrage und werden automatisch freigegeben, wenn die Anfrage abgeschlossen ist.

  • Phasenpersistenz: Variablen, die in der eingehenden Phase festgelegt sind, bleiben in der back-End-, ausgehenden und Fehlerphase innerhalb derselben Anforderung verfügbar.

  • Threadisolation: Die strenge Threadisolation stellt sicher, dass jede Anforderung in einem eigenen Thread mit einem eigenen Kontextobjekt ausgeführt wird, was eine Übergreifende Anforderungsdateneinmischung verhindert.

  • Sequenzielle Aktualisierungen: Jedes Fragment kann vorhandene Variablen ändern, wobei nachfolgende Fragmente vorherige Werte überschreiben. Die sequenzielle Ausführung beseitigt die Notwendigkeit von Sperrmechanismen.

  • Speicherschwellenwert: Die Plattform optimiert die Kontextvariablenverwaltung für kleine Sammlungen, in der Regel 50 Variablen pro Anforderung oder weniger.

Festlegen und Abrufen von Variablen in Fragmenten

<!-- 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");
}" />

Bewährte Methoden

Verwenden Sie sicheren Variablenzugriff

Seien Sie immer vorsichtig mit potenziellen NULL-Werten, verwenden Sie sicheren Zugriff GetValueOrDefault, und stellen Sie aussagekräftige Standardwerte für den gesamten variablen Zugriff bereit:

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

Überprüfen der Variablenexistenz

Stellen Sie sicher, dass variablen, die durch erforderliche Fragmente erstellt wurden, vorhanden sind, bevor Sie darauf zugreifen. Wenn Abhängigkeiten fehlen, wählen Sie aus zwei Strategien aus:

Strategie 1: Schnell scheitern (kritische Abhängigkeiten)

Gibt eine Fehlerantwort zurück, wenn kritische Abhängigkeiten fehlen:

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

Strategie 2: Geschmeidig umgehen (optionale Abhängigkeiten)

Setzen Sie die Ausführung mit dem entsprechenden Fallbackverhalten fort, wenn optionale Abhängigkeiten fehlen:

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

Minimieren des Variablenzugriffs

Reduzieren Sie Kontextvariablen-Nachschlagevorgänge, indem Sie mehrere Zugriffe in einzelne Ausdrücke konsolidieren:

<!-- 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", ""))" />

Beibehalten konsistenter Typen

Verwenden Sie explizite Typbehandlung für optimale Leistung und Zuverlässigkeit. Geben Sie beim Arbeiten mit Richtlinienausdrücken den erwarteten Typ mit dem @() Operator an:

<!-- 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>

Verwandte Inhalte

  • Last updated on