API Management ilkelerini keşfetme

  • 3 dakika

Azure API Management'ta ilkeler yayımcının yapılandırma aracılığıyla API'nin davranışını değiştirmesine olanak tanır. İlkeler, bir API'nin isteği veya yanıtı üzerine sıralı olarak yürütülen bir Deyim koleksiyonudur.

İlkeler, API tüketicisi ile yönetilen API arasında yer alan ağ geçidi içinde uygulanır. Ağ geçidi tüm istekleri alır ve genellikle bunları temel alınan API'ye değiştirilmeden iletir. Ancak bir ilke hem gelen isteğe hem de giden yanıta değişiklik uygulayabilir. İlke ifadeleri herhangi bir API Management ilkesinde, ilke aksini belirtmedikçe, öznitelik değerleri ya da metin değerleri olarak kullanılabilir.

İlke yapılandırmasını anlama

İlke tanımı, gelen ve giden deyimlerinin sırasını açıklayan basit bir XML belgesidir. XML doğrudan tanım penceresinde düzenlenebilir.

Yapılandırma , , backendoutboundve on-errorolarak inboundayrılır. Belirtilen ilke deyimleri dizisi bir istek ve yanıt için yürütülür.

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

bir isteğin işlenmesi sırasında bir hata oluşursa, , backendveya outbound bölümlerinde kalan tüm adımlar inboundatlanır ve yürütme bölümündeki deyimlere on-error atlanır. bölüme on-error ilke deyimleri yerleştirerek özelliğini kullanarak hatayı gözden geçirebilir, ilkeyi context.LastError kullanarak set-body hata yanıtını inceleyip özelleştirebilir ve hata oluşursa ne olacağını yapılandırabilirsiniz.

İlke ifadeleri

İlke aksini belirtmediği sürece, ilke ifadeleri API Management ilkelerinin herhangi birinde öznitelik değerleri veya metin değerleri olarak kullanılabilir. İlke ifadesi şu şekildedir:

  • içine alınmış @(expression)tek bir C# deyimi veya
  • içinde bir değer döndüren çok deyimli bir C# kod bloğu @{expression}

Her ifade örtük olarak sağlanan context değişkene ve .NET Framework türlerinin izin verilen bir alt kümesine erişebilir.

İlke ifadeleri , özel kod yazmanıza veya arka uç hizmetlerini değiştirmenize gerek kalmadan trafiği denetlemek ve API davranışını değiştirmek için gelişmiş bir araç sağlar.

Aşağıdaki örnek, gelen isteğe kullanıcı verileri eklemek için ilke ifadelerini ve set-header ilkesini kullanır. Eklenen üst bilgi, istekteki abonelik anahtarıyla ilişkilendirilmiş kullanıcı kimliğini ve isteği işleyen ağ geçidinin barındırıldığı bölgeyi içerir.

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

Farklı kapsamlarda belirtilen ilkeleri uygulama

Genel düzeyde bir ilkeniz ve API için yapılandırılmış bir ilkeniz varsa, söz konusu API her kullanıldığında her iki ilke de uygulanır. API Management, birleştirilmiş ilke deyimlerinin temel öğesi aracılığıyla belirlenimci bir şekilde sıralanmasına olanak tanır.

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

Önceki örnek ilke tanımında, cross-domain deyimi önce yürütülür. İlke, find-and-replace daha geniş bir kapsamdaki tüm ilkelerden sonra yürütülür.

Yanıt içeriğini filtreleme

Aşağıdaki örnekte tanımlanan ilke, istekle ilişkili ürüne göre yanıt yükündeki veri öğelerinin nasıl filtreleneceği gösterilmektedir.

Kod parçacığı, yanıt içeriğinin JSON olarak biçimlendirildiğini varsayar ve "minutely", "hourly", "daily", "flags" adlı kök düzeyinde özellikler içerir.

<policies>
  <inbound>
    <base />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <choose>
      <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
        <!-- NOTE that we are not using preserveContent=true when deserializing response body stream into a JSON object since we don't intend to access it again. See details on /azure/api-management/api-management-transformation-policies#SetBody -->
        <set-body>
          @{
            var response = context.Response.Body.As<JObject>();
            foreach (var key in new [] {"minutely", "hourly", "daily", "flags"}) {
            response.Property (key).Remove ();
           }
          return response.ToString();
          }
    </set-body>
      </when>
    </choose>    
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>