API Management gelişmiş ilkeleri

Bu makalede, ilke ifadelerini temel alan ilkeler gibi gelişmiş API Management ilkeleri için bir başvuru sağlanır.

İlkeler hakkında daha fazla bilgi:

Gelişmiş ilkeler

Denetim akışı

İlke, choose if-then-else veya bir programlama dilindeki switch yapısına benzer şekilde Boole ifadelerinin değerlendirmesinin sonucuna göre kapalı ilke deyimleri uygular.

Not

İlkenin öğelerini ve alt öğelerini ilke deyiminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<choose>
    <when condition="Boolean expression | Boolean constant">
        <!— one or more policy statements to be applied if the above condition is true  -->
    </when>
    <when condition="Boolean expression | Boolean constant">
        <!— one or more policy statements to be applied if the above condition is true  -->
    </when>
    <otherwise>
        <!— one or more policy statements to be applied if none of the above conditions are true  -->
    </otherwise>
</choose>

Denetim akışı ilkesi en az bir <when/> öğe içermelidir. <otherwise/> öğesi isteğe bağlıdır. Öğelerdeki <when/> koşullar, ilke içindeki görünümlerine göre değerlendirilir. koşul özniteliği eşittir olan ilk <when/> öğenin içine alınmış ilke deyimleri true uygulanır. öğesi içinde <otherwise/> yer alan ilkeler varsa, öğe koşulu özniteliklerinin <when/>falsetümü ise uygulanır.

Örnekler

Örnek

Aşağıdaki örnekte bir set-variable ilkesi ve iki denetim akışı ilkesi gösterilmektedir.

Değişken kümesi ilkesi gelen bölümündedir ve istek üst bilgisi veya iPhonemetnini iPad içeriyorsa true User-Agent olarak ayarlanmış bir isMobile Boole bağlam değişkeni oluşturur.

İlk denetim akışı ilkesi de gelen bölümündedir ve bağlam değişkeninin değerine bağlı olarak iki Set sorgu dizesi parametre ilkesinden isMobile birini koşullu olarak uygular.

İkinci denetim akışı ilkesi giden bölümündedir ve olarak ayarlandığında trueXML'yi JSON'a Dönüştür ilkesini isMobile koşullu olarak uygular.

<policies>
    <inbound>
        <set-variable name="isMobile" value="@(context.Request.Headers.GetValueOrDefault("User-Agent","").Contains("iPad") || context.Request.Headers.GetValueOrDefault("User-Agent","").Contains("iPhone"))" />
        <base />
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<bool>("isMobile"))">
                <set-query-parameter name="mobile" exists-action="override">
                    <value>true</value>
                </set-query-parameter>
            </when>
            <otherwise>
                <set-query-parameter name="mobile" exists-action="override">
                    <value>false</value>
                </set-query-parameter>
            </otherwise>
        </choose>
    </inbound>
    <outbound>
        <base />
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<bool>("isMobile"))">
                <xml-to-json kind="direct" apply="always" consider-accept-header="false"/>
            </when>
        </choose>
    </outbound>
</policies>

Örnek

Bu örnekte, ürün kullanılırken arka uç hizmetinden alınan yanıttan veri öğelerini kaldırarak içerik filtrelemenin nasıl gerçekleştirildiği gösterilmektedir Starter . Örnek arka uç yanıtı , OpenWeather One Call API'sine benzer kök düzeyi özellikleri içerir.

<!-- Copy this snippet into the outbound section to remove a number of data elements from the response received from the backend service based on the name of the product -->
<choose>
  <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
    <set-body>@{
        var response = context.Response.Body.As<JObject>();
        foreach (var key in new [] {"current", "minutely", "hourly", "daily", "alerts"}) {
          response.Property (key).Remove ();
        }
        return response.ToString();
      }
    </set-body>
  </when>
</choose>

Öğeler

Öğe Açıklama Gerekli
Seçin Kök öğesi. Evet
Tesis İlkenin if veya ifelse bölümleri choose için kullanılacak koşul. İlkenin choose birden çok when bölümü varsa bunlar sıralı olarak değerlendirilir. condition öğesi olarak değerlendirildiğinde truebaşka hiçbir when koşul değerlendirilmez. Evet
Aksi takdir -de Koşulların hiçbiri olarak değerlendirilmezse truekullanılacak ilke parçacığını when içerir. Hayır

Öznitelikler

Öznitelik Açıklama Gerekli
condition="Boole ifadesi | Boole sabiti" İçeren when ilke deyimi değerlendirildiğinde değerlendirilecek Boole ifadesi veya sabiti. Evet

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, arka uç, hatada

  • İlke kapsamları: tüm kapsamlar

İstek iletme

İlke, forward-request gelen isteği istek bağlamında belirtilen arka uç hizmetine iletir. Arka uç hizmet URL'si API ayarlarında belirtilir ve arka uç hizmet ilkesini ayarlama kullanılarak değiştirilebilir.

Önemli

  • Bu ilke, istekleri bir API arka ucuna iletmek için gereklidir. Varsayılan olarak, API Management bu ilkeyi genel kapsamda ayarlar.
  • Bu ilkenin kaldırılması isteğin arka uç hizmetine iletilmemesiyle sonuçlanır. Giden bölümündeki ilkeler, gelen bölümündeki ilkelerin başarıyla tamamlanmasından hemen sonra değerlendirilir.

Not

