Aracılığıyla paylaş

API Management'ta arka uçlar

UYGULANANLAR: Tüm API Management katmanları

API Management'taki arka uç (veya API arka ucu), ön uç API'nizi ve işlemlerini uygulayan bir HTTP hizmetidir.

API Management, belirli API'leri içeri aktardığınızda API arka ucunu otomatik olarak yapılandırır. Örneğin, API Management içeri aktarırken arka uç web hizmetini yapılandırıyor:

Azure hizmetlerindeki API'ler gibi diğer API'ler için arka uç hizmetini açıkça belirtmeden bir Azure kaynağını içeri aktarırsınız. Örnekler şunları içerir:

API Management, api arka ucu olarak diğer kaynakların kullanılmasını da destekler, örneğin:

Bu arka uçlar için API Management'ta bir arka uç varlığı oluşturabilir ve API'lerinizde buna başvurabilirsiniz.

Arka planın avantajları

API Management, API'nizin arka uç hizmetlerini yönetebilmeniz için arka uç varlıklarını destekler. Arka uç varlığı, arka uç hizmeti hakkındaki bilgileri kapsülleyerek API'ler arasında yeniden kullanılabilirliği ve geliştirilmiş idareyi destekler.

Aşağıdakilerden biri veya daha fazlası için arka uçları kullanın:

  • Arka uç hizmetine yönelik isteklerin kimlik bilgilerini yetkilendirme
  • Adlandırılmış değerler üst bilgi veya sorgu parametresi kimlik doğrulaması için yapılandırılmışsa Azure Key Vault'ta gizli bilgileri korumak için API Management işlevselliğinden yararlanın.
  • Arka ucunuzu çok fazla istekten korumak için devre kesici kuralları tanımlama
  • İstekleri birden çok sunucuya veya yük dengeleyiciye yönlendirme

Azure portalında veya Azure API'lerini veya araçlarını kullanarak arka uç varlıklarını yapılandırın ve yönetin.

Backend geliştirme

Azure portalında veya Azure API'lerini veya araçlarını kullanarak arka uç oluşturabilirsiniz.

Not

Belirli API'leri, örneğin Microsoft Foundry veya diğer yapay zeka hizmetlerinden gelen API'leri içeri aktardığınızda, API Management otomatik olarak bir arka uç bileşeni yapılandırır.

Portalda arka uç oluşturmak için:

  1. Portalda oturum açın ve API Management örneğine gidin.
  2. Sol menüde API'ler>Arka Uçlar>+ Yeni arka uç oluştur'u seçin.
  3. Arka uç sayfasında aşağıdaki adımları tamamlayın:
    1. Arka uç için bir Ad ve isteğe bağlı Açıklama girin.
    2. Bir Arka uç barındırma türü seçin, örneğin bir İşlev Uygulaması veya Mantıksal Uygulama gibi bir Azure kaynağı için Azure kaynağı, özel bir hizmet için özel URL veya bir Service Fabric kümesi.
    3. Çalışma Zamanı URL'sinde, API isteklerinin ilettiği arka uç hizmetinin URL'sini girin.
    4. Gelişmiş altında, isteğe bağlı olarak arka uç için sertifika zincirini veya sertifika adı doğrulamasını devre dışı bırakın.
    5. Bu arka uç hizmetini arka uç havuzuna ekle altında, isteğe bağlı olarak arka uç için yük dengeli bir havuz seçin veya oluşturun.
    6. Devre kesici kuralı altında, isteğe bağlı olarak arka uç için bir devre kesici yapılandırın.
    7. Yetkilendirme kimlik bilgileri'nin altında, isteğe bağlı olarak arka uç erişimi yetkilendirmek için kimlik bilgilerini yapılandırın. Seçenekler arasında API Management örneğinde yapılandırılmış bir istek üst bilgisi, sorgu parametresi, istemci sertifikası veya sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimlik bulunur.
    8. Oluştur'i seçin.

Arka uç oluşturduktan sonra arka uç ayarlarını istediğiniz zaman güncelleştirebilirsiniz. Örneğin, devre kesici kuralı ekleyebilir, çalışma zamanı URL'sini değiştirebilir veya yetkilendirme kimlik bilgileri ekleyebilirsiniz.

Yetkilendirme kimlik bilgileri için yönetilen kimliği yapılandırma

