Azure API Management ilkeleri

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. Bu makalede ilkelerin nasıl kullanılacağı açıklanmaktadır.

İ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 75'ten 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 arama sayısını kısıtlamak için arama 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ıp değiştirmeden temel API'ye iletse de, bir ilke hem gelen isteğe hem de giden yanıta değişiklik 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ı , inbound, backendve outbound bölümlerine on-errorayrılır. Belirlenen politika ifadeleri serisi, bir istek ve yanıt için sırayla işletilir. Şöyle görünü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's 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:

, inboundveya backend bölümlerinde kalan outboundtü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 set-body kullanarak hata yanıtını inceleyin ve özelleştirin.
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 aşağıdakilerden biridir:

tek bir C# deyimi @(expression) içinde
@{expression} ile çevrelenmiş, bir değer döndüren çoklu ifadeli bir C# kod bloğu.

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, burada en genişten en dara kadar sunulan aşağıdaki kapsamlarda ilke 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 bir işlem)

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

Bilinmesi gerekenler

Farklı API tüketicileri için ayrıntılı denetim için, ilke tanımlarını birden fazla kapsamda yapılandırabilirsiniz.
Tüm ilkeler, her kapsam ve politika bölümünde desteklenmez.
İlke tanımlarını birden fazla kapsamda yapılandırdığınızda, her ilke bölümünde ilke devralma ve ilke değerlendirme sırasını base öğesinin yerleştirilmesi ile kontrol edebilirsiniz.

Önemli

En iyi uygulama olarak, ilkeleri üst kapsamdan devralmak için her ilke bölümünün başına bir base öğe ekleyin. Bu, daha yüksek bir düzeyde tanımlanan ilkelerin yanlışlıkla geçersiz kılınmamasını veya yoksayılmasını sağlar. Bu en iyi yöntemi denetlemek veya uygulamak için yerleşik bir Azure İlkesi tanımı (API Management policies should inherit parent scope policies using <base/>) kullanılabilir.
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 Bir GraphQL çözümleyicisi , GraphQL şemasındaki belirli bir işlem türü ve alanı kapsamındaki ilkelerle yapılandırılır.

API Management şu anda HTTP API, Azure 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ırabilirsiniz.
API, ürün veya tüm API'ler gibi diğer kapsamlardaki ilke tanımlarına çözümleyici ilkesi ekleyemezsiniz. İlke, diğer kapsamlarda yapılandırılan ilkeleri de devralmaz.
Ağ geçidi, ilke yürütme işlem hattında yapılandırılan inbound ve backend ilkelerden sonra çözümleyiciye özgü bir ilkeyi değerlendirir.

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

Yardımı Copilot'tan al

API Management ilke tanımlarınızı oluşturmak ve düzenlemek için Copilot'tan yapay zeka yardımı alabilirsiniz. XML söz dizimini bilmenize gerek kalmadan özel gereksinimlerinize uyan ilkeler oluşturmak ve güncelleştirmek için Copilot'u kullanabilirsiniz. Ayrıca mevcut ilkelerin açıklamalarını da alabilirsiniz. Copilot, diğer API yönetim çözümlerinde yapılandırmış olabileceğiniz ilkeleri çevirmenize yardımcı olabilir.

Azure Copilot , Azure portalında doğal dil istemleriyle ilke yazma yardımı sağlar. API Management ilke düzenleyicisinde ilkeler yazabilir ve Copilot'dan ilke bölümlerini açıklamasını isteyebilirsiniz.
Visual Studio Code'da Azure için GitHub Copilot, ilke yazımını kolaylaştırıcı bir yardım sağlar ve ilke yapılandırmasını hızlandırmak için Visual Studio Code'daki Azure API Yönetimi Uzantısı'nı kullanabilirsiniz. İlke tanımlarını oluşturmak ve iyileştirmek için Copilot Chat veya Copilot Düzenlemeleri doğal dille yönlendirebilirsiniz.

Örnek komut:

Generate a policy that adds an Authorization header to the request with a Bearer token.

Copilot yapay zeka ile desteklendiğinden sürprizler ve hatalar mümkündür. Daha fazla bilgi için bkz. Copilot sıkça sorulan sorular.

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

Önce cross-domain deyimi çalışır.
İlke, find-and-replace daha geniş bir kapsamdaki tüm ilkelerden sonra çalışır.

Not

ÖĞESINI API kapsamında kaldırırsanız base , yalnızca API kapsamında yapılandırılan ilkeler uygulanır. Ürün ve daha geniş kapsamlarda yapılandırılan ilkeler uygulanmaz.

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

Aşağıdaki örnek, gelen isteklere kullanıcı verileri eklemek için ilke ifadelerini ve set-header ilkeyi kullanır. Eklenen üst bilgi, istekteki abonelik anahtarıyla ilişkili 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>

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

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-09-09