Akış değişkenli koşullar

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi

Koşullu ifadeler, tüm programlama dillerinde yaygın olarak kullanılan bir kontrol yapısıdır. API proxy yapılandırması, programlama dillerine benzer şekilde akışlar, politikalar, adımlar ve RouteRules için koşullu ifadeleri destekler. Koşullu ifadeler tanımlayarak API'niz için dinamik davranışlar tanımlarsınız. Bu dinamik davranış, XML'i yalnızca mobil cihazlar için JSON'a dönüştürme veya istek mesajının içerik türüne ya da HTTP fiiline göre bir arka uç URL'sine yönlendirme gibi işlemler yapmanıza olanak tanır.

Bu konuda, API yönetimi özelliklerini çalışma zamanında kod yazmadan dinamik olarak uygulamak için koşulları nasıl kullanacağınız gösterilmektedir.

Koşullu ifadeleri yapılandırma

Koşullu davranış, API proxy'lerinde koşullar ve değişkenler birlikte kullanılarak uygulanır. Koşullu ifade, Condition öğesi kullanılarak oluşturulur. Aşağıdaki koşul boş bir koşuldur:

<Condition></Condition>

Koşullu ifade oluşturmak için koşullu operatör ve değişken ekleyerek aşağıdaki yapıyı oluşturursunuz:

<Condition>{variable.name}{operator}{"value"}</Condition>

Desteklenen koşullu operatörler arasında = (eşittir), != (eşit değildir) ve > (büyüktür) bulunur. Okunabilirliği artırmak için koşulları metin olarak da yazabilirsiniz: equals, notequals, greaterthan.

URI yollarıyla çalışırken ~/ veya MatchesPath kullanabilirsiniz. Ayrıca, JavaRegex normal ifadelerini ~~ operatörüyle eşleştirebilirsiniz.

Koşullar, Arka uç API kaynaklarına koşullu akışlar oluşturma bölümünde açıklanan arka uç API kaynaklarına yönelik API proxy koşullu akışlarını tanımlamak için kullanılır. Koşulların tam listesi için Koşullar referansı başlıklı makaleyi inceleyin.

Değişkenler

Koşullar, değişkenlerin değerlerini değerlendirerek çalışır. Değişken, bir API proxy'si tarafından yürütülen HTTP işleminin veya API proxy yapılandırmasının bir özelliğidir. Bir API proxy'si bir uygulamadan istek aldığında Apigee Edge; sistem saati, uygulamanın ağ bilgileri, mesajlardaki HTTP üstbilgileri, API proxy yapılandırması, politika yürütmeleri vb. ile ilişkili uzun bir değişken listesi doldurur. Bu sayede, koşullu ifadeler oluşturmak için kullanabileceğiniz zengin bir bağlam elde edersiniz.

Değişkenler her zaman noktalı gösterim kullanır. Örneğin, istek mesajındaki HTTP üstbilgileri request.header.{header_name} adlı değişkenler olarak kullanılabilir. Dolayısıyla Content-type başlığını değerlendirmek için request.header.Content-type değişkenini kullanabilirsiniz. Örneğin, request.header.Content-type = "application/json", isteğin içerik türünün JSON olması gerektiğini belirtir.

Yalnızca istek mesajı GET olduğunda bir politikanın uygulanmasına neden olacak koşullu bir ifade oluşturmanız gerektiğini varsayalım. Bir isteğin HTTP fiilini değerlendiren bir koşul oluşturmak için aşağıdaki koşullu ifadeyi oluşturursunuz. Bu koşuldaki değişken request.verb. Değişkenin değeri GET. Operatör: =.

<Condition>request.verb = "GET"</Condition>
Şunları da kullanabilirsiniz: 
<Condition>request.verb equals "GET"</Condition>

Edge, koşulları değerlendirmek için bu tür bir ifade kullanır. Yukarıdaki örnek, istekle ilişkili HTTP fiili GET ise doğru olarak değerlendirilir. İstekle ilişkili HTTP fiili POST ise ifade, yanlış olarak değerlendirilir.

Dinamik davranışı etkinleştirmek için Akışlar, Adımlar ve RouteRules'a Koşullar ekleyebilirsiniz.

Bir akışa koşul eklediğinizde "koşullu akış" oluşturmuş olursunuz. Koşullu akışlar yalnızca koşul doğru olarak değerlendirildiğinde yürütülür. Koşullu bir akışa istediğiniz sayıda politika ekleyebilirsiniz. Koşullu akış, belirli ölçütleri karşılayan istek veya yanıt mesajları için son derece özel işleme kuralları oluşturmanıza olanak tanır.

Örneğin, yalnızca istek fiili GET olduğunda yürütülen bir akış oluşturmak için:

<Flows>
  <Flow name="ExecuteForGETs">
  <Condition>request.verb="GET"</Condition>
  </Flow>
</Flows>

GET'ler için bir akış, POST'lar için başka bir akış oluşturmak istiyorsanız:

<Flows>
  <Flow name="ExecuteForGETs">
  <Condition>request.verb="GET"</Condition>
  </Flow>
  <Flow name="ExecuteForPOSTs">
  <Condition>request.verb="POST"</Condition>
  </Flow>
</Flows>

Aşağıdaki örnekte gösterildiği gibi, koşulu politika adımının kendisine uygulayabilirsiniz. Aşağıdaki koşul, VerifyApiKey politikasının yalnızca istek mesajı POST ise uygulanmasına neden olur.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

Bu tür koşullu akışları tanımladıktan sonra bunlara politikalar ekleyebilirsiniz. Böylece bir API proxy'si, GET istekleri için bir politika grubu ve POST istekleri için başka bir politika grubu uygulayabilir.

Kapsamlı referans bilgileri için aşağıdaki kaynaklara bakın:

1. Örnek

Aşağıdaki örnekte, ProxyEndpoint yanıt akışında yapılandırılmış Convert-for-devices adlı tek bir koşullu akış gösterilmektedir. Koşulu, geçerli olduğu varlığa bir öğe olarak ekleyin. Bu örnekte koşul, akışın bir bileşenidir. Bu nedenle, ifade doğru olarak değerlendirildiğinde akış yürütülür.

<Flows>
  <Flow name="Convert-for-devices">
  <Condition>(request.header.User-Agent = "Mozilla")</Condition>
    <Response>
      <Step><Name>ConvertToJSON</Name></Step>
    </Response>
  </Flow>
</Flows>

Edge, bir uygulamadan alınan her istek için mevcut tüm HTTP üstbilgilerinin değerlerini değişken olarak depolar. İstek, User-Agent adlı bir HTTP üstbilgisi içeriyorsa bu üstbilgi ve değeri, request.header.User-Agent adlı bir değişken olarak depolanır.

Yukarıdaki ProxyEndpoint yapılandırması göz önüne alındığında Edge, koşulun doğru olarak değerlendirilip değerlendirilmediğini görmek için request.header.User-Agent değişkeninin değerini kontrol eder.

Koşul doğru olarak değerlendirilirse (yani request.header.User-Agent değişkeninin değeri Mozilla değerine eşitse) koşullu akış yürütülür ve ConvertToJSON adlı XMLtoJSON politikası uygulanır. Aksi takdirde akış yürütülmez ve XML yanıtı, istekte bulunan uygulamaya değiştirilmeden (XML biçiminde) döndürülür.

2. Örnek

Yanıt mesajını XML'den JSON'a dönüştürmeniz gereken belirli bir örnek kullanalım ancak bu örnek yalnızca mobil cihazlar için geçerli olsun. Öncelikle Weather API'den gelen XML biçimli yanıtı JSON'a dönüştürecek politikayı oluşturun:

<XMLToJSON name="ConvertToJSON">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

Yukarıdaki politika yapılandırması, API proxy'sine yanıt mesajını almasını, varsayılan ayarlarla XML'den JSON'a dönüştürme işlemi gerçekleştirmesini ve ardından sonucu yeni yanıt mesajına yazmasını söyler. (Bir istek mesajını XML'den JSON'a dönüştürüyorsanız bu değerlerin her ikisini de request olarak ayarlamanız yeterlidir.)

Yanıtları XML'den JSON'a dönüştürmek istediğiniz için dönüşümü gerçekleştirmek üzere koşullu bir yanıt akışı yapılandırmanız gerekir. Örneğin, tüm yanıtları istemci uygulamasına döndürülmeden önce XML'den JSON'a dönüştürmek için aşağıdaki ProxyEndpoint yanıt akışını yapılandırın.

<Flows>
  <Flow name="Convert-for-devices">
    <Response>
      <Step><Name>ConvertToJSON</Name></Step>
    </Response>
  </Flow>
</Flows>

API'yi standart isteği kullanarak çağırdığınızda yanıt JSON biçiminde olur.

Ancak hedefiniz, hava durumu raporlarını yalnızca istekte bulunan istemci bir mobil cihaz olduğunda JSON'a dönüştürmektir. Bu tür dinamik davranışları etkinleştirmek için akışa koşullu bir ifade eklemeniz gerekir.

Koşullu akışı test etme

Bu örnek istekte, HTTP User-Agent üstbilgisi Mozilla olarak ayarlanmıştır. Bu da koşullu ifadenin doğru olarak değerlendirilmesine ve koşullu akışın (Convert-for-devices) yürütülmesine neden olur.

$ curl -H "User-Agent:Mozilla" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

veya Python'un kullanılabildiği yerlerde kolay okunabilir şekilde yazdırmak için:

$ curl -H "User-Agent:Mozilla" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282 | python -mjson.tool

Örnek Yanıt:

. . .

"yweather_forecast": [
         {
              "code": "11",
              "date": "12 Dec 2012",
              "day": "Wed",
              "high": "55",
              "low": "36",
              "text": "Showers"
          },
          {
              "code": "32",
              "date": "13 Dec 2012",
              "day": "Thu",
              "high": "56",
              "low": "38",
              "text": "Sunny"
          }
      ]
  }

. . .

User-Agent başlığı olmadan veya Mozilla dışında bir değerle gönderilen istekler, XML biçimli bir yanıtla sonuçlanır.

$ curl http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Değiştirilmemiş XML yanıtı döndürülür.

Örnek Yanıt:

<yweather:forecast day="Wed" date="12 Dec 2012" low="36" high="55" text="Showers" code="11" /> <yweather:forecast day="Thu" date="13 Dec 2012" low="38" high="56" text="Sunny" code="32" />

Desen eşleştirme

Bu bölümde, Apigee akışında koşullarla kalıp eşleştirmenin nasıl kullanılacağı açıklanmaktadır.

Operatörler

Bu bölümde, koşullu ifadelerde aşağıdaki kalıp eşleştirme operatörlerinin nasıl kullanılacağı açıklanmaktadır:

Eşleşmeler

Öncelikle "Eşleşir" veya "~" koşullu operatörüne bakalım. Bu iki operatör aynıdır. İngilizce sürüm olan "Matches" daha kolay okunabilir bir seçenek olarak kabul edilir.

Özet: "Eşleşir" operatörü size iki olasılık sunar. Dizeyi tam olarak eşleştirin veya "*" ile joker karakter eşleşmesi yapın. Beklediğiniz gibi, joker karakter sıfır veya daha fazla karakterle eşleşir. Bunun nasıl çalıştığını görelim.

Aşağıdaki XML'de bir adım koşulu gösterilmektedir. Koşul doğru olarak değerlendirildiğinde SomePolicy politikasını yürütür. Bu örnekte, Edge'de isteğin yol son ekini depolayan yerleşik bir değişken olan proxy.pathsuffix değişkenini test ediyoruz. Ancak dize içeren herhangi bir akış değişkeninin değerini test edebileceğinizi unutmayın. Bu durumda, gelen isteğin temel yolu /animals ve istek /animals/cat ise yol son eki "/cat" dizesidir.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix Matches "/cat")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Soru: SomePolicy'nin yürütülmesine hangi proxy yolu son eki neden olur? Tek bir olasılık var.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat

Politika yürütülüyor mu? Evet, çünkü proxy yolu son eki "/cat" ile tam olarak eşleşiyor. Sonek /bat, /dog, "/" veya başka bir şeyse yürütülmez.

Şimdi, "*" joker karakterini kullandığımız şu koşullu ifadeyi inceleyelim:

<Condition>(proxy.pathsuffix Matches "/*at")</Condition>

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat

Politika yürütülüyor mu? Evet, çünkü joker karakter herhangi bir karakterle eşleşir ve "/cat" bir eşleşmedir.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/bat

Politika yürütülüyor mu? Evet, joker karakter herhangi bir karakterle eşleştiği için "/bat" bir eşleşmedir.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/owl

Politika yürütülüyor mu? Kesinlikle hayır. Joker karakter "o" ile eşleşse de "wl" harfleri eşleşmez.

Şimdi joker karakteri, son ekin sonuna taşıyalım:

<Condition>(proxy.pathsuffix Matches "/cat*")</Condition>

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat

Politika yürütülüyor mu? Evet, çünkü joker karakter, herhangi bir karakterin sıfır veya daha fazla örneğiyle eşleşir.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/bat

Politika yürütülüyor mu? "/bat" eşleşmiyor.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat123

Politika yürütülüyor mu? Evet, joker karakter sıfır veya daha fazla karakterle eşleşir. Bu nedenle "123" bir eşleşme oluşturur.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat/bird/mouse

Politika yürütülüyor mu? Evet, joker karakter sıfır veya daha fazla karakterle eşleştiği için "/bird/mouse" bir eşleşme oluşturur. Bunun gibi bir ifadenin, harf karakterlerinden sonraki her şeyle eşleştiği için başınızı nasıl ağrıtabileceğine dikkat edin.

Soru: "Eşleşir" operatörü büyük/küçük harfe duyarlı mıdır?

Evet. Şöyle bir koşulunuz olduğunu varsayalım:

<Condition>(proxy.pathsuffix Matches "/*At")</Condition>

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat

Politika yürütülüyor mu? Hayır, joker karakter herhangi bir harfle (büyük/küçük harf fark etmeksizin) eşleşir ancak küçük "a" harfi "A" ile eşleşmez.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/bAt

Politika yürütülüyor mu? Evet, büyük/küçük harf eşleşiyor.

Soru: Eşleşir operatörüyle karakterleri nasıl kaçırabilirim?

Ayrılmış karakterlerden çıkmak için yüzde "%" karakterini kullanın. Örneğin:

<Condition>(proxy.pathsuffix Matches "/c%*at")</Condition>

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat

Politika yürütülüyor mu? Hayır, eşleşme operatörü "c*at" dizesini tam olarak arar.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/c*at

Soru:Politika yürütülüyor mu?

Evet, bu yol biraz sıra dışı olsa da eşleşiyor.

JavaRegex

Gördüğünüz gibi, "Eşleşir" operatörü basit durumlar için idealdir. Ancak başka bir operatör olan "JavaRegex" veya "~~" operatörünü kullanabilirsiniz. JavaRegex'in daha okunabilir olduğu kabul edilir. Bunun dışında, bu iki operatör aynıdır. Normal ifade kalıbı eşleştirmeye izin verdiği için JavaRegex olarak adlandırılır ve Edge, Java dilindeki java.util.regex paketi sınıflarıyla aynı kurallara uyar. JavaRegex operatörünün çalışma şekli, Eşleşir operatöründen çok farklıdır. Bu nedenle, ikisini birbirine karıştırmamak önemlidir.

Özet: "JavaRegex" operatörü, koşullu ifadelerde normal ifade söz dizimini kullanmanıza olanak tanır.

Aşağıdaki kodda bir adım koşulu gösterilmektedir. Koşul doğru olarak değerlendirilirse SomePolicy politikasını yürütür. Bu örnekte, Edge'de isteğin yol son ekini depolayan yerleşik bir değişken olan proxy.pathsuffix değişkenini test ediyoruz. Gelen isteğin temel yolu /animals ve istek /animals/cat ise yol son eki, "/cat" dizesidir.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix JavaRegex "/cat")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Soru: SomePolicy'nin yürütülmesine hangi proxy yolu son eki neden olur? Eşleşir operatöründe olduğu gibi, bu durumda da yalnızca bir olasılık vardır.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat

Politika yürütülüyor mu? Evet, çünkü proxy yolu son eki "/cat" ile tam olarak eşleşiyor. Sonek /bat veya /dog ya da başka bir şeyse yürütülmez.

Şimdi "*" niceleyicisini kullanarak bir normal ifade oluşturalım. Bu niceleyici, önceki karakterin sıfır veya daha fazla tekrarıyla eşleşir.

<Condition>(proxy.pathsuffix JavaRegex "/c*t")</Condition>

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat

Politika yürütülüyor mu? Hayır "*" niceleyicisi, önceki karakterin (yani "c") sıfır veya daha fazla tekrarıyla eşleşir.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/ccccct

Politika yürütülüyor mu? Evet, çünkü joker karakter, önceki karakterin sıfır veya daha fazla örneğiyle eşleşir.

Ardından, önceki karakteri bir kez eşleştiren veya hiç eşleştirmeyen "?" niceleyicisini kullanırız.

<Condition>(proxy.pathsuffix JavaRegex "/ca?t")</Condition>

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat

Politika yürütülüyor mu? Evet. "?" niceleyicisi, önceki karakter olan "a" karakterinin sıfır veya bir tekrarıyla eşleşir.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/ct

Politika yürütülüyor mu? Evet. "?" niceleyicisi, önceki karakterin bir tanesiyle veya hiçbiriyle eşleşir. Bu durumda "a" karakteri olmadığından koşul doğru olarak değerlendirilir.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/caat

Politika yürütülüyor mu? Hayır. "?" niceleyicisi, önceki karakterlerden bir tanesiyle eşleşir. Bu karakter "a"dir.

Ardından, "[abc]" veya "gruplandırma" stilindeki normal ifadeyi kullanırız. "a", "b" veya "c" karakterleriyle eşleşir.

<Condition>(proxy.pathsuffix JavaRegex "/[cbr]at")</Condition>

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat

Politika yürütülüyor mu? Evet. Burada normal ifadeler kullanıyoruz ve "[cbr]" ifadesi "c", "b" VEYA "r" ile eşleşiyor. Aşağıdaki aramalar da eşleşir:

GET http://artomatic-test.apigee.net/matchtest/bat

GET http://artomatic-test.apigee.net/matchtest/rat

Ancak bu bir eşleşme değildir:

GET http://artomatic-test.apigee.net/matchtest/mat

Soru: JavaRegex operatörü büyük/küçük harfe duyarlı mıdır?

Evet. Şöyle bir koşulunuz olduğunu varsayalım:

<Condition>(proxy.pathsuffix JavaRegex "/ca?t")</Condition>

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat

Politika yürütülüyor mu? Evet, normal ifade, önceki karakterin ("a") sıfır veya bir tekrarıyla eşleşir.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cAt

Soru: Politika yürütülür mü?

Hayır, çünkü büyük "A" harfi küçük "a" harfiyle eşleşmez.

MatchesPath

MatchesPath operatörü "~/" şeklinde de belirtilebilir. Matches (~) ve JavaRegex (~~) operatörlerine benzer. Ancak MatchesPath tamamen farklıdır.

Bu operatörün bir yolu bir dizi parça olarak değerlendirdiğini unutmayın. Bu nedenle, yol /animals/cats/wild ise yolun "/animals", "/cats" ve "/wild" bölümlerinden oluştuğunu düşünebilirsiniz.

MatchesPath operatörü, iki joker karakter gösterimi kullanmanıza olanak tanır: tek yıldız (*) ve çift yıldız (**). Tek yıldız, bir yol öğesiyle eşleşir. Çift yıldız, bir veya daha fazla yol öğesiyle eşleşir.

Bunu bir örnek üzerinde inceleyelim. Bu örnekte, isteğin yol son ekini depolayan Edge'deki yerleşik bir değişken olan proxy.pathsuffix değişkenini test ediyoruz. Ancak dize içeren herhangi bir akış değişkeninin değerini test edebileceğinizi unutmayın.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/*")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Soru: SomePolicy'nin yürütülmesine hangi proxy yolu son eki neden olur?

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/animals

Soru: Politika yürütülür mü?

Hayır, çünkü koşul "/animals" ifadesinden sonra "/*" ile belirtilen başka bir yol öğesi gerektiriyor.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/animals/

Politika yürütülüyor mu? Evet, yolun başka bir yol öğesi ("/animals/" işaretinden sonraki kısım) var ancak bu öğe boş.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/animals/cats

Politika yürütülüyor mu? Evet, çünkü yolun "/animals" ifadesinden sonra gelen bir öğesi ("/cats") var.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild

Soru: Politika yürütülür mü?

Hayır, çünkü tek yıldız yalnızca bir yol öğesiyle eşleşir ve bu API'de "/animals" ifadesinden sonra birden fazla öğe vardır.