Arka uç hizmetine erişimi yetkilendirmek için API Management örneğinde yapılandırılan sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimliği kullanabilirsiniz. Yetkilendirme kimlik bilgileri için yönetilen kimlik yapılandırmak için aşağıdaki adımları tamamlayın:

  1. Arka uç yapılandırmasının Yetkilendirme kimlik bilgileri bölümünde Yönetilen kimlik sekmesini ve ardından Etkinleştir'i seçin.

  2. İstemci kimliği'ndeSistem tarafından atanan kimlik'i veya örneğinizde yapılandırdığınız kullanıcı tarafından atanan kimliği seçin.

  3. Kaynak Kimliği alanına bir hedef Azure hizmeti veya arka ucu temsil eden kendi Microsoft Entra uygulamanızın uygulama kimliğini girin. Örneğin, Azure OpenAI hizmeti için girin https://cognitiveservices.azure.com .

    Daha fazla örnek için authentication-managed-identity başvuru ilkesine bakınız.

  4. Oluştur'i seçin.

Not

Ayrıca yönetilen kimliğe arka uç hizmetine erişmek için uygun izinleri veya RBAC rolünü atayın. Örneğin, arka uç bir Azure OpenAI hizmetiyse, Cognitive Services User rolünü yönetilen kimliğe atayın.

Yetkilendirme kimlik bilgileri için sertifikaları yapılandırma

İstemci sertifikaları veya özel sertifika yetkilisi (CA) sertifikaları ile karşılıklı TLS kimlik doğrulaması kullanarak arka uç hizmetine ağ geçidi erişiminin güvenliğini sağlayabilirsiniz.

İstemci sertifikayı yapılandırma

Arka uç hizmetinin güvenliği iyi bilinen bir CA tarafından verilen bir sertifikayla sağlanıyorsa, arka uç varlığına bir istemci sertifikası ekleyebilirsiniz:

  1. Sertifikayı API Management örneğine ekleyin. Azure Key Vault'ta yönetilen bir sertifikaya başvurabilir veya PFX dosyasını karşıya yükleyebilirsiniz.
  2. Arka uç yapılandırmasının Yetkilendirme kimlik bilgileri bölümünde İstemci sertifikaları sekmesini seçin.
  3. Açılan listede, kullanmak istediğiniz istemci sertifikasını seçin.
  4. Oluştur'i seçin.

CA sertifikalarını yapılandırma

Arka uç hizmeti özel bir CA sertifikası kullanıyorsa, arka uç varlığındaki özel CA sertifikasına başvurabilirsiniz. Arka uç sunucu sertifikası için güven oluşturmak için bu adımı uygulamanız gerekebilir; örneğin, otomatik olarak imzalanan sertifikalar, güvenilmeyen kök sertifikalar veya kısmi sertifika zincirleri.

Not

Şu anda, ca sertifika ayrıntılarını yalnızca v2 katmanlarında bir arka uç varlığında yapılandırabilirsiniz.

CA sertifika ayrıntılarını eklemek için şu adımları izleyin:

  1. Arka uç yapılandırmasının Yetkilendirme kimlik bilgileri bölümünde CA Sertifikaları'nı seçin.
  2. + CA sertifikası ayrıntıları ekle'yi seçin.
  3. CA sertifikası ekle bölmesinde aşağıdaki seçeneklerden birini belirleyin:
    • Sertifika parmak izi - Özel CA sertifikasının parmak izini (SHA-1, SHA-256 veya SHA-512 karması) girin.
    • Konu adı ve veren parmak izi - CA'yi benzersiz olarak tanımlayan konu adını ve CA'nın parmak izini girin.
  4. Add (Ekle) seçeneğini belirleyin.
  5. Oluştur'i seçin.

Portalda arka uç için CA sertifika ayrıntılarını yapılandırma işleminin ekran görüntüsü.

Not

Arka uç varlığında bir özel CA sertifikasının ayrıntılarını yapılandırdığınızda, API Management arka uçta doğrulama ayarlarını backendTlsPropertiesetkinleştirmenize veya devre dışı bırakmanıza bakılmaksızın sertifika adını ve sertifika zincirini her zaman doğrular.

Tavsiye

API Management REST API'sini kullanarak CA sertifika ayrıntılarını program aracılığıyla da yapılandırabilirsiniz. backendTlsProperties arka uç varlığında değerini ayarlayın.

Set-backend-service ilkesini kullanarak arka uç hizmetine referans alma

Arka uç oluşturduktan sonra API'lerinizdeki arka uç tanımlayıcıya (ad) başvurabilirsiniz. set-backend-service Gelen API isteğini arka uçtan yönlendirmek için ilkeyi kullanın. Api için zaten bir arka uç web hizmeti yapılandırdıysanız, isteği bunun yerine bir arka uç varlığına yönlendirmek için ilkeyi kullanabilirsiniz set-backend-service . Örneğin:

<policies>
    <inbound>
        <base />
        <set-backend-service backend-id="myBackend" />
    </inbound>
    [...]
<policies/>

Not

Alternatif olarak, kullanabilirsiniz base-url. Genellikle biçimi şeklindedir https://backend.com/api. Yanlış yapılandırmaları önlemek için sonuna bir eğik çizgi eklemekten kaçının. Genellikle, base-url ve HTTP(S) uç noktası değeri arka uçta eşleşmeli, böylece ön uç ve arka uç arasında sorunsuz bir tümleştirme sağlanabilir. API Management örneklerinin arka uç hizmet adını sonuna base-urleklediğini unutmayın.

Konuma, çağrılan ağ geçidine veya diğer ifadelere göre etkin backend'i değiştirmek için set-backend-service ilkesini kullanarak koşullu mantık uygulayabilirsiniz.

Örneğin, çağrılan ağ geçidine göre trafiği başka bir arka uçtan yönlendirmeye yönelik bir ilke aşağıda verilmiştir:

<policies>
    <inbound>
        <base />
        <choose>
            <when condition="@(context.Deployment.Gateway.Id == "factory-gateway")">
                <set-backend-service backend-id="backend-on-prem" />
            </when>
            <when condition="@(context.Deployment.Gateway.IsManaged == false)">
                <set-backend-service backend-id="self-hosted-backend" />
            </when>
            <otherwise />
        </choose>
    </inbound>
    [...]
<policies/>

Tavsiye

API Management ayrıca API istekleri aldığında arka uç varlıklarını otomatik olarak algılar ve kullanır. Çalışma zamanında, API Management'ın istek gönderdiği bir arka uç hizmetinin URL'si ile eşleşen bir arka uç varlığı varsa, arka uç varlığını kullanır. açıkça kullanmanız set-backend-servicegerekmez.

Devre kesici

API Management, bir arka uç hizmetinin çok sayıda isteğe maruz kalmasını önlemek için arkadaki kaynakta bir devre kesici özelliği sunar.

  • Devre kesici özelliği, devre kesiciyi trip etmek için tanımlanan zaman aralığındaki hata koşullarının sayısı veya yüzdesi ve hataları gösteren durum kodları aralığı gibi kuralları tanımlar.
  • Devre kesici çalıştığında API Management, tanımlı bir süre için arka uç hizmetine istek göndermeyi durdurur ve istemciye 503 Hizmet Kullanılamıyor yanıtı döndürür.
  • Yapılandırılan yolculuk süresinden sonra devre sıfırlanır ve trafik arka uçta devam eder.

Arka uç devre kesicisi, arka ucun aşırı yükleme durumlarından kurtulmasını sağlamak için devre kesici düzeninin bir uygulamasıdır. API Management ağ geçidini ve arka uç hizmetlerinizi korumak için uygulayabileceğiniz genel hız sınırlama ve eşzamanlılık sınırlama ilkelerini artırır.

Not

  • Şu anda, API Yönetimi'nin Tüketim katmanında arka uç devre kesici desteklenmemektedir.
  • API Management mimarisinin dağıtılmış yapısı nedeniyle, devre kesici tetikleme kuralları yaklaşıktır. Ağ geçidinin farklı örnekleri, aynı örnek üzerindeki bilgilere göre devre kesme kurallarını senkronize etmez ve uygulamaz.
  • Şu anda arka uç devre kesici için yalnızca bir kural yapılandırabilirsiniz.

Dikkat

Bir Azure OpenAI hizmetini arka uç olarak yapılandırıyorsanız ve hizmet çok fazla istek alıyorsa, 429 Too Many Requests yanıt durum kodu ve değeri büyük olabilen (örneğin, 1 gün) bir Retry-After üst bilgisi döndürür. Azure OpenAI arka uçlarını kullanarak, 429 yanıtlarını yönetmek ve Retry-After süresini kabul etmek için devre kesici kuralları uygulayın.

Örnek

Arka uçta bir devre kesici yapılandırmak için Azure portalını, API Management REST API'sini veya Bicep veya ARM şablonunu kullanın. Aşağıdaki örnekte, myAPIM API Management örneğindeki myBackend'deki devre kesici, 1 saat içinde sunucu hatalarını gösteren üç veya daha fazla 5xx durum kodu olduğunda devreye alır.

Bu örnekteki devre kesici 1 saat sonra sıfırlanır. Yanıtta bir Retry-After üst bilgi varsa, devre kesici değeri kabul eder ve istekleri arka uçtan yeniden göndermeden önce belirtilen süreyi bekler.

  1. Azure portalında API Management örneğine gidin.
  2. Sol menüde API'ler>Arka ucunuzu arka uçlar'ı> seçin.
  3. Arka uç sayfasında Ayarlar>Devre kesici ayarları>Yeni ekle'yi seçin.
  4. Yeni devre kesici oluştur sayfasında kuralı yapılandırın:
    • Kural adı: Kural için myBackend gibi bir ad girin.
    • Hata sayısı: 3 girin.
    • Hata aralığı: Varsayılan değeri 1 saat olarak bırakın.
    • Hata durumu kod aralığı: 500 - 599'ı seçin.
    • Yolculuk süresi: Varsayılan değeri 1 saat olarak bırakın.
    • HTTP yanıtında 'Retry-After' üst bilgisini denetleyin: Doğru (Kabul Et)'i seçin.

Yük dengeli havuz

API Management, bir API için birden çok arka uç uygulamak ve bu arka uçlar arasında yük dengeleme istekleri uygulamak istediğinizde arka uç havuzlarını destekler. Havuz, yük dengeleme için tek bir varlık olarak ele alınan arka uçlardan oluşan bir koleksiyondur.

Aşağıdaki gibi senaryolar için arka uç havuzu kullanın:

  • Yükü, her biri ayrı arka uç devre kesicilerine sahip olabilecek birden fazla arka uça dağıtın.
  • Yükü yükseltme için bir grup arka plan sunucusundan diğer bir gruba taşımak (mavi-yeşil dağıtım).

Not

  • Havuza en fazla 30 arka uç ekleyebilirsiniz.
  • API Management mimarisinin dağıtılmış yapısı nedeniyle arka uç yük dengelemesi yaklaşık olarak yapılır. Ağ geçidinin farklı örnekleri, aynı örnekteki bilgilere göre eşitlenmez ve yük dengelemesi yapamaz.

Yük dengeleme seçenekleri

API Management, arka uç havuzları için aşağıdaki yük dengeleme seçeneklerini destekler:

Yük dengeleme seçeneği Açıklama
Hepsini bir kez deneme İstekler varsayılan olarak havuzdaki arka uç sunucular arasında eşit olarak dağıtılır.
Ağırlıklı Havuzdaki arka uçlara ağırlıklar atayın ve istekleri her arka ucun göreli ağırlığına göre dağıtın. Mavi-yeşil dağıtımlar gibi senaryolar için kullanışlıdır.
Öncelik tabanlı Arka uçları öncelik grupları halinde düzenleyin. Önce yüksek öncelikli gruplara istek gönderin; bir grup içinde istekleri eşit olarak veya atanan ağırlıklara göre dağıtın.

Not

API Management hizmeti, daha yüksek öncelikli gruplardaki tüm arka uçlar devre kesici kurallarının tetiklenmesi nedeniyle kullanılamaz hale geldiğinde, yalnızca alt öncelik gruplarındaki arka uçları kullanır.

Oturum farkındalığı

Yukarıdaki yük dengeleme seçeneklerinden herhangi biriyle, oturum sırasında belirli bir kullanıcıdan gelen tüm isteklerin havuzda aynı arka uçtan gitmesini sağlamak için oturum tanımayı (oturum benzimliği) etkinleştirebilirsiniz. API Management, oturum durumunu korumak için bir oturum kimliği tanımlama bilgisi ayarlar. Bu seçenek, örneğin yapay zeka sohbet yardımcıları veya diğer konuşma aracıları gibi arka uçların olduğu senaryolarda, istekleri aynı oturumdan aynı uç noktaya yönlendirmek için kullanışlıdır.

Not

Yük dengeli havuzlardaki oturum farkındalığı ilk olarak AI Gateway Erkengüncelleştirme grubuna yayımlanıyor.

Oturum bilinci için tanımlama bilgilerini yönet

Oturum farkındalığını kullandığınızda, istemcinin tanımlama bilgilerini uygun şekilde işlemesi gerekir. İstemcinin, oturum durumunu korumak için Set-Cookie üst bilgi değerini depolaması ve bunu sonraki isteklerle birlikte göndermesi gerekir.

API Management ilkelerini, oturum tanımayı etkinleştirmek için çerezleri ayarlamada yardımcı olması amacıyla kullanabilirsiniz. Örneğin, Yardımcılar API'si (Microsoft Foundry Modellerinde Azure OpenAI'nin bir özelliği) için istemcinin oturum kimliğini tutması, thread kimliğini gövdeden ayıklaması ve çifti saklaması ve her çağrı için doğru tanımlama bilgini göndermesi gerekir. Ayrıca, istemcinin tanımlama bilgisi göndermesi gereken veya tanımlama bilgisi üst bilgisi göndermemesi gereken zamanları bilmesi gerekir. Bu gereksinimler, aşağıdaki örnek ilkeler tanımlanarak uygun şekilde işlenebilir:

<policies>
  <inbound>
    <base />
    <set-backend-service backend-id="APIMBackend" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <set-variable name="gwSetCookie" value="@{
      var payload = context.Response.Body.As<JObject>();
      var threadId = payload["id"];
      var gwSetCookieHeaderValue = context.Request.Headers.GetValueOrDefault("SetCookie", string.Empty);
      if(!string.IsNullOrEmpty(gwSetCookieHeaderValue))
      {
        gwSetCookieHeaderValue = gwSetCookieHeaderValue + $";Path=/threads/{threadId};";
      }
      return gwSetCookieHeaderValue;
    }" />
    <set-header name="Set-Cookie" exists-action="override">
      <value>Cookie=gwSetCookieHeaderValue</value>
    </set-header>
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

Örnek

Arka uç havuzunu yapılandırmak için portalı, API Management REST API'sini veya Bicep veya ARM şablonunu kullanın. Aşağıdaki örnekte, API Management örneği myAPIM içinde myBackendPool bir arka uç havuzuyla yapılandırılmıştır. Havuzdaki örnek arka uçlar arka uç-1 ve arka uç-2 olarak adlandırılır. Her iki arka uç da en yüksek öncelik grubundadır; grup içinde, arka uç-1,arka uç-2'den daha büyük bir ağırlığa sahiptir.

  1. Azure portalında API Management örneğine gidin.
  2. Sol menüde API'ler>Arka ucunuzu arka uçlar'ı> seçin.
  3. Arka uçlar sayfasında Yük dengeleyici sekmesini seçin.
  4. + Yeni havuz oluştur'u seçin.
  5. Yeni yük dengeli havuz oluştur sayfasında aşağıdaki bilgileri girin:
    • Ad: Havuz için myBackendPool gibi bir ad girin.
    • Açıklama: İsteğe bağlı olarak bir açıklama girin.
    • Havuza arka uç ekleme: Havuza eklemek için bir veya daha fazla arka uç seçin.
    • Arka uç ağırlığı ve önceliği: Havuzdaki her arka ucun ağırlığını ve önceliğini yapılandırmak için Ağırlığı ve önceliği özelleştir'i seçin. Örneğin, arka uç-1 ve arka uç-2 adlı iki arka uç eklediyseniz, arka uç-1'in ağırlığını 3, arka uç-2'nin kalınlığını 1 olarak ayarlayın ve her iki arka ucun da önceliğini 1 olarak ayarlayın.
    • Oluştur'i seçin.

Sınırlamalar

  • Geliştirici ve Premium katmanları için Bu sınırlamayla karşılaşırsanız, Teknoloji Topluluğu blogunda iç sanal ağ modunda Kendi Kendine Zincirlenmiş API Management istek sınırlaması makalesindeki yönergeleri izleyin.
  • Şu anda arka uç devre kesici için yalnızca bir kural yapılandırabilirsiniz.

İlgili içerik

  • Last updated on