Parçalarla politika yürütme

UYGULANANLAR: Tüm API Management katmanları

İstek ve yanıt yaşam döngüsü boyunca özel davranışa sahip gelişmiş işlem hattı senaryoları, ilke parçaları kullanılarak oluşturulur. Ürün ve API düzeylerindeki merkezi ilkeler , include-fragment ilkesini kullanarak parçalar ekler. Parçalar, sorumlulukların net bir şekilde ayrılmasını sağlarken yinelemeyi önlemek için ürün ve API ilkeleri arasında paylaşılabilir.

Parça ekleme

Parça eklemek için merkezi ilkeleri kullanma

Ürün ve API ilke tanımları, tam istek ve yanıt işlem hattını oluşturmak için belirli bir sırada parça ekleyen düzenleyiciler olarak görev alır. Aşağıdaki örnekte, bir ilke tanımı tarafından eklenen parçalar gösterilmektedir:

<policies>
  <inbound>
    <include-fragment fragment-id="security-context" />
    <include-fragment fragment-id="rate-limiting" />
    <include-fragment fragment-id="request-logging" />
    <base />
  </inbound>
  <backend>
    <include-fragment fragment-id="backend-selection" />
    <base />
  </backend>
  <outbound>
    <include-fragment fragment-id="circuit-breaker" />
    <base />
  </outbound>
  <on-error>
    <include-fragment fragment-id="error-response" />
  </on-error>
</policies>

Temel kavramlar

• Sıralı sıra: Parçalar dahil edildikleri sırayla yürütülür.
• Aşama yerleştirme: Parçalar, işlevlerine göre uygun ilke aşamalarına (gelen, arka plan, giden, hata olduğunda) eklenir.
• Bağımlılık yönetimi: Sonraki parçalar, dizideki önceki parçalar tarafından ayarlanan bağlam değişkenlerini kullanabilir.

En iyi yöntemler

Kapsamı temel alan parçalar ekleme

Parça sorumluluklarını kapsama göre bölerek ürün ve API ilkelerinin birlikte etkili bir şekilde çalıştığından emin olun:

• Ürün ilkesi: Ürünler arasında farklılık gösteren ürüne özgü davranışlar gerçekleştiren parçalar ekler.
• API ilkesi: Tüm ürünlere uygulanan parçaları ekler.

Yinelemeyi önlemek için parçaları yeniden kullanma

Aynı parçayı yeniden kullanarak ürün ve API ilkeleri arasında aynı mantık gerektiğinde yinelemeyi ortadan kaldırın. Bu örnekte parça circuit-breaker yeniden kullanılır:

<!-- Product Policy -->
<policies>
  <inbound>
    <include-fragment fragment-id="security-context" />
    <include-fragment fragment-id="rate-limiting" />
    <base />
  </inbound>
  <backend>
    <include-fragment fragment-id="backend-selection" />
    <base />
  </backend>
  <outbound>
    <include-fragment fragment-id="circuit-breaker" />
    <base />
  </outbound>
</policies>

<!-- API Policy -->
<policies>
  <inbound>
    <include-fragment fragment-id="request-logging" />
    <base />
  </inbound>
  <outbound>
    <include-fragment fragment-id="circuit-breaker" />
    <base />
  </outbound>
</policies>

Parça bağımlılıklarını ve veri sözleşmelerini belgele

Hangi parçaların ve değişkenlerin gerekli olduğunu netleştirmek için her parçadaki bağımlılık ilişkilerini ve veri sözleşmelerini belgele. Şunları belirtmek için açıklamaları kullanın:

• Bağımlılıklar: Bu parçadan önce yürütülmesi gereken diğer parçalar
• Gerekli: Bu parça yürütülmeden önce mevcut olması gereken bağlam değişkenleri
• Üretir: Bu parçanın aşağı akış parçaları için ürettiği bağlam değişkenleri

<fragment fragment-id="rate-limiting-fragment">
  <!-- Dependencies: security-context-fragment, config-cache-fragment -->
  <!-- Requires: subscription-key variables -->
  <!-- Produces: rate-limit-applied, rate-limit-remaining variables -->
  
  <!-- Verify dependencies before execution -->
  <choose>
    <when condition="@(!context.Variables.ContainsKey("subscription-key"))">
      <return-response>
        <set-status code="500" reason="Internal Server Error" />
        <set-body>Rate limiting requires security context</set-body>
      </return-response>
    </when>
  </choose>
  
  <!-- Rate limiting logic -->
  <set-variable name="rate-limit-applied" value="@(true)" />
  <set-variable name="rate-limit-remaining" value="@(95)" />
</fragment>

Koşullu parça eklemesini kullanın

İstek özelliklerine, yapılandırma ayarlarına veya çalışma zamanı bağlamlarına göre parçaları dinamik olarak dahil etmek için merkezi ilkeler içinde koşullu mantık uygulayın. Bu düzen, farklı senaryolara uyum sağlayan esnek işleme işlem hatlarını etkinleştirir:

<!-- Product Policy -->
<policies>
  <inbound>
    <include-fragment fragment-id="config-cache" />
    <include-fragment fragment-id="request-analysis" />
    
    <!-- Conditional authentication with custom logic based on request type -->
    <choose>
      <when condition="@(context.Request.Headers.GetValueOrDefault("Authorization", "").StartsWith("Bearer"))">
        <include-fragment fragment-id="security-jwt" />
      </when>
      <otherwise>
        <include-fragment fragment-id="security-api-key" />
      </otherwise>
    </choose>
    
    <base />
  </inbound>
</policies>

Parçalar arasında istek gövdesini koruma

Parçaların işlenmek üzere istek gövdesini okuması gerektiğinde (meta verileri ayıklama veya doğrulama gibi), her zaman istek gövdesinin aşağı akış parçaları ve arka uç iletme için kullanılabilir durumda kaldığından emin olmak için kullanın preserveContent: true :

<set-variable name="request-metadata" value="@{
  try {
    // CRITICAL: preserveContent: true ensures body remains available for other fragments and backend
    var body = context.Request.Body.As<string>(preserveContent: true);
    var requestData = JObject.Parse(body);
    
    // Extract metadata without consuming the body
    return new JObject {
      ["user-id"] = requestData["user"]?.ToString() ?? "anonymous"
    };
  } catch {
    return new JObject();
  }
}" />

preserveContent: true olmadan, istek gövdesini okumak onu tüketir ve bu da daha sonraki parçalar veya arka plan hizmetleri için kullanılamaz hale getirir.

Test etme ve hata ayıklama

Parça işlem hattının etkili hata ayıklaması, yürütme akışını ve değişken durumunu anlamak için sistematik bir yaklaşım gerektirir. Bu bölümde, istek işleme görünürlüğünü en üst düzeye çıkarırken performans etkisini en aza indiren hata ayıklama yaklaşımları gösterilmektedir.

Debug üst bilgilerini etkinleştir

İşlem hattının belirli bir noktasında değişken durumunu yakalamak için sorun giderme amacıyla hata ayıklama başlıklarını kullanın. Hata ayıklama üst bilgileri HTTP yanıt üst bilgilerinde görünür ve API istemcileri tarafından görülebilir. Parçalar genelinde tek tek hata ayıklama üst bilgileri eklemek yerine, tüm hata ayıklama üst bilgilerini tek bir konumda bir araya getiren ayrılmış bir üst bilgi yönetim parçası oluşturun. Bu merkezi yaklaşım tutarlılık sağlar ve sürdürülebilirliği artırır.

<!-- Example: Dedicated header fragment -->
<fragment fragment-id="debug-headers">
  <!-- Debug headers for troubleshooting -->
  <set-header name="X-Debug-Request-Type" exists-action="override">
    <value>@(context.Variables.GetValueOrDefault<string>("request-type", "unknown"))</value>
  </set-header>
  <set-header name="X-Debug-Selected-Backend" exists-action="override">
    <value>@(context.Variables.GetValueOrDefault<string>("selected-backend", "unknown"))</value>
  </set-header>
  <set-header name="X-Debug-Request-ID" exists-action="override">
    <value>@(context.Variables.GetValueOrDefault<string>("request-id", "unknown"))</value>
  </set-header>
</fragment>

İşlem hattı yerleşimi:

Diğer tüm parçaların yürütülmesi tamamlandıktan sonra, üst bilgi yönetim parçasını ürün ilkenizin giden bölümüne ekleyin:

<policies>
  <outbound>
    <include-fragment fragment-id="circuit-breaker" />
    <include-fragment fragment-id="resource-tracking" />
    <!-- Headers fragment - placed last to capture final state -->
    <include-fragment fragment-id="debug-headers" />
    <base />
  </outbound>
</policies>

Alternatif - satır içi hata ayıklama üst bilgileri:

Basit senaryolar için veya tek tek parçaları test ederken hata ayıklama üst bilgilerini doğrudan ekleyebilirsiniz:

<set-header name="X-Debug-Variables" exists-action="override">
    <value>@{
        var debug = new JObject();
        debug["request-id"] = context.Variables.GetValueOrDefault<string>("request-id", "not-set");
        debug["request-type"] = context.Variables.GetValueOrDefault<string>("request-type", "not-set");
        debug["selected-backend"] = context.Variables.GetValueOrDefault<string>("selected-backend", "not-set");
        return debug.ToString(Formatting.None);
    }</value>
</set-header>

Parça yürütmeyi izleme

Parça sıralamasını doğrulamak ve hangi parçaların ürün ve API politikası sınırları arasında yürütüldüğünü belirlemek için yürütme kırıntı izleri oluşturun. Bu teknik, koşullu mantığın hatalarını ayıklamak ve bazı parçaların neden atlandığını anlamak için çok önemlidir. Bu kodu her parçanın başına ekleyin ve "parça-adı"nı gerçek parça adıyla değiştirin:

<set-variable name="execution-trace" value="@{
    var trace = context.Variables.GetValueOrDefault<string>("execution-trace", "");
    return trace + "→fragment-name";
}" />

İçerik haritası izini görüntülemek için, yürütme akışını günlüğe kaydetmek için yerleşik izleme ilkesini kullanın:

<trace source="Fragment-Execution" severity="information">
    <message>@(context.Variables.GetValueOrDefault<string>("execution-trace", ""))</message>
</trace>

İstek izleme kullanarak hata ayıklama

Beklenmeyen davranış sorunlarını gidermek için ilke işlem hattı aracılığıyla ayrıntılı yürütme izlemelerini yakalamak için istek izlemeyi etkinleştirin. İstek izlemeyi etkinleştirmek için istemcinin şunları yapması gerekir:

1. API Yönetimi yönetim API'si ile kimlik doğrulaması yaparak bir erişim jetonu alın.
2. Hata ayıklama izleme belirteci almak için hata ayıklama kimlik bilgilerini alma
3. hata ayıklama belirtecini kullanarak izlemenin etkinleştirildiği istekler gönderme
4. Yürütme akışını ve ilke ayrıntılarını gösteren tam izleme çıktısını alma

İzleme çıktısı, işlem hattınızdaki sorunları belirlemenize yardımcı olabilecek parça yürütme sırası, değişken durumu ve ilke işleme hakkında ayrıntılı bilgiler içerir. Daha fazla bilgi için bkz. API için izlemeyi etkinleştirme.

İşlem hattı sorunlarını gidermeye yardımcı olmak için izleme çıktısının tamamını kopyalayın ve sorunları çözmeye yönelik ayrıntılı analiz ve öneriler için GitHub Copilot'a sağlayın.

İ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.
• Politika parçaları için değişken yönetimi - Bağlam değişkeni işleme, güvenli erişim desenleri ve parçalar arası iletişim hakkında kapsamlı yönergeler.
• Politika parçaları için merkezi meta veri önbelleği - Parçalar arasında paylaşılan meta veri önbelleğe alma şablonları için gerçekleştirme rehberi.