Akış değişkenlerini kullanma

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

Akış değişkenleri, kavramsal olarak politikalarınızdan veya yardımcı programlarınızdan (ör. izleme aracı) erişebileceğiniz nesnelerdir. Bu politikalar, Apigee Edge tarafından işlenen bir API işlemiyle ilişkili durumu korumanıza olanak tanır.

Akış değişkenleri nedir?

Akış değişkenleri, bir API proxy akışı bağlamında bulunur ve bir API işlemindeki durumu, adlandırılmış değişkenlerin bir yazılım programındaki durumu izlediği şekilde izler. Akış değişkenlerinde aşağıdaki gibi bilgiler saklanır:

  • İstekte bulunan uygulamadan gönderilen IP adresi, başlıklar, URL yolu ve yük
  • Edge'in bir isteği aldığı tarih ve saat gibi sistem bilgileri
  • Bir politika yürütüldüğünde elde edilen veriler. Örneğin, bir OAuth jetonunu doğrulayan bir politika yürütüldükten sonra Edge, istekte bulunan uygulamanın adı gibi bilgileri içeren akış değişkenleri oluşturur.
  • Hedef sistemden gelen yanıtla ilgili bilgiler

Bazı değişkenler Edge'e "yerleşiktir" ve bir API isteği alındığında otomatik olarak doldurulur. API işlemi boyunca kullanılabilir. Ayrıca AssignMessage politikası gibi politikaları kullanarak veya JavaScript, Node.js ve Java kodunda kendi özel değişkenlerinizi oluşturabilirsiniz.

Gördüğünüz gibi, değişkenlerin kapsamı vardır ve erişilebilir oldukları yerler kısmen API proxy akışında oluşturuldukları zamana bağlıdır. Genel olarak, bir değişken oluşturulduğunda API işlemi akışında daha sonra yürütülen tüm politikalarda ve kodlarda kullanılabilir.

Akış değişkenleri nasıl kullanılır?

Akış değişkenleri politikalarda ve koşullu akışlarda kullanılır:

  • Politikalar, akış değişkenlerinden durumu alabilir ve bunları işlerini yapmak için kullanabilir.

    Örneğin, VerifyJWT politikası, doğrulanacak jetonu bir akış değişkeninden alabilir ve ardından üzerinde doğrulama gerçekleştirebilir. Başka bir örnek olarak, JavaScript politikası akış değişkenlerini alabilir ve bu değişkenlerdeki verileri kodlayabilir.

  • Koşullu akışlar, bir API'nin akışını Edge üzerinden yönlendirmek için akış değişkenlerine başvurabilir. Bu, programlamada bir anahtar ifadesinin çalışma şekline benzer.

    Örneğin, bir hatayı döndürme politikası yalnızca belirli bir akış değişkeni ayarlandığında yürütülebilir. Son olarak, bir Node.js hedef uygulamasında akış değişkenlerini alabilir ve ayarlayabilirsiniz.

Değişkenlerin bu bağlamların her birinde nasıl kullanıldığına dair örneklere bakalım.

Politikalardaki akış değişkenleri

Bazı politikalar akış değişkenlerini giriş olarak alır.

Örneğin, aşağıdaki AssignMessage politikası, client.ip akış değişkeninin değerini alır ve My-Client-IP adlı bir istek başlığına yerleştirir. Bu politika, istek akışına eklenirse arka uç hedefine iletilen bir üstbilgi ayarlar. Yanıt akışında ayarlanırsa başlık, istemci uygulamasına geri gönderilir.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Bir başka örnek olarak, Kota politikası yürütüldüğünde çeşitli akış değişkenleri politika ile ilgili değerlerle doldurulur. Bu değişkenlerden birine ratelimit.my-quota-policy.used.count adı verilir (my-quota-policy, ilgilendiğiniz kota politikasının adıdır).

Daha sonra "Mevcut kota sayısı maksimumun% 50'sinin altındaysa ve saat 09:00 ile 17:00 arasındaysa farklı bir kota uygula" koşullu akışını çalıştırabilirsiniz. Bu koşul, mevcut kota sayısının değerine ve yerleşik Edge değişkenlerinden biri olan system.time adlı bir akış değişkenine bağlı olabilir.

Koşullu akışlardaki akış değişkenleri

Koşullu akışlar akış değişkenlerini değerlendirir ve proxy'lerin dinamik olarak davranmasını sağlar. Koşullar genellikle akışların, adımların ve rota kurallarının davranışını değiştirmek için kullanılır.

Burada, bir proxy akışı adımında request.verb değişkeninin değerini değerlendiren koşullu bir akış gösterilmektedir. Bu durumda, istek fiili POST ise VerifyAPIKey politikası yürütülür. Bu, API proxy yapılandırmalarında kullanılan yaygın bir kalıptır.

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

Peki request.verb, client.ip ve system.time gibi değişkenler nereden geliyor? Ne zaman oluşturulur ve değerle doldurulur? Değişkenlerin ne zaman oluşturulduğunu ve ne zaman kullanılabildiğini anlamak için Akış değişkeni kapsamını anlama başlıklı makaleyi inceleyin.

JavaScript politikasıyla çağrılan JavaScript kodundaki akış değişkenleri

JavaScript politikası ile JavaScript kodunu bir API proxy akışının bağlamı içinde yürütebilirsiniz. Bu politika tarafından yürütülen JavaScript, Apigee JavaScript nesne modelini kullanır. Bu model, özel kodunuzun, kodunuzun yürütüldüğü API proxy akışıyla ilişkili istek, yanıt ve bağlam nesnelerine erişmesini sağlar. Örneğin, bu kod, akış değişkeni target.name'den elde edilen değerle bir yanıt başlığı ayarlar.

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

Değişkenleri okumak ve ayarlamak için JavaScript kullanma tekniği, AssignMessage politikası ile yapabileceğiniz çalışmaya (daha önce gösterilmişti) benzer. Bu özellik, Edge'de aynı türden işlemleri yapmanın başka bir yoludur. Unutulmaması gereken nokta, JavaScript politikası tarafından yürütülen JavaScript'in, API proxy akışında mevcut olan ve kapsamda bulunan tüm akış değişkenlerine erişebildiğidir.

Node.js kodundaki akış değişkenleri

apigee-access modülünü gerektirerek Edge'e dağıtılan Node.js kodunda akış değişkenlerini ayarlayabilir ve bunlara erişebilirsiniz.

custom.foo adlı bir değişkenin Bar değerine ayarlandığı basit bir örneği burada bulabilirsiniz. Bu yeni değişken ayarlandıktan sonra, Node.js kodu yürütüldükten sonra proxy akışında gerçekleşen tüm politikalarda veya diğer kodlarda kullanılabilir.

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

apigee-access kullanarak değişkenlerle çalışma hakkında daha fazla bilgiyi Node.js'de akış değişkenlerine erişme başlıklı makalede bulabilirsiniz.

Akış değişkeni kapsamını anlama

Kapsam değişkeni, bir API proxy'si çağrısının akışı veya genel "yaşam döngüsü" ile ilgilidir.

API proxy'sinin akışını görselleştirme

Akış değişkeni kapsamını anlamak için mesajların bir API proxy'sinden akış şeklini anlamak veya görselleştirmek önemlidir. API proxy'si, akış olarak düzenlenmiş bir dizi mesaj işleme adımından oluşur. Bir proxy akışındaki her adımda, proxy kendisine sunulan bilgileri değerlendirir ve bir sonraki adımda ne yapacağına karar verir. Bu süreçte proxy, politika kodu yürütebilir veya koşullu dallanma gerçekleştirebilir.

Aşağıdaki şekilde bu akış sırası gösterilmektedir. Akışların dört ana segmentten oluştuğunu unutmayın: ProxyEndpoint isteği, TargetEndpoint isteği, TargetEndpoint yanıtı ve ProxyEndpoint yanıtı.

Bu konunun geri kalanında akış değişkenlerini incelemeye başlarken bu akış yapısını aklınızda bulundurun.

Değişken kapsamı ile proxy akışı arasındaki ilişki

Daha önce açıklandığı gibi, iletilerin bir proxy üzerinden nasıl aktığını görselleştirebildiğiniz anda değişken kapsamını anlamaya başlayabilirsiniz. Kapsam, bir değişkenin ilk kez örneklendiği proxy akışı yaşam döngüsündeki noktayı ifade eder.

Örneğin, ProxyEndpoint istek segmentine eklenmiş bir politikanız varsa bu politika, TargetEndpoint istek segmenti kapsamındaki değişkenlere erişemez. Bunun nedeni, akışın TargetEndpoint istek segmentinin henüz yürütülmemiş olmasıdır. Bu nedenle, API proxy'sinin bu kapsamdaki değişkenleri doldurma şansı olmamıştır.

Aşağıdaki tabloda, değişken kapsamlarının tam listesi ve proxy akışında ne zaman kullanılabilecekleri gösterilmektedir.

Değişken kapsamı Bu değişkenlerin doldurulduğu yerler
proxy isteği ProxyEndpoint istek segmenti
hedef isteği TargetEndpoint istek segmenti
hedef yanıt TargetEndpoint yanıt segmenti
proxy yanıtı ProxyEndpoint yanıt segmenti
her zaman kullanılabilir Proxy, bir istek alır almaz. Bu değişkenler, tüm proxy akışı yaşam döngüsü boyunca kullanılabilir.

Örneğin, client.ip adlı yerleşik bir Edge değişkeni vardır. Bu değişkenin kapsamı "proxy isteği"dir. Proxy'yi çağıran istemcinin IP adresiyle otomatik olarak doldurulur. Bir istek ilk kez ProxyEndpoint'e ulaştığında doldurulur ve tüm proxy akışı yaşam döngüsü boyunca kullanılabilir.

target.url adlı başka bir yerleşik değişken vardır. Bu değişkenin kapsamı "hedef istek"tir. Bu alan, arka uç hedefine gönderilen istek URL'siyle birlikte TargetEndpoint istek segmentinde doldurulur. ProxyEndpoint isteğindeki target.url bölümüne erişmeye çalışırsanız NULL değeri alırsınız. Bu değişkeni kapsamda olmadan önce ayarlamaya çalışırsanız proxy hiçbir şey yapmaz (hata oluşturmaz ve değişkeni ayarlamaz).

Değişken kapsamı hakkında nasıl düşüneceğinizi gösteren basit bir örneği burada bulabilirsiniz. Bir istek nesnesinin (başlıklar, parametreler, gövde) tüm içeriğini kopyalayıp çağıran uygulamaya geri gönderilecek yanıt yüküne atamak istediğinizi varsayalım. Bu görev için AssignMessage politikasını kullanabilirsiniz. Politika kodu şu şekilde görünür:

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

Bu politika, request nesnesini kopyalayıp response nesnesine atar. Ancak bu politika, proxy akışında nereye yerleştirilmelidir? Yanıt değişkeninin kapsamı "hedef yanıtı" olduğundan, yanıtın TargetEndpoint yanıtına yerleştirilmesi gerekir.

Akış değişkenlerine referans verme

Apigee Edge'deki tüm yerleşik değişkenler, nokta gösterimi adlandırma kuralına uyar. Bu kural, değişkenin amacını belirlemeyi kolaylaştırır. Örneğin system.time.hour ve request.content.

Apigee, ilgili değişkenleri uygun şekilde düzenlemek için çeşitli önekler ayırır. Bu önekler şunlardır:

  • request
  • response
  • system
  • target

Bir değişkene politikada referans vermek için değişkeni süslü parantez içine alın. Örneğin, aşağıdaki AssignMessage politikası, client.ip değişkeninin değerini alır ve Client-IP adlı bir istek başlığına yerleştirir.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Koşullu akışlarda küme parantezleri gerekli değildir. Aşağıdaki örnek koşul, request.header.accept değişkenini değerlendirir:

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

Ayrıca, JavaScript ve Java kodunda akış değişkenlerine de başvurabilirsiniz. Daha fazla bilgi için aşağıdaki sayfaları inceleyin:

Akış değişkenlerinin veri türü

Bir akış değişkeninin her özelliğinin iyi tanımlanmış bir veri türü vardır (ör. Dize, Uzun, Tam Sayı, Boole veya Koleksiyon). Veri türlerini Akış değişkenleri referansı bölümünde bulabilirsiniz. Bir politika tarafından oluşturulan değişkenler için veri türü bilgileriyle ilgili olarak söz konusu politika referans konusuna bakın.

Manuel olarak oluşturduğunuz değişkenler, oluşturuldukları sırada verilen türü varsayar ve izin verilen değer türlerine bağlıdır. Örneğin, Node.js kodunda oluşturulan değişkenler; Number, String, Boolean, null veya undefined ile sınırlıdır.

Politikalarda akış değişkenlerini kullanma

Birçok politika, normal yürütülmelerinin bir parçası olarak akış değişkenleri oluşturur. Politika referansı dokümanlarında bu politikaya özgü değişkenlerin tümü yer alır.

Proxy'ler ve politikalarla çalışırken hangi değişkenlerin oluşturulduğunu ve ne için kullanıldığını öğrenmek için politika referansına bakın. Örneğin, kota politikası, kota sayıları ve sınırları, süre sonu vb. hakkında bilgi içeren bir değişken grubu oluşturur.

Bazı politika değişkenleri hata ayıklama için yararlıdır. Örneğin, bir proxy akışında belirli bir örnekte hangi değişkenlerin ayarlandığını görmek için İzleme Aracı'nı kullanabilirsiniz.

ExtractVariables politikası, özel değişkenleri iletilerden çıkarılan verilerle doldurmanıza olanak tanır. Sorgu parametrelerini, başlıkları ve diğer verileri ayıklayabilirsiniz. Örneğin, iletilerden belirli verileri ayıklamak için kalıpları kullanarak istek ve yanıt iletilerini ayrıştırabilirsiniz.

Aşağıdaki örnekte, Değişkenleri Ayıkla, bir yanıt mesajını ayrıştırır ve yanıttan alınan belirli verileri depolar. Politika, geocoderesponse.latitude ve geocoderesponse.longitude olmak üzere iki özel değişken oluşturur ve bunlara değerler atar.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Birçok politikanın otomatik olarak değişken oluşturduğunu unutmayın. Bu değişkenlere proxy akışı bağlamında erişebilirsiniz. Bu değişkenler, her bir politika konusu altındaki Politika referansı bölümünde belgelenmiştir.

JavaScript kodunda akış değişkenleriyle çalışma

Değişkenlere doğrudan bir API proxy'si bağlamında yürütülen JavaScript kodunda erişebilir ve bunları ayarlayabilirsiniz. Edge'de yürütülen JavaScript, Apigee JavaScript nesne modeli aracılığıyla proxy akışı değişkenlerine doğrudan erişebilir.

JavaScript kodundaki değişkenlere erişmek için bu nesnelerden herhangi birinde getter/setter yöntemlerini çağırın:

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

Gördüğünüz gibi, bu nesne referansları, API proxy'sinin akışını görselleştirme bölümünde daha önce açıklandığı gibi, proxy akış modeliyle ilgili tanıdık segmentlerle eşlenir.

context nesnesi, sistem değişkenleri gibi "genel olarak" kullanılabilen değişkenlere karşılık gelir. Örneğin, geçerli yılı almak için context nesnesinde getVariable() işlevini çağırabilirsiniz:

var year = context.getVariable('system.time.year');

Benzer şekilde, bir özelleştirilebilen değişkenin değerini veya herhangi bir yazılabilir hazır değişkenin değerini ayarlamak için setVariable() işlevini çağırabilirsiniz. Burada, organization.name.myorg adlı bir özelleştirilebilen değişken oluşturup buna bir değer atıyoruz.

var org = context.setVariable('organization.name.myorg', value);