İlkenin öğelerini ve alt öğelerini ilke deyiminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<forward-request timeout="time in seconds" follow-redirects="false | true" buffer-request-body="false | true" buffer-response="true | false" fail-on-error-status-code="false | true"/>

Örnekler

Örnek

Aşağıdaki API düzeyi ilkesi, tüm API isteklerini 60 saniyelik zaman aşımı aralığıyla arka uç hizmetine iletir.

<!-- api level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request timeout="60"/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Örnek

Bu işlem düzeyi ilkesi, üst API düzeyi kapsamından arka uç ilkesini devralmak için öğesini kullanır base .

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <base/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Örnek

Bu işlem düzeyi ilkesi, zaman aşımı 120 olan tüm istekleri açıkça arka uç hizmetine iletir ve üst API düzeyi arka uç ilkesini devralmaz. Arka uç hizmeti 400 ile 599 (dahil) arasında bir hata durum koduyla yanıt verirse , hatada bölümü tetiklenir.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request timeout="120" fail-on-error-status-code="true" />
        <!-- effective policy. note the absence of <base/> -->
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Örnek

Bu işlem düzeyi ilkesi istekleri arka uç hizmetine iletmez.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <!-- no forwarding to backend -->
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Öğeler

Öğe Açıklama Gerekli
iletme isteği Kök öğesi. Evet

Öznitelikler

Öznitelik Açıklama Gerekli Varsayılan
timeout="integer" Zaman aşımı hatası oluşmadan önce arka uç hizmeti tarafından HTTP yanıt üst bilgilerinin döndürülmesini bekleme süresi (saniye cinsinden). En düşük değer 0 saniyedir. Temel alınan ağ altyapısı bu süreden sonra boştaki bağlantıları bırakaabildiği için 240 saniyeden büyük değerler dikkate alınamayabilir. Hayır 300
follow-redirects="false | true" Arka uç hizmetinden gelen yeniden yönlendirmelerin ardından ağ geçidinin mi yoksa çağıranın mı döndürüldiğini belirtir. Hayır yanlış
buffer-request-body="false | true" "True" olarak ayarlandığında istek arabelleğe alınır ve yeniden denendiğinde yeniden kullanılır. Hayır yanlış
buffer-response="false | true" Öbeklenmiş yanıtların işlenmesini etkiler. "false" olarak ayarlandığında, arka uçtan alınan her öbek hemen çağırana döndürülür. "true" olarak ayarlandığında öbekler arabelleğe alınır (akışın sonu algılanmadığı sürece 8 KB) ve yalnızca çağırana döndürülür.

İçeriğin hemen çağırana döndürülmesi veya akışı yapılmasını gerektiren sunucu tarafından gönderilen olayları (SSE) uygulayan arka uçlar gibi arka uçlarla "false" olarak ayarlayın.
Hayır true
fail-on-error-status-code="false | true" true olarak ayarlandığında, 400 ile 599 (dahil) aralığındaki yanıt kodları için hatada bölümünü tetikler. Hayır yanlış

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: arka uç
  • İlke kapsamları: tüm kapsamlar

Parça ekle

İlke, include-fragment ilke tanımına önceden oluşturulmuş bir ilke parçasının içeriğini ekler. İlke parçası, API Management örneğinizdeki ilke tanımlarına dahil edilebilen merkezi olarak yönetilen, yeniden kullanılabilir bir XML ilke parçacığıdır.

İlke, ilke parçasını ilke tanımında seçtiğiniz konuma olduğu gibi ekler.

İlke bildirimi

<include-fragment fragment-id="fragment" />

Örnek

Aşağıdaki örnekte, myFragment adlı ilke parçası bir ilke tanımının gelen bölümüne eklenir.

<inbound>
    <include-fragment fragment-id="myFragment" />
    <base />
</inbound>
[...]

Öğeler

Öğe Açıklama Gerekli
include-fragment Kök öğesi. Evet

Öznitelikler

Öznitelik Açıklama Gerekli Varsayılan
fragment-id Bir dize. İfadeye izin verilir. API Management örneğinde oluşturulan bir ilke parçasının tanımlayıcısını (adını) belirtir. Evet Yok

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, arka uç, hatada

  • İlke kapsamları: tüm kapsamlar

Eşzamanlılığı sınırla

İlke, limit-concurrency kapsayan ilkelerin herhangi bir anda belirtilen sayıda istekten daha fazla yürütülmesini engeller. Bu sayı aşıldığında, yeni istekler Çok Fazla İstek durum koduyla 429 hemen başarısız olur.

Not

İlkenin öğelerini ve alt öğelerini ilke deyiminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<limit-concurrency key="expression" max-count="number">
        <!— nested policy statements -->
</limit-concurrency>

Örnek

Aşağıdaki örnekte, bir bağlam değişkeninin değerine göre arka uça iletilen istek sayısının nasıl sınırlandığı gösterilmektedir.

<policies>
  <inbound>…</inbound>
  <backend>
    <limit-concurrency key="@((string)context.Variables["connectionId"])" max-count="3">
      <forward-request timeout="120"/>
    </limit-concurrency>
  </backend>
  <outbound>…</outbound>
</policies>

Öğeler

Öğe Açıklama Gerekli
limit-concurrency Kök öğesi. Evet

Öznitelikler

Öznitelik Açıklama Gerekli Varsayılan
anahtar Bir dize. İfadeye izin verilir. Eşzamanlılık kapsamını belirtir. Birden çok ilke tarafından paylaşılabilir. Evet Yok
max-count Bir tamsayı. İlkeye girmesine izin verilen en fazla istek sayısını belirtir. Evet Yok

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, arka uç, hatada

  • İlke kapsamları: tüm kapsamlar

