Politika parçaları için değişken yönetimi

UYGULANANLAR: Tüm API Management katmanları

Bağlam değişkenleri , gelişmiş işlem hattı senaryoları için ilke parçaları arasında veri paylaşımını sağlar. Uygun değişken yönetimi, en iyi performansa sahip güvenilir işlem hatları oluşturmak için kritik öneme sahiptir. Hatalı işleme çalışma zamanı hatalarına, performans sorunlarına ve öngörülemeyen davranışlara yol açabilir.

Değişken temelleri

Bağlam değişkenleri, ilke parçaları arasında iş parçacığı güvenli veri paylaşımını sağlar ve yerleşik set-variable ilkesi kullanılarak oluşturulur. Her istek kendi yalıtılmış değişken bağlamını korur ve eşzamanlı isteklerin birbiriyle karışmamasını sağlar.

Değişken yaşam döngüsü yönetimi

• İstek kapsamı: Değişkenler yalnızca tek bir istek sırasında bulunur ve istek tamamlandığında otomatik olarak çöp olarak toplanır.

• Aşama kalıcılığı: Gelen aşamada ayarlanan değişkenler, aynı istek içinde arka uç, giden ve hata aşaması boyunca kullanılabilir durumda kalır.

• İş parçacığı yalıtımı: Katı iş parçacığı yalıtımı, her isteğin kendi bağlam nesnesiyle kendi iş parçacığında çalışmasını sağlayarak istekler arası veri girişimini önler.

• Sıralı güncelleştirmeler: Herhangi bir parça mevcut değişkenleri değiştirebilir ve sonraki parçalar önceki değerlerin üzerine yazılabilir. Sıralı yürütme, kilitleme mekanizmaları gereksinimini ortadan kaldırır.

• Depolama eşiği: Platform, bağlam değişkeni yönetimini genellikle istek başına 50 veya daha az değişken olmak üzere küçük koleksiyonlar için iyileştirir.

Parçalarda değişken atama ve çağırma

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

En iyi yöntemler

Güvenli değişken erişimini kullanma

Her zaman olası null değerlerle dikkatli olun, GetValueOrDefault ile güvenli erişim kullanın ve tüm değişken erişimlerinde anlamlı varsayılan değerler sağlayın.

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

Değişken varlığını denetleme

Önkoşul parçaları tarafından oluşturulan değişkenlerin bunlara erişmeden önce mevcut olduğundan emin olun. Bağımlılıklar eksik olduğunda iki strateji arasından seçim yapın:

Strateji 1: Hızlı başarısız (kritik bağımlılıklar)

Kritik bağımlılıklar eksik olduğunda bir hata yanıtı döndür:

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

Strateji 2: Düzgün bir şekilde işleme (isteğe bağlı bağımlılıklar)

İsteğe bağlı bağımlılıklar eksik olduğunda uygun geri dönüş davranışıyla yürütmeye devam edin:

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

Değişken erişimini en aza indirme

Birden çok erişimi tek ifadeler halinde birleştirerek bağlam değişkeni aramalarını azaltın:

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

Tutarlı türleri koruma

En iyi performans ve güvenilirlik için açık tür işlemeyi kullanın. İlke ifadeleriyle çalışırken, beklenen türü işleçle @() belirtin:

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

İlgili içerik

• Politika parçalarıyla gelişmiş yürütme işlem hatları oluşturmaya yönelik mimari - Belirgin bir görev ayrımı yaparak modüler, ölçeklenebilir politika parçası mimarileri tasarlamaya yönelik temel desenler.
• İlke parçaları için merkezi meta veri önbelleği - Parçalar arasında paylaşılan meta veri önbelleğe alma desenleri için uygulama kılavuzu.
• Politika ekleme ve kesitlerle koordinasyon - Kesit ekleme desenleri ve ürün ile API politikaları arasındaki koordinasyon.