Şimdi çift yıldız işaretini kullanalım:

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/**")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Soru: SomePolicy'nin yürütülmesine hangi proxy yolu son eki neden olur?

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/animals

Politika yürütülüyor mu? Hayır, çünkü koşul, "/**" tarafından belirtilen en az bir yol öğesinin bulunmasını gerektiriyor.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/animals/

Politika yürütülüyor mu?

Evet, yolun başka bir yol öğesi var ("/animals/" işaretinden sonraki kısım) ancak bu öğe boş.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/animals/cats

Politika yürütülüyor mu?

Evet, çünkü yolda "/animals" öğesinden sonra gelen en az bir öğe var.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild

Politika yürütülüyor mu?

Evet, çünkü yolda "/animals" öğesinden sonra gelen birden fazla öğe var.

Yıldız işaretlerini karıştırma

Yol eşlemenizi daha da hassaslaştırmak için tek (*) ve çift (**) yıldız işaretinin kombinasyonlarını kullanabilirsiniz.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/*/wild/**")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

API çağrısı:

Aşağıdaki API çağrılarının tümü eşleşme oluşturur:

GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild/

ve

GET http://artomatic-test.apigee.net/matchtest/animals/dogs/wild/austrailian

ve

GET http://artomatic-test.apigee.net/matchtest/animals/birds/wild/american/finches

API kaynakları

RESTful hizmetleri, API kaynakları koleksiyonlarıdır. API kaynağı, geliştiricilerin API'nizi çağırarak erişebileceği bir varlığı tanımlayan URI yolu parçasıdır. Örneğin, hizmetiniz hava durumu raporları ve hava durumu tahminleri sağlıyorsa arka uç hizmetiniz iki API kaynağı tanımlayabilir:

  • http://mygreatweatherforecast.com/reports
  • http://mygreatweatherforecast.com/forecasts

Bir API proxy'si oluşturduğunuzda (İlk API proxy'nizi oluşturma bölümünde gösterildiği gibi) en azından arka uç hizmetinizle eşlenen bir takma ad ana URL'si oluşturursunuz. Örneğin:

Arka uç ana URL'si Yeni/eşdeğer API proxy URL'si
http://mygreatweatherforecast.com http://{your_org}-{environment}.apigee.net/mygreatweatherforecast

Bu noktada, her iki ana URL'yi de kullanarak arka ucunuza API çağrıları yapabilirsiniz. Ancak API proxy URL'sini kullandığınızda işler ilginçleşmeye başlar.

API proxy'sini kullandığınızda Edge'in toplamaya başladığı API analizlerine ek olarak proxy'ler, arka ucunuzdaki kaynaklarla eşlenen koşullu akışlar tanımlamanıza da olanak tanır. Özetle, "/reports kaynağına bir GET çağrısı gelirse Edge bir şey yapmalıdır."

Aşağıdaki resimde, aynı arka uca erişen iki URL arasındaki davranış farkı gösterilmektedir. Biri proxy'si olmayan kaynak URL'si, diğeri ise aynı arka uç kaynağına koşullu akışı olan bir Edge API proxy'sidir. Koşullu akışları aşağıda daha ayrıntılı olarak açıklayacağız.

API proxy'lerinin belirli arka uç kaynaklarıyla eşlenmesi

Arka uç hizmetinin ana URL'siyle eşlenen bir API proxy'si URL'siyle (proxy'yi oluşturduğunuzda), daha önce bahsedilen /reports ve /forecasts kaynakları gibi belirli kaynaklara koşullu akışlar ekleyebilirsiniz.

Edge'in, /reports veya /forecasts kaynaklarına çağrı geldiğinde "bir şey yapmasını" istediğinizi varsayalım. Bu noktada Edge'e ne yapacağını söylemiyorsunuz, yalnızca bu kaynaklara yapılan çağrıları dinlemesi gerektiğini belirtiyorsunuz. Bunu koşullarla yaparsınız. Edge API proxy'nizde /reports ve /forecasts için koşullu akışlar oluşturabilirsiniz. Kavramsal amaçlar doğrultusunda, aşağıdaki API proxy XML'i bu koşulların nasıl görünebileceğini gösterir.

<Flows>
    <Flow name="reports">
        <Description/>
        <Request/>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
    </Flow>
    <Flow name="forecasts">
        <Description/>
        <Request/>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/forecasts") and (request.verb = "GET")</Condition>
    </Flow>
</Flows>

Bu koşullar şunları belirtir: "URL'de /reports ve /forecasts ile bir GET isteği geldiğinde Edge, bu akışlara eklediğiniz politikalar aracılığıyla sizden (API geliştiricisi) aldığı talimatları uygular.

Şimdi, bir koşul karşılandığında Edge'e ne yapacağını söylemeye bir örnek verelim. Aşağıdaki API proxy XML'inde, https://yourorg-test.apigee.net/mygreatweatherforecast/reports adresine bir GET isteği gönderildiğinde Edge, yanıttaki "XML-to-JSON-1" politikasını yürütür.

<Flows>
    <Flow name="reports">
        <Description/>
        <Request/>
        <Response>
            <Step>
                <Name>XML-to-JSON-1</Name>
            </Step>
        </Response>
        <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
</Flow>

Bu isteğe bağlı koşullu akışlara ek olarak her API proxy'si iki varsayılan akışla birlikte gelir: koşullu akışlarınızdan önce yürütülen bir <PreFlow> ve koşullu akışlarınızdan sonra yürütülen bir <PostFlow>. Bunlar, bir API proxy'sine herhangi bir çağrı yapıldığında politikaları yürütmek için kullanışlıdır. Örneğin, erişilen arka uç kaynağından bağımsız olarak her çağrıda bir uygulamanın API anahtarını doğrulamak istiyorsanız <PreFlow> öğesine bir API Anahtarını Doğrulama politikası ekleyebilirsiniz. Akışlar hakkında daha fazla bilgi için Akışları yapılandırma başlıklı makaleyi inceleyin.

Arka uç kaynaklarına koşullu akışlar oluşturma

API proxy'sinde arka uç kaynaklarına koşullu akışlar tanımlamak tamamen isteğe bağlıdır. Ancak bu koşullu akışlar, ayrıntılı yönetim ve izleme uygulamanıza olanak tanır.

Şunları yapabilirsiniz:

  • Yönetimi, API modelinizin semantiğini yansıtacak şekilde uygulayın.
  • Politikaları ve komut dosyasıyla oluşturulmuş davranışları ayrı ayrı kaynak yollarına (URI'ler) uygulama
  • Analytics hizmetleri için ayrıntılı metrikler toplama

Örneğin, arka ucunuzdaki /developers ve /apps kaynaklarına farklı türde mantıklar uygulamanız gerektiğini varsayalım.

Bunun için API proxy'nize iki koşullu akış eklersiniz: /developers ve /apps.

API proxy düzenleyicisi Gezgin bölmesinin Geliştirme görünümünde, Proxy Uç Noktaları'ndaki varsayılanın yanındaki + simgesini tıklayın.

"New Conditional Flow" (Yeni Koşullu Akış) penceresinde aşağıdaki anahtar yapılandırmaları girersiniz:

  • Akış adı: Geliştiriciler
  • Condition Type: Path
  • Yol: /developers

URI'nin sonunda /developers ile proxy'ye bir çağrı gönderilirse koşul tetiklenir (ve politikalar yürütülür).

Şimdi /apps için koşullu bir akış ekleyin ve koşulun bir istekteki hem URI hem de POST fiiliyle tetiklenmesini istediğinizi varsayın. Yapılandırma, aşağıdakilerin ayarlanmasını içerir:

  • Akış Adı: Uygulamalar
  • Koşul Türü: Yol ve Fiil
  • Yol: /apps
  • Fiil: POST

URI'nin sonunda /apps ve bir POST fiiliyle proxy'ye çağrı gönderilirse koşul tetiklenir (ve politikalar yürütülür).

Gezgin bölmesinde, Uygulamalar ve Geliştiriciler için yeni akışlar görürsünüz.

API proxy düzenleyicisi kod görünümünde koşullu akış yapılandırmasını görüntülemek için akışlardan birini seçin:

<Flow name="Apps">
    <Description>Developer apps registered in Developer Services</Description>
    <Request/>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/apps") and (request.verb = "POST")</Condition>
</Flow>

Gördüğünüz gibi API kaynakları, gelen isteğin URI yolunu değerlendiren koşullu akışlardır. (proxy.pathsuffix değişkeni, ProxyEndpoint yapılandırmasında yapılandırılan BasePath'i izleyen isteğin URI'sini tanımlar.)

Tanımladığınız her API kaynağı, API proxy'sindeki koşullu bir akış tarafından uygulanır. Akışları yapılandırma bölümüne bakın.

API proxy'sini test ortamına dağıttıktan sonra aşağıdaki istek:

http://{org_name}-test.apigee.net/{proxy_path}/apps

koşulun doğru olarak değerlendirilmesine neden olur ve bu akış, ilişkili tüm politikalarla birlikte yürütülür.

Aşağıdaki örnek koşul, /apps kaynağına yapılan çağrıları, sonunda eğik çizgi (/apps veya /apps/**) olsun ya da olmasın tanımak için bir Java normal ifadesi kullanır:

<Condition>(proxy.pathsuffix JavaRegex "/apps(/?)") and (request.verb = "POST")</Condition>

Bu koşul türü hakkında daha fazla bilgi için Apigee Topluluğu'ndaki How to match regardless ... (Nasıl eşleştirilir?) başlıklı makaleyi inceleyin.

Hiyerarşik URI'leri modelleme

Bazı durumlarda hiyerarşik API kaynaklarınız olur. Örneğin, Developer Services API, bir geliştiriciye ait tüm uygulamaları listelemek için bir yöntem sunar. URI yolu:

/developers/{developer_email}/apps

Bir koleksiyondaki her öğe için benzersiz bir kimliğin oluşturulduğu kaynaklarınız olabilir. Bu durum bazen aşağıdaki gibi açıklanır:

/genus/:id/species

Bu yol, aşağıdaki iki URI için de geçerlidir:

/genus/18904/species
/genus/17908/species

Bu yapıyı bir API kaynağında temsil etmek için joker karakterler kullanabilirsiniz. Örneğin:

/developers/*/apps
 
/developers/*example.com/apps
 
/genus/*/species

bu hiyerarşik URI'leri API kaynakları olarak uygun şekilde çözümler.

Bazı durumlarda, özellikle de derin hiyerarşik API'ler için belirli bir URI parçasının altındaki her şeyi çözmek isteyebilirsiniz. Bunun için kaynak tanımınızda çift yıldız joker karakteri kullanın. Örneğin, aşağıdaki API kaynağını tanımlarsanız: 
/developers/**

Bu API kaynağı, aşağıdaki URI yollarını çözümler:

/developers/{developer_email}/apps
/developers/{developer_email}/keys
/developers/{developer_email}/apps/{app_id}/keys

Koşullu akış koşulu, API proxy tanımında şu şekilde görünür:

<Condition>(proxy.pathsuffix MatchesPath "/developers/**") and (request.verb = "POST")</Condition>

Diğer örnekler

RouteRule'a eklenen koşul

<RouteRule name="default">
 <!--this routing executes if the header indicates that this is an XML call. If true, the call is routed to the endpoint XMLTargetEndpoint-->
  <Condition>request.header.content-type = "text/xml"</Condition>
  <TargetEndpoint>XmlTargetEndpoint</TargetEndpoint>
</RouteRule>

Politikaya eklenen koşul

<Step>
<!--the policy MaintenancePolicy only executes if the response status code is exactly 503-->
  <Condition>response.status.code = 503</Condition>
  <Name>MaintenancePolicy</Name>
</Step>

Koşullu Akış

<!-- this entire flow is executed only if the request verb is a GET-->
<Flow name="GetRequests">
  <Condition>request.verb="GET"</Condition>
  <Request>
    <Step>
<!-- this policy only executes if request path includes a term like statues-->
<Condition>request.path ~ "/statuses/**"</Condition>
      <Name>StatusesRequestPolicy</Name>
    </Step>
  </Request>
  <Response>
    <Step>
<!-- this condition has multiple expressions. The policy executes if the response code status is exactly 503 or 400-->
<Condition>(response.status.code = 503) or (response.status.code = 400)</Condition>
      <Name>MaintenancePolicy</Name>
    </Step>
  </Response>
</Flow>

Koşullardaki örnek operatörler

Koşul oluşturmak için kullanılan operatörlere dair bazı örnekler:

  • request.header.content-type = "text/xml"
  • request.header.content-length < 4096 && request.verb = "PUT"
  • response.status.code = 404 || response.status.code = 500
  • request.uri MatchesPath "/*/statuses/**"
  • request.queryparam.q0 NotEquals 10

Pratik bir örnek: Yolun sonundaki "/" işaretini yoksayma

Edge geliştiricileri genellikle şu iki yol son ekini de işlemek ister: "/cat" ve "/cat/". Bunun nedeni, bazı kullanıcıların veya istemcilerin API'nizi yolun sonuna fazladan eğik çizgi ekleyerek çağırabilmesidir. Bu durumu koşullu ifadelerinizde işleyebilmeniz gerekir. Bu kullanım alanı, Apigee Topluluğu'nda ele alınmıştır.

İsterseniz bunu normal ifade kullanmadan şu şekilde yapabilirsiniz:

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>((proxy.pathsuffix = "/cat") OR (proxy.pathsuffix = "/cat/")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Bu iyi bir seçenektir. Net ve okunabilir olmalıdır.

Ancak normal ifadeyle de aynı şeyi yapabilirsiniz. Parantezler, ifadenin normal ifade kısmını gruplandırmak için kullanılır ancak zorunlu değildir.

<Condition>(proxy.pathsuffix JavaRegex "/cat(/?)"</Condition>

API çağrıları:

GET http://artomatic-test.apigee.net/matchtest/cat
or
GET http://artomatic-test.apigee.net/matchtest/cat/

Politika yürütülüyor mu? Evet. Normal ifadede "?" karakterinin, önceki karakterin sıfır veya bir tekrarıyla eşleşme anlamına geldiğini unutmayın. Bu nedenle, hem "/cat" hem de "/cat/" eşleşir.

API çağrısı:

GET http://artomatic-test.apigee.net/matchtest/cat/spotted

Politika yürütülüyor mu? Hayır. Normal ifade, önceki karakterin sıfır veya yalnızca bir tekrarıyla eşleşir ve başka bir şeye izin verilmez.

JavaRegex ile rastgele dizeleri eşleştirme

Bu konudaki tüm örneklerde, yerleşik akış değişkenlerinden biri olan proxy.pathsuffix'in nasıl eşleştirileceği gösterilmektedir. Herhangi bir dize veya akış değişkeninde (proxy.pathsuffix gibi yerleşik bir akış değişkeni olsun veya olmasın) kalıp eşleştirme yapabileceğinizi bilmek faydalı olacaktır.

Örneğin, rastgele bir dizeyi test eden bir koşulunuz varsa (belki arka uç yükünde döndürülen bir dize veya kimlik doğrulama sunucusu aramasından döndürülen bir dize) bunu test etmek için eşleşen operatörleri kullanabilirsiniz. JavaRegex kullanırsanız normal ifade, konu dizesinin tamamıyla karşılaştırılır. Özne "abc" ve normal ifade "[a-z]" ise eşleşme olmaz. Çünkü "[a-z]" tam olarak bir alfabetik karakterle eşleşir. "[a-z]+" ifadesi, "[a-z]*" ve "[a-z]{3}" ifadeleri gibi çalışır.

Bunu somut bir örnekle açıklayalım. Kimlik doğrulama sunucusunun, virgülle ayrılmış bir dize olarak rol listesi döndürdüğünü varsayalım: "editor, author, guest".

Düzenleyici rolünün varlığını test etmek için bu yapı işe yaramaz çünkü "editor" dizesi, tüm dizenin yalnızca bir parçasıdır.

<Condition>returned_roles ~~ "editor"</Condition>

Ancak aşağıdaki yapı çalışır:

<Condition>returned_roles ~~ ".*\beditor\b.*")</Condition>

Bu ifade, .* öneki ve sonekiyle kelime sonlarını ve dizedeki diğer bölümleri dikkate aldığı için işe yarar.

Bu örnekte, "editor" için de eşleşme operatörüyle test yapabilirsiniz:

<Condition>returned_roles ~~ "*editor*")</Condition>

Ancak daha fazla hassasiyete ihtiyaç duyduğunuz durumlarda JavaRegex genellikle daha iyi bir seçimdir.

JavaRegex ifadelerinde çift tırnak işaretlerini kod dışı bırakma

Koşul söz dizimi, JavaRegex ifadesinin çift tırnak içine alınmasını gerektirir. Bu nedenle, çift tırnak içeren bir normal ifadeniz varsa bunları eşleştirmek için alternatif bir yönteme ihtiyacınız vardır. Cevap: Unicode. Örneğin, aşağıdaki gibi çift tırnak içeren bir üstbilgi ilettiğinizi varsayalım: 
 -H 'content-type:multipart/related; type="application/xop+xml"'
 Bu başlığı bir normal ifade koşuluyla eşleştirmeye çalışırsanız ifade çift tırnak içerdiğinden Geçersiz Koşul hatası alırsınız: 
request.header.Content-Type ~~ "(multipart\/related)(; *type="application\/xop\+xml\")"
 Bu sorunu çözmek için ASCII tabanlı çift tırnak işaretlerini Unicode eşdeğeri olan \u0022 ile değiştirmeniz gerekir. Örneğin, aşağıdaki ifade geçerlidir ve beklenen sonucu verir: 
request.header.Content-Type ~~ "(multipart\/related)(; *type=\u0022application\/xop\+xml\u0022)"