Olay hub'ına oturum açma

İlke, log-to-eventhub günlükçü varlığı tarafından tanımlanan bir olay hub'ına belirtilen biçimde iletiler gönderir. Adından da anlaşılacağı gibi, ilke seçilen istek veya yanıt bağlamı bilgilerini çevrimiçi veya çevrimdışı analiz için kaydetmek için kullanılır.
İlke Application Insights örneklemeden etkilenmez. İlkenin tüm çağrıları günlüğe kaydedilir.

Not

Olay hub'larını yapılandırma ve olayları günlüğe kaydetme hakkında adım adım kılavuz için bkz. Azure Event Hubs ile API Management olayları günlüğe kaydetme.

Not

İlkenin öğelerini ve alt öğelerini ilke deyiminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<log-to-eventhub logger-id="id of the logger entity" partition-id="index of the partition where messages are sent" partition-key="value used for partition assignment">
  Expression returning a string to be logged
</log-to-eventhub>

Örnek

Herhangi bir dize Event Hubs'da günlüğe kaydedilecek değer olarak kullanılabilir. Bu örnekte, tüm gelen çağrıların tarih ve saat, dağıtım hizmeti adı, istek kimliği, IP adresi ve işlem adı, kimlikle kaydedilen olay hub'ı Günlükçüsünü contoso-logger günlüğe kaydedilir

<policies>
  <inbound>
    <log-to-eventhub logger-id ='contoso-logger'>
      @( string.Join(",", DateTime.UtcNow, context.Deployment.ServiceName, context.RequestId, context.Request.IpAddress, context.Operation.Name) )
    </log-to-eventhub>
  </inbound>
  <outbound>
  </outbound>
</policies>

Öğeler

Öğe Açıklama Gerekli
log-to-eventhub Kök öğesi. Bu öğenin değeri, olay hub'ınız için günlüğe kaydedilecek dizedir. Evet

Öznitelikler

Öznitelik Açıklama Gerekli
günlükçü kimliği API Management hizmetinize kayıtlı günlükçü kimliği. Evet
partition-id İletilerin gönderildiği bölümün dizinini belirtir. İsteğe bağlı. Bu öznitelik kullanılıyorsa partition-key kullanılamayabilir.
partition-key İletiler gönderildiğinde bölüm ataması için kullanılan değeri belirtir. İsteğe bağlı. Bu öznitelik kullanılıyorsa partition-id kullanılamayabilir.

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, arka uç, hatada

  • İlke kapsamları: tüm kapsamlar

Ölçümleri yayma

İlke, emit-metric belirtilen biçimdeki özel ölçümleri Application Insights'a gönderir.

Not

Not

İlkenin öğelerini ve alt öğelerini ilke deyiminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<emit-metric name="name of custom metric" value="value of custom metric" namespace="metric namespace"> 
    <dimension name="dimension name" value="dimension value" /> 
</emit-metric> 

Örnek

Aşağıdaki örnek kullanıcı kimliği, istemci IP'si ve API kimliği ile birlikte API isteklerinin sayısını özel boyutlar olarak saymak için özel bir ölçüm gönderir.

<policies>
  <inbound>
    <emit-metric name="Request" value="1" namespace="my-metrics"> 
        <dimension name="User ID" /> 
        <dimension name="Client IP" value="@(context.Request.IpAddress)" /> 
        <dimension name="API ID" /> 
    </emit-metric> 
  </inbound>
  <outbound>
  </outbound>
</policies>

Öğeler

Öğe Açıklama Gerekli
emit-metric Kök öğesi. Bu öğenin değeri, özel ölçümünüzü yayma dizesidir. Evet
boyut Alt öğe. Özel ölçüme dahil edilen her boyut için bu öğelerden bir veya daha fazlasını ekleyin. Evet

Öznitelikler

emit-metric

Öznitelik Açıklama Gerekli Tür Varsayılan değer
name Özel ölçümün adı. Evet dize, ifade Yok
ad alanı Özel ölçümün ad alanı. Hayır dize, ifade API Management
değer Özel ölçümün değeri. Hayır int, ifade 1

boyut

Öznitelik Açıklama Gerekli Tür Varsayılan değer
name Boyutun adı. Evet dize, ifade Yok
değer Boyutun değeri. Yalnızca varsayılan boyutlardan biriyle eşleşiyorsa name atlanabilir. Bu durumda değer boyut adına göre sağlanır. Hayır dize, ifade Yok

Değer olmadan kullanılabilecek varsayılan boyut adları:

  • API Kimliği
  • İşlem Kimliği
  • Ürün Kimliği
  • Kullanıcı Kimliği
  • Abonelik Kimliği
  • Konum Kimliği
  • Ağ Geçidi Kimliği

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, arka uç, hatada

  • İlke kapsamları: tüm kapsamlar

Sahte yanıt

mock-responseadından da anlaşılacağı gibi, API'leri ve işlemleri taklit etmek için kullanılır. Normal işlem hattı yürütmesini durdurur ve çağırana sahte bir yanıt döndürür. İlke her zaman en yüksek aslına uygun yanıtları döndürmeye çalışır. Kullanılabilir olduğunda yanıt içeriği örneklerini tercih eder. Şemalar sağlandığında ve örnekler sağlanmadığında şemalardan örnek yanıtlar oluşturur. Hiçbir örnek veya şema bulunmazsa, içeriği olmayan yanıtlar döndürülür.

Not

İlkenin öğelerini ve alt öğelerini ilke bildiriminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<mock-response status-code="code" content-type="media type"/>

Örnekler

<!-- Returns 200 OK status code. Content is based on an example or schema, if provided for this
status code. First found content type is used. If no example or schema is found, the content is empty. -->
<mock-response/>

<!-- Returns 200 OK status code. Content is based on an example or schema, if provided for this
status code and media type. If no example or schema found, the content is empty. -->
<mock-response status-code='200' content-type='application/json'/>

Öğeler

Öğe Açıklama Gerekli
sahte yanıt Kök öğesi. Evet

Öznitelikler

Öznitelik Açıklama Gerekli Varsayılan
durum kodu Yanıt durum kodunu belirtir ve karşılık gelen örneği veya şemayı seçmek için kullanılır. Hayır 200
içerik türü Content-Type Yanıt üst bilgisi değerini belirtir ve karşılık gelen örneği veya şemayı seçmek için kullanılır. Hayır Hiçbiri

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, hata üzerine

  • İlke kapsamları: tüm kapsamlar

Yeniden Dene

İlkeretry, alt ilkelerini bir kez yürütür ve sonra yeniden deneme bitene false veya yeniden denenene condition kadar yürütmelerini yeniden denercount.

Not

İlkenin öğelerini ve alt öğelerini ilke bildiriminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi


<retry
    condition="boolean expression or literal"
    count="number of retry attempts"
    interval="retry interval in seconds"
    max-interval="maximum retry interval in seconds"
    delta="retry interval delta in seconds"
    first-fast-retry="boolean expression or literal">
        <!-- One or more child policies. No restrictions -->
</retry>

Örnek

Aşağıdaki örnekte, üstel bir yeniden deneme algoritması kullanılarak istek iletme on kereye kadar yeniden denendi. first-fast-retry false olarak ayarlandığından, tüm yeniden deneme girişimleri üstel olarak artan yeniden deneme bekleme sürelerine (bu örnekte, yaklaşık 10 saniye, 20 saniye, 40 saniye, ...) en fazla bekleme max-intervalsüresine tabidir.


<retry
    condition="@(context.Response.StatusCode == 500)"
    count="10"
    interval="10"
    max-interval="100"
    delta="10"
    first-fast-retry="false">
        <forward-request buffer-request-body="true" />
</retry>

Örnek

Aşağıdaki örnekte, bağlantı bırakıldığında/zaman aşımına uğradıysa veya istek sunucu tarafı hatasıyla sonuçlanırsa, tanımlı arka uç dışındaki bir URL'ye istek gönderme işlemi en fazla üç kez yeniden denenecek. first-fast-retry true olarak ayarlandığından ilk yeniden deneme ilk istek hatasının hemen ardından yürütülür. send-request Hata durumunda null olması için response-variable-name true olarak ayarlanması ignore-error gerektiğini unutmayın.


<retry
    condition="@(context.Variables["response"] == null || ((IResponse)context.Variables["response"]).StatusCode >= 500)"
    count="3"
    interval="1"
    first-fast-retry="true">
        <send-request 
            mode="new" 
            response-variable-name="response" 
            timeout="3" 
            ignore-error="true">
		        <set-url>https://api.contoso.com/products/5</set-url>
		        <set-method>GET</set-method>
		</send-request>
</retry>

Öğeler

Öğe Açıklama Gerekli
retry Kök öğesi. Alt öğeleri olarak başka ilkeler içerebilir. Evet

Öznitelikler

Öznitelik Açıklama Gerekli Varsayılan
Durum Yeniden denemelerin durdurulup durdurulmaması () veya devam edilmesi (false) gerektiğini belirten bir boole değişmez değeri veya ifade.true Evet Yok
count Denenecek en fazla yeniden deneme sayısını belirten pozitif bir sayı. Evet Yok
interval Yeniden deneme girişimleri arasındaki bekleme aralığını belirten saniye cinsinden pozitif bir sayı. Evet Yok
maksimum aralık Yeniden deneme girişimleri arasındaki maksimum bekleme aralığını belirten saniye cinsinden pozitif bir sayı. Üstel bir yeniden deneme algoritması uygulamak için kullanılır. Hayır Yok
delta Bekleme aralığı artışını belirten saniye cinsinden pozitif bir sayı. Doğrusal ve üstel yeniden deneme algoritmalarını uygulamak için kullanılır. Hayır Yok
ilk hızlı yeniden deneme olarak ayarlanırsa true , ilk yeniden deneme girişimi hemen gerçekleştirilir. Hayır false

Bekleme sürelerini yeniden deneyin

  • Yalnızca değeri belirtildiğinde intervalsabit aralıklı yeniden denemeler gerçekleştirilir.

  • Yalnızca ve delta belirtildiğinde intervaldoğrusal aralık yeniden deneme algoritması kullanılır. Yeniden denemeler arasındaki bekleme süresi şu formüle göre artar: interval + (count - 1)*delta.

  • ve max-intervaldelta belirtildiğindeinterval, üstel aralık yeniden deneme algoritması uygulanır. Yeniden denemeler arasındaki bekleme süresi, şu formüle göre katlanarak artar: interval + (2^count - 1) * random(delta * 0.8, delta * 1.2), tarafından max-intervalayarlanan en uzun zaman aralığına kadar.

    Örneğin, interval her delta ikisi de 10 saniye ve max-interval 100 saniye olarak ayarlandığında, yeniden denemeler arasındaki yaklaşık bekleme süresi şu şekilde artar: 10 saniye, 20 saniye, 40 saniye, 80 saniye, kalan yeniden denemeler için 100 saniye bekleme süresi kullanılır.

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir. Alt ilke kullanım kısıtlamaları bu ilke tarafından devralınacaktır.

  • İlke bölümleri: gelen, giden, arka uç, hatada

  • İlke kapsamları: tüm kapsamlar

Yanıt döndür

İlke return-response işlem hattı yürütmesini durdurur ve çağıran için varsayılan veya özel bir yanıt döndürür. Varsayılan yanıt gövdesizdir 200 OK . Özel yanıt bir bağlam değişkeni veya ilke deyimleri aracılığıyla belirtilebilir. Her ikisi de sağlandığında, bağlam değişkeni içinde yer alan yanıt, çağırana döndürülmeden önce ilke deyimleri tarafından değiştirilir.

Not

İlkenin öğelerini ve alt öğelerini ilke bildiriminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<return-response response-variable-name="existing context variable">
  <set-status/>
  <set-header/>
  <set-body/>
</return-response>

Örnek

<return-response>
   <set-status code="401" reason="Unauthorized"/>
   <set-header name="WWW-Authenticate" exists-action="override">
      <value>Bearer error="invalid_token"</value>
   </set-header>
</return-response>

Öğeler

Öğe Açıklama Gerekli
dönüş yanıtı Kök öğesi. Evet
set-status Bir set-status ilke deyimi. Hayır
set-header Bir set-header ilke deyimi. Hayır
küme gövdesi Bir küme gövdesi ilke deyimi. Hayır

Öznitelikler

Öznitelik Açıklama Gerekli
response-variable-name Bir yukarı akış gönderme isteği ilkesinden başvuruda bulunup bir Response nesne içeren bağlam değişkeninin adı İsteğe bağlı.

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, arka uç, hatada

  • İlke kapsamları: tüm kapsamlar

Tek yönlü istek gönderme

İlke, send-one-way-request sağlanan isteği yanıt beklemeden belirtilen URL'ye gönderir.

Not

İlkenin öğelerini ve alt öğelerini ilke bildiriminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<send-one-way-request mode="new | copy">
  <set-url>...</set-url>
  <method>...</method>
  <header name="" exists-action="override | skip | append | delete">...</header>
  <body>...</body>
  <authentication-certificate thumbprint="thumbprint" />
</send-one-way-request>

Örnek

Bu örnek ilke, HTTP yanıt kodu 500'den büyük veya buna eşitse Slack sohbet odasına ileti göndermek için ilkeyi kullanma send-one-way-request örneğini gösterir. Bu örnek hakkında daha fazla bilgi için bkz. Azure API Management hizmetinden dış hizmetleri kullanma.

<choose>
    <when condition="@(context.Response.StatusCode >= 500)">
      <send-one-way-request mode="new">
        <set-url>https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX</set-url>
        <set-method>POST</set-method>
        <set-body>@{
                return new JObject(
                        new JProperty("username","APIM Alert"),
                        new JProperty("icon_emoji", ":ghost:"),
                        new JProperty("text", String.Format("{0} {1}\nHost: {2}\n{3} {4}\n User: {5}",
                                                context.Request.Method,
                                                context.Request.Url.Path + context.Request.Url.QueryString,
                                                context.Request.Url.Host,
                                                context.Response.StatusCode,
                                                context.Response.StatusReason,
                                                context.User.Email
                                                ))
                        ).ToString();
            }</set-body>
      </send-one-way-request>
    </when>
</choose>

Öğeler

Öğe Açıklama Gerekli
tek yönlü istek gönderme Kök öğesi. Evet
set-url İsteğin URL'si. Hayır if mode=copy; aksi takdirde evet.
method İstek için HTTP yöntemi. Hayır if mode=copy; aksi takdirde evet.
üst bilgi İstek üst bilgisi. Birden çok istek üst bilgisi için birden çok üst bilgi öğesi kullanın. Hayır
body İstek gövdesi. Hayır
kimlik doğrulama sertifikası İstemci kimlik doğrulaması için kullanılacak sertifika Hayır

Öznitelikler

Öznitelik Açıklama Gerekli Varsayılan
mode="string" Bunun yeni bir istek mi yoksa geçerli isteğin bir kopyası mı olduğunu belirler. Giden modunda, mode=copy istek gövdesini başlatmaz. Hayır Yeni
name Ayarlanacak üst bilginin adını belirtir. Evet Yok
exists-action Üst bilgi zaten belirtildiğinde hangi eylemin gerçekleştireceklerini belirtir. Bu öznitelik aşağıdaki değerlerden birine sahip olmalıdır.

- override - varolan üst bilginin değerini değiştirir.
- skip - varolan üst bilgi değerinin yerini almaz.
- append - değeri varolan üst bilgi değerine ekler.
- delete - üst bilgiyi istekten kaldırır.

Aynı ada sahip birden çok girdiyi listelemek için override ayarlandığında, üst bilginin tüm girişlere göre ayarlanmasıyla sonuçlanır (birden çok kez listelenir); sonuçta yalnızca listelenen değerler ayarlanır.
Hayır override

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, arka uç, hatada

  • İlke kapsamları: tüm kapsamlar

İstek gönderme

İlke belirtilen send-request URL'ye belirtilen isteği gönderir ve ayarlanan zaman aşımı değerinden uzun süre beklemez.

Not

İlkenin öğelerini ve alt öğelerini ilke deyiminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<send-request mode="new|copy" response-variable-name="" timeout="60 sec" ignore-error
="false|true">
  <set-url>...</set-url>
  <set-method>...</set-method>
  <set-header name="" exists-action="override|skip|append|delete">...</set-header>
  <set-body>...</set-body>
  <authentication-certificate thumbprint="thumbprint" />
</send-request>

Örnek

Bu örnekte, bir yetkilendirme sunucusuyla başvuru belirtecini doğrulamanın bir yolu gösterilmektedir. Bu örnek hakkında daha fazla bilgi için bkz. Azure API Management hizmetinden dış hizmetleri kullanma.

<inbound>
  <!-- Extract Token from Authorization header parameter -->
  <set-variable name="token" value="@(context.Request.Headers.GetValueOrDefault("Authorization","scheme param").Split(' ').Last())" />

  <!-- Send request to Token Server to validate token (see RFC 7662) -->
  <send-request mode="new" response-variable-name="tokenstate" timeout="20" ignore-error="true">
    <set-url>https://microsoft-apiappec990ad4c76641c6aea22f566efc5a4e.azurewebsites.net/introspection</set-url>
    <set-method>POST</set-method>
    <set-header name="Authorization" exists-action="override">
      <value>basic dXNlcm5hbWU6cGFzc3dvcmQ=</value>
    </set-header>
    <set-header name="Content-Type" exists-action="override">
      <value>application/x-www-form-urlencoded</value>
    </set-header>
    <set-body>@($"token={(string)context.Variables["token"]}")</set-body>
  </send-request>

  <choose>
        <!-- Check active property in response -->
        <when condition="@((bool)((IResponse)context.Variables["tokenstate"]).Body.As<JObject>()["active"] == false)">
            <!-- Return 401 Unauthorized with http-problem payload -->
            <return-response>
                <set-status code="401" reason="Unauthorized" />
                <set-header name="WWW-Authenticate" exists-action="override">
                    <value>Bearer error="invalid_token"</value>
                </set-header>
            </return-response>
        </when>
    </choose>
  <base />
</inbound>

Öğeler

Öğe Açıklama Gerekli
send-request Kök öğesi. Evet
url İsteğin URL'si. Hayır if mode=copy; aksi takdirde evet.
method İsteğin HTTP yöntemi. Hayır if mode=copy; aksi takdirde evet.
üst bilgi İstek üst bilgisi. Birden çok istek üst bilgisi için birden çok üst bilgi öğesi kullanın. Hayır
body İstek gövdesi. Hayır
kimlik doğrulama sertifikası İstemci kimlik doğrulaması için kullanılacak sertifika Hayır

Öznitelikler

Öznitelik Açıklama Gerekli Varsayılan
mode="string" Bunun yeni bir istek mi yoksa geçerli isteğin bir kopyası mı olduğunu belirler. Giden modunda, mode=copy istek gövdesini başlatmaz. Hayır Yeni
response-variable-name="string" Yanıt nesnesi alacak bağlam değişkeninin adı. Değişken yoksa, ilkenin başarıyla yürütülmesinden sonra oluşturulur ve koleksiyon aracılığıyla context.Variable erişilebilir hale gelir. Evet Yok
timeout="integer" URL çağrısı başarısız olmadan önce saniye cinsinden zaman aşımı aralığı. Hayır 60
ignore-error True ise ve istek bir hatayla sonuçlanırsa, hata yoksayılır ve yanıt değişkeni null değer içerir. Hayır yanlış
name Ayarlanacak üst bilginin adını belirtir. Evet Yok
exists-action Üst bilgi zaten belirtildiğinde hangi eylemin gerçekleştireceklerini belirtir. Bu öznitelik aşağıdaki değerlerden birine sahip olmalıdır.

- override - varolan üst bilginin değerini değiştirir.
- skip - varolan üst bilgi değerinin yerini almaz.
- append - değeri varolan üst bilgi değerine ekler.
- delete - üst bilgiyi istekten kaldırır.

Aynı ada sahip birden çok girdiyi listelemek için override ayarlandığında, üst bilginin tüm girişlere göre ayarlanmasıyla sonuçlanır (birden çok kez listelenir); sonuçta yalnızca listelenen değerler ayarlanır.
Hayır override

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, arka uç, hatada

  • İlke kapsamları: tüm kapsamlar

HTTP ara sunucusunu ayarlama

İlke, proxy http ara sunucusu aracılığıyla arka uçlara iletilen istekleri yönlendirmenize olanak tanır. Ağ geçidi ile ara sunucu arasında yalnızca HTTP (HTTPS değil) desteklenir. Yalnızca Temel ve NTLM kimlik doğrulaması. Gönderme isteğini HTTP ara sunucusu aracılığıyla yönlendirmek için ayarlanan HTTP proxy ilkesini send-request ilke bloğunun içine yerleştirmeniz gerekir.

Not

İlkenin öğelerini ve alt öğelerini ilke deyiminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<proxy url="http://hostname-or-ip:port" username="username" password="password" />

Örnek

İlke belgesinde hassas bilgilerin depolanmasını önlemek için özelliklerin kullanıcı adı ve parola değerleri olarak kullanıldığına dikkat edin.

<proxy url="http://192.168.1.1:8080" username={{username}} password={{password}} />

Öğeler

Öğe Açıklama Gerekli
proxy Kök öğe Evet

Öznitelikler

Öznitelik Açıklama Gerekli Varsayılan
url="string" Biçiminde Ara Sunucu URL'si http://host:port. Evet Yok
username="string" Proxy ile kimlik doğrulaması için kullanılacak kullanıcı adı. Hayır Yok
password="string" Proxy ile kimlik doğrulaması için kullanılacak parola. Hayır Yok

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen

  • İlke kapsamları: tüm kapsamlar

İstek yöntemini ayarlama

İlke, set-method bir isteğin HTTP istek yöntemini değiştirmenize olanak tanır.

Not

İlkenin öğelerini ve alt öğelerini ilke bildiriminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<set-method>METHOD</set-method>

Örnek

İlkeyi set-method kullanan bu örnek ilke, HTTP yanıt kodu 500'den büyük veya buna eşitse Slack sohbet odasına ileti gönderme örneğini gösterir. Bu örnek hakkında daha fazla bilgi için bkz. Azure API Management hizmetinden dış hizmetleri kullanma.

<choose>
    <when condition="@(context.Response.StatusCode >= 500)">
      <send-one-way-request mode="new">
        <set-url>https://hooks.slack.com/services/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</set-url>
        <set-method>POST</set-method>
        <set-body>@{
                return new JObject(
                        new JProperty("username","APIM Alert"),
                        new JProperty("icon_emoji", ":ghost:"),
                        new JProperty("text", String.Format("{0} {1}\nHost: {2}\n{3} {4}\n User: {5}",
                                                context.Request.Method,
                                                context.Request.Url.Path + context.Request.Url.QueryString,
                                                context.Request.Url.Host,
                                                context.Response.StatusCode,
                                                context.Response.StatusReason,
                                                context.User.Email
                                                ))
                        ).ToString();
            }</set-body>
      </send-one-way-request>
    </when>
</choose>

Öğeler

Öğe Açıklama Gerekli
set-method Kök öğesi. öğesinin değeri HTTP yöntemini belirtir. Evet

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, hata üzerine

  • İlke kapsamları: tüm kapsamlar

Durum kodunu ayarlama

İlke, set-status HTTP durum kodunu belirtilen değere ayarlar.

Not

İlkenin öğelerini ve alt öğelerini ilke bildiriminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<set-status code="" reason=""/>

Örnek

Bu örnekte yetkilendirme belirteci geçersizse 401 yanıtının nasıl döndürüleceği gösterilmektedir. Daha fazla bilgi için bkz. Azure API Management hizmetinden dış hizmetleri kullanma

<choose>
  <when condition="@((bool)((IResponse)context.Variables["tokenstate"]).Body.As<JObject>()["active"] == false)">
    <return-response response-variable-name="existing response variable">
      <set-status code="401" reason="Unauthorized" />
      <set-header name="WWW-Authenticate" exists-action="override">
        <value>Bearer error="invalid_token"</value>
      </set-header>
    </return-response>
  </when>
</choose>

Öğeler

Öğe Açıklama Gerekli
set-status Kök öğesi. Evet

Öznitelikler

Öznitelik Açıklama Gerekli Varsayılan
code="integer" Döndürülecek HTTP durum kodu. Evet Yok
reason="string" Durum kodunu döndürme nedeninin açıklaması. Evet Yok

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, arka uç, hatada
  • İlke kapsamları: tüm kapsamlar

Değişken ayarlama

İlke set-variable bir bağlam değişkeni bildirir ve bir ifade veya dize değişmez değeri aracılığıyla belirtilen bir değer atar. İfade değişmez değer içeriyorsa dizeye dönüştürülür ve değerin türü olur System.String.

Not

İlkenin öğelerini ve alt öğelerini ilke bildiriminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<set-variable name="variable name" value="Expression | String literal" />

Örnek

Aşağıdaki örnekte, gelen bölümünde ayarlanmış bir değişken ilkesi gösterilmektedir. Bu küme değişkeni ilkesi, istek üst bilgisi veya iPhonemetnini iPad içeriyorsa true User-Agent olarak ayarlanmış bir isMobile Boole bağlam değişkeni oluşturur.

<set-variable name="IsMobile" value="@(context.Request.Headers.GetValueOrDefault("User-Agent","").Contains("iPad") || context.Request.Headers.GetValueOrDefault("User-Agent","").Contains("iPhone"))" />

Öğeler

Öğe Açıklama Gerekli
set-variable Kök öğesi. Evet

Öznitelikler

Öznitelik Açıklama Gerekli
name Değişkenin adı. Evet
değer Değişkenin değeri. Bu bir ifade veya değişmez değer olabilir. Evet

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, arka uç, hatada
  • İlke kapsamları: tüm kapsamlar

İzin verilen türler

İlkede set-variable kullanılan ifadeler aşağıdaki temel türlerden birini döndürmelidir.

  • System.Boolean
  • System.SByte
  • System.Byte
  • System.UInt16
  • System.UInt32
  • System.UInt64
  • System.Int16
  • System.Int32
  • System.Int64
  • Decimal
  • System.Single
  • Double
  • System.Guid
  • System
  • Char
  • Datetime
  • Timespan
  • System.Byte mı?
  • System.UInt16 mı?
  • System.UInt32?
  • System.UInt64?
  • System.Int16 mı?
  • System.Int32?
  • System.Int64?
  • Decimal?
  • System.Single?
  • Double?
  • System.Guid?
  • System?
  • Char?
  • Datetime?

İzleme

İlke API trace Inspector çıkışına, Application Insights telemetrilerine ve/veya Kaynak Günlüklerine özel bir izleme ekler.

  • İlke, izleme tetiklendiğinde API Inspector çıkışına özel bir izleme ekler; örneğin Ocp-Apim-Trace istek üst bilgisi mevcut ve true Ocp-Apim-Subscription-Key olarak ayarlanmış ve istek üst bilgisi mevcut ve izlemeye izin veren geçerli bir anahtar barındırıyor.
  • İlke, Application Insights tümleştirmesi etkinleştirildiğinde ve severity ilkede belirtilen tanılama ayarında belirtilene eşit veya bundan verbosity büyük olduğunda Application Insights'ta bir İzleme telemetrisi oluşturur.
  • Kaynak Günlükleri etkinleştirildiğinde ve ilkede belirtilen önem düzeyi tanılama ayarında belirtilen ayrıntı düzeyinden yüksek veya daha yüksek olduğunda ilke günlük girdisine bir özellik ekler.
  • İlke Application Insights örneklemeden etkilenmez. İlkenin tüm çağrıları günlüğe kaydedilir.

Not

İlkenin öğelerini ve alt öğelerini ilke deyiminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi


<trace source="arbitrary string literal" severity="verbose|information|error">
    <message>String literal or expressions</message>
    <metadata name="string literal or expressions" value="string literal or expressions"/>
</trace>

Örnek

<trace source="PetStore API" severity="verbose">
    <message>@((string)context.Variables["clientConnectionID"])</message>
    <metadata name="Operation Name" value="New-Order"/>
</trace>

Öğeler

Öğe Açıklama Gerekli
izleme Kök öğesi. Evet
message Günlüğe kaydedilecek dize veya ifade. Evet
meta veriler Application Insights İzleme telemetrisine özel bir özellik ekler. Hayır

Öznitelikler

Öznitelik Açıklama Gerekli Varsayılan
kaynak İzleme görüntüleyicisi için anlamlı olan ve iletinin kaynağını belirten dize değişmez değeri. Evet Yok
önem derecesi İzlemenin önem düzeyini belirtir. İzin verilen değerler verbose, information, error (en düşükten en yükseğe). Hayır Ayrıntılı
name Özelliğin adı. Evet Yok
değer Özelliğin değeri. Evet Yok

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, arka uç, hatada

  • İlke kapsamları: tüm kapsamlar

Wait

İlke, wait hemen alt ilkelerini paralel olarak yürütür ve tamamlanmadan önce ilk alt ilkelerinin tümünün veya birinin tamamlanmasını bekler. Bekleme ilkesinin anlık alt ilkeleri İstek gönder, Önbellekten değer al ve Denetim akışı ilkeleri olabilir.

Not

İlkenin öğelerini ve alt öğelerini ilke deyiminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<wait for="all|any">
  <!--Wait policy can contain send-request, cache-lookup-value,
        and choose policies as child elements -->
</wait>

Örnek

Aşağıdaki örnekte, ilkenin hemen alt ilkeleri olarak iki choose ilke wait vardır. Bu choose ilkelerin her biri paralel olarak yürütülür. Her choose ilke önbelleğe alınmış bir değeri almayı dener. Önbellek isabetsiz değeri varsa, değeri sağlamak için bir arka uç hizmeti çağrılır. Bu örnekte, özniteliği olarak ayarlandığından wait , for ilke tüm anlık alt ilkeleri tamamlanana allkadar tamamlanmaz. Bu örnekte bağlam değişkenleri (execute-branch-one, value-one, execute-branch-twove value-two) bu örnek ilkenin kapsamı dışında bildirilir.

<wait for="all">
  <choose>
    <when condition="@((bool)context.Variables["execute-branch-one="])">
      <cache-lookup-value key="key-one" variable-name="value-one" />
      <choose>
        <when condition="@(!context.Variables.ContainsKey("value-one="))">
          <send-request mode="new" response-variable-name="value-one">
            <set-url>https://backend-one</set-url>
            <set-method>GET</set-method>
          </send-request>
        </when>
      </choose>
    </when>
  </choose>
  <choose>
    <when condition="@((bool)context.Variables["execute-branch-two="])">
      <cache-lookup-value key="key-two" variable-name="value-two" />
      <choose>
        <when condition="@(!context.Variables.ContainsKey("value-two="))">
          <send-request mode="new" response-variable-name="value-two">
            <set-url>https://backend-two</set-url>
            <set-method>GET</set-method>
          </send-request>
        </when>
      </choose>
    </when>
  </choose>
</wait>

Öğeler

Öğe Açıklama Gerekli
Bekle Kök öğesi. Yalnızca send-requestalt öğe , cache-lookup-valueve choose ilkeleri içerebilir. Evet

Öznitelikler

Öznitelik Açıklama Gerekli Varsayılan
: İlkenin tüm anlık alt ilkelerin wait tamamlanmasını mı yoksa yalnızca bir ilkeyi mi bekleyeceğini belirler. İzin verilen değerler şunlardır:

- all - Tüm anlık alt ilkelerin tamamlanmasını bekleyin
- herhangi biri - herhangi bir anlık alt ilkenin tamamlanmasını bekleyin. İlk anlık alt ilke tamamlandıktan sonra, wait ilke tamamlanır ve diğer tüm anlık alt ilkelerin yürütülmesi sonlandırılır.
Hayır tümü

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

  • İlke bölümleri: gelen, giden, arka uç
  • İlke kapsamları: tüm kapsamlar

Sonraki adımlar

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