Bu değişken context nesnesiyle oluşturulduğu için tüm akış segmentlerinde kullanılabilir (bu, aslında genel bir değişken oluşturmaya benzer).

Ayrıca, JavaCallout politikası ile yürüttüğünüz Java kodunda proxy akışı değişkenlerini alabilir/ayarlayabilirsiniz.

Node.js uygulamalarında akış değişkenlerine erişme

Edge'e dağıtılan Node.js kodundan akış değişkenlerini alabilir, ayarlayabilir ve silebilirsiniz. Tek yapmanız gereken, kodunuzda apigee-access modülünü "require" etmektir. Ayrıntılar için Node.js'de akış değişkenlerine erişme başlıklı makaleyi inceleyin.

Unutulmaması gerekenler

Akış değişkenleri hakkında unutulmaması gereken birkaç önemli nokta:

  • Bazı "hazır" değişkenler, proxy'nin kendisi tarafından otomatik olarak oluşturulur ve doldurulur. Bunlar Akış değişkenleri referansında belgelenmiştir.
  • Proxy akışında kullanılabilecek özel değişkenler oluşturabilirsiniz. AssignMessage politikası ve JavaScript politikası gibi politikaları kullanarak ve Node.js kodunda değişken oluşturabilirsiniz.
  • Değişkenlerin kapsamı vardır. Örneğin, ilk proxy bir uygulamadan istek aldığında bazı değişkenler otomatik olarak doldurulur. Diğer değişkenler ise proxy'nin yanıt akışı segmentinde doldurulur. Bu yanıt değişkenleri, yanıt segmenti yürütülene kadar tanımlanmamış olarak kalır.
  • Politikalar yürütüldüğünde politikaya özel değişkenler oluşturup bunları doldurabilirler. Her politikanın dokümanında, ilgili politikaya özgü tüm değişkenler listelenir.
  • Koşullu akışlar genellikle bir veya daha fazla değişkeni değerlendirir. Koşullu akışlar oluşturmak istiyorsanız değişkenleri anlamanız gerekir.
  • Birçok politika, giriş veya çıkış olarak değişkenleri kullanır. Belki bir politika tarafından oluşturulan bir değişken daha sonra başka bir politika tarafından kullanılıyordur.
  • Düz JavaScript (ve JavaScript nesne modelimiz) ya da Edge'de kodu yürüten JavaCallout politikası kullanarak Node.js'den birçok akış değişkenini alıp ayarlayabilirsiniz.

İlgili kod örnekleri

API proxy örnekleri GitHub'da bulunur ve kolayca indirilip kullanılabilir. Örnekleri indirme ve kullanma hakkında bilgi edinmek için Örnek API proxy'lerini kullanma başlıklı makaleye bakın. API proxy'si örneklerinin açıklaması ve ne yaptıkları hakkında bilgi edinmek için Örnekler listesi'ne bakın.

Değişkenlerin ve değişken işlemenin kullanıldığı örnek proxy'ler şunlardır:

  • variables - Değişkenlerin, aktarım ve JSON ile XML mesajı içeriklerine göre nasıl ayıklanıp ayarlandığını gösterir.
  • policy-mashup-cookbook: İki herkese açık API'yi çağırmak, sonuçları birleştirmek ve istemci uygulaması için zenginleştirilmiş bir yanıt oluşturmak üzere politika bileşimini kullanan eksiksiz bir uygulama. Bu örnek hakkında daha fazla bilgi için Politika bileşimini kullanma başlıklı makaleyi inceleyin.
  • conditional-policy - Değişken değerlerine dayalı olarak basit koşullu politika zorunluluğunu uygular.

İlgili konular

  • Bir API proxy'sinde otomatik olarak doldurulan tüm değişkenler Akış değişkenleri referansı bölümünde listelenir. Referansta her değişkenin türü ve kapsamı da listelenir.
  • Belirli bir politikanın hangi değişkenleri doldurduğunu öğrenmek istiyorsanız ilgili politikanın referans konusuna bakın. Örneğin, Kota politikası referansındaki Akış değişkenleri bölümüne bakın.