Azure API Management ilkeleri

  • Makale

UYGULANANLAR: Tüm API Management katmanları

Azure API Management'ta API yayımcıları, ilkeleri kullanarak yapılandırma aracılığıyla API davranışını değiştirebilir. İlkeler, bir API isteği veya yanıtı üzerinde sırayla çalıştırılan deyimlerin bir koleksiyonudur. API Management, kimlik doğrulaması, hız sınırlama, önbelleğe alma ve isteklerin veya yanıtların dönüştürülmesi gibi yaygın API senaryolarını ele almak için yapılandırabileceğiniz 50'den fazla ilke sağlar. Tam liste için bkz. API Management ilke başvurusu.

Popüler ilkeler şunlardır:

  • XML'den JSON'a biçim dönüştürme
  • Bir geliştiriciden gelen çağrı sayısını kısıtlamak için çağrı hızı sınırlaması
  • Belirli IP adreslerinden gelen istekleri filtreleme

İlkeler, API tüketicisi ile yönetilen API arasındaki ağ geçidi içerisinde uygulanır. Ağ geçidi istekleri alır ve bunları değiştirmeden temel alınan API'ye iletirken, ilke hem gelen isteğe hem de giden yanıta değişiklikler uygulayabilir.

İlke yapılandırmasını anlama

İlke tanımları, isteklere ve yanıtlara uygulanacak deyim dizisini açıklayan basit XML belgeleridir. İlke tanımlarını yapılandırmanıza yardımcı olmak için portal şu seçenekleri sağlar:

  • XML kodlamadan popüler ilkeleri yapılandırmayı basitleştirmek için kılavuzlu, form tabanlı bir düzenleyici
  • XML kod parçacıkları ekleyebileceğiniz veya XML'yi doğrudan düzenleyebileceğiniz bir kod düzenleyicisi

İlkeleri yapılandırma hakkında daha fazla bilgi için bkz . İlkeleri ayarlama veya düzenleme.

İlke XML yapılandırması , backend, outboundve on-error bölümlerine 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>

İlke XML örnekleri için bkz . API Management ilke parçacıkları deposu.

Hata işleme

bir isteğin işlenmesi sırasında bir hata oluşursa:

  • , backendveya outbound bölümlerinde kalan inboundtüm adımlar atlanır.
  • Yürütme bölümündeki deyimlere atlar on-error .

bölüme on-error ilke deyimleri yerleştirerek şunları yapabilirsiniz:

  • özelliğini kullanarak context.LastError hatayı gözden geçirin.
  • İlkeyi kullanarak hata yanıtını inceleyin ve özelleştirin set-body .
  • Hata oluşursa ne olacağını yapılandırın.

Daha fazla bilgi için bkz . API Management ilkelerinde hata işleme.

İ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. Bazı ilkeler Denetim akışı ve Değişken ayarla gibi ilke ifadelerini temel alır.

Kapsamlar

API Management, ilkeleri en genişten en dara kadar aşağıdaki kapsamlarda tanımlamanızı sağlar:

  • Genel (tüm API'ler)
  • Çalışma alanı (seçili çalışma alanıyla ilişkili tüm API'ler)
  • Ürün (seçili bir ürünle ilişkili tüm API'ler)
  • API (BIR API'deki tüm işlemler)
  • İşlem (API'de tek işlem)

İlkeyi yapılandırırken, önce ilkenin uygulanacağı kapsamı seçmeniz gerekir.

İlke kapsamları

Bilinmesi gerekenler

  • Farklı API tüketicileri için ayrıntılı denetim için, ilke tanımlarını birden fazla kapsamda yapılandırabilirsiniz

  • Her kapsam ve ilke bölümünde tüm ilkeler desteklenmez

  • İlke tanımlarını birden fazla kapsamda yapılandırırken, öğesinin yerleştirilmesine base göre ilke devralmayı ve ilke değerlendirme sırasını her ilke bölümünde denetleyebilirsiniz

  • API isteklerine uygulanan ilkeler, istekte kullanılan bir abonelik anahtarının varlığı veya olmaması, abonelik anahtarının API veya ürün kapsamı ve API'nin veya ürünün abonelik gerekip gerektirmediği de dahil olmak üzere istek bağlamından da etkilenir.

    Not

    API kapsamlı bir abonelik, tüm API'ler aboneliği veya yerleşik tüm erişimli abonelik kullanıyorsanız, ürün kapsamında yapılandırılan ilkeler bu abonelikten gelen isteklere uygulanmaz.

Daha fazla bilgi için bkz.

GraphQL çözümleyici ilkeleri

API Management'ta GraphQL çözümleyicisi, GraphQL şemasındaki belirli bir işlem türü ve alanı kapsamındaki ilkeler kullanılarak yapılandırılır.

  • API Management şu anda HTTP API, Cosmos DB veya Azure SQL veri kaynaklarını belirten GraphQL çözümleyicilerini desteklemektedir. Örneğin, bir HTTP veri kaynağına yönelik istek (ve isteğe bağlı olarak yanıt) belirtmek için öğeleri olan tek http-data-source bir ilke yapılandırın.
  • API, ürün veya tüm API'ler gibi diğer kapsamlardaki ilke tanımlarına çözümleyici ilkesi ekleyemezsiniz. Ayrıca diğer kapsamlarda yapılandırılmış ilkeleri devralmaz.
  • Ağ geçidi, ilke yürütme işlem hattında yapılandırılan inbound ve backend ilkelerden sonra çözümleyici kapsamlı bir ilkeyi değerlendirir.

Daha fazla bilgi için bkz . GraphQL çözümleyicisini yapılandırma.

Azure'da Microsoft Copilot kullanarak ilke oluşturma konusunda yardım alma (önizleme)

Azure'da Microsoft Copilot (önizleme), Azure API Management için ilke yazma özellikleri sağlar. Söz dizimini bilmeden belirli gereksinimlerinize uyan veya size açıklanmış ilkeleri önceden yapılandırmış ilkeler oluşturmak için Azure'da Api Management'ın ilke düzenleyicisi bağlamında Copilot kullanın.

Azure'da Copilot'tan ilke tanımları oluşturmasını isteyebilir, ardından sonuçları ilke düzenleyicisine kopyalayabilir ve gerekli ayarlamaları yapabilirsiniz. Farklı seçenekler hakkında içgörü elde etmek, sağlanan ilkeyi değiştirmek veya zaten sahip olduğunuz ilkeyi netleştirmek için sorular sorun. Daha fazla bilgi edinin

Örnekler

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 uygulanabilir. API Management, öğesi aracılığıyla birleştirilmiş ilke deyimlerinin belirlenimci bir şekilde sıralanmasına base olanak tanır.

API kapsamında örnek ilke tanımı:

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

Yukarıdaki örnek ilke tanımında:

  • deyimi cross-domain önce yürütülür.
  • İlke, find-and-replace daha geniş bir kapsamdaki tüm ilkelerden sonra yürütülür.

Not

ÖĞESINI API kapsamında kaldırırsanız base , yalnızca API kapsamında yapılandırılan ilkeler uygulanır. Ne ürün ne de genel kapsam ilkeleri uygulanmaz.

İstekleri değiştirmek için ilke ifadelerini kullanma

Aşağıdaki örnek, gelen isteğe kullanıcı verileri eklemek için ilke ifadelerini ve set-header ilkeyi 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>

İlgili içerik

İlkelerle çalışma hakkında daha fazla bilgi için bkz: