Akış değişkenlerini kullanma

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

Kavramsal olarak akış değişkenleri, politikalarınızın veya yardımcı programlarınızın (İzleme aracı aracı gibi) içinden erişebileceğiniz nesnelerdir. Bu alanlar, Apigee Edge tarafından işlenen bir API işlemiyle ilişkilendirilen durumu korumanıza olanak tanır.

Video

Aşağıdaki videoda akış değişkenleri hakkında bilgi verilmektedir:

Akış değişkenleri nedir?

Akış değişkenleri, API proxy akışı bağlamında bulunur ve adlandırılmış değişkenlerin bir yazılım programındaki durumu izlemesi gibi API işlemlerindeki durumu izler. Akış değişkenleri aşağıdaki gibi bilgileri depolar:

• İstekte bulunan uygulamadan gönderilen IP adresi, üstbilgiler, URL yolu ve yük
• Edge'in istek aldığı tarih ve saat gibi sistem bilgileri
• Bir politika yürütüldüğünde elde edilen veriler. Örneğin, 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ıt hakkında bilgi

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

Göreceğiniz gibi, değişkenlerin kapsamı vardır ve bunlara erişilebilen yerler kısmen API proxy akışında ne zaman oluşturulduklarına bağlıdır. Genel olarak, bir değişken oluşturulduğunda API işlem akışında daha sonra çalıştırılan tüm politikalar ve kodlar tarafından 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 durum bilgisi alabilir ve işlerini yapmak için bu bilgileri kullanabilir.

  Örneğin, bir VerifyJWT politikası, doğrulanacak jetonu bir akış değişkeninden alıp doğrulamayı gerçekleştirebilir. Bir başka örnek olarak, JavaScript politikası akış değişkenlerini alıp bu değişkenlerde bulunan verileri kodlayabilir.

• Koşullu akışlar, Edge üzerinden bir API akışının yönünü belirlemek için akış değişkenlerine referans verebilir. Bu, programlamada bir switch ifadesinin işleyiş şekline benzer.

  Örneğin, hata döndürecek bir politika yalnızca belirli bir akış değişkeni ayarlandığında yürütülebilir. Son olarak, Node.js hedef uygulamasında akış değişkenlerini alıp ayarlayabilirsiniz.

Şimdi, bu bağlamlarda değişkenlerin nasıl kullanıldığına dair örneklere bakalım.

Politikalardaki akış değişkenleri

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

Örneğin, aşağıdaki AssignmentMessage politikası client.ip akış değişkeninin değerini alır ve bunu My-Client-IP adlı bir istek başlığına yerleştirir. İstek akışına eklenirse bu politika, 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>

Başka bir örnek olarak, bir kota politikası yürütüldüğünde çeşitli akış değişkenleri politikayla ilgili değerlerle doldurulur. Bu değişkenlerden biri ratelimit.my-quota-policy.used.count olarak adlandırılır (my-quota-policy, ilgilendiğiniz kota politikasının adıdır).

Daha sonra, "mevcut kota sayısı maksimum değerin% 50'sinden azsa ve saat 9:00 ile 17:00 arasındaysa farklı bir kota uygula" yazan koşullu bir akış ç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 yönlendirme kurallarının davranışını değiştirmek için kullanılır.

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

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

request.verb, client.ip ve system.time gibi değişkenlerin kaynağını merak ediyor olabilirsiniz. Ne zaman örneklendirilir ve bir değerle doldurulur? Değişkenlerin ne zaman oluşturulduğunu ve ne zaman kullanılabileceğ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ışı bağlamında yürütebilirsiniz. Bu politika tarafından yürütülen JavaScript, Apigee JavaScript nesne modelini kullanır. Bu model, özel kodunuza kodunuzun yürütüldüğü API proxy akışıyla ilişkili istek, yanıt ve bağlam nesnelerine erişim sağlar. Örneğin, bu kod, akış değişkeni target.name'den elde edilen değerle bir yanıt üstbilgisi ayarlar.

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

Değişkenleri okumak ve ayarlamak için JavaScript'i kullanma tekniği, AssignMessage politikasıyla (daha önce gösterilmiştir) yapabileceğiniz işlemlere benzer. Bu, Edge'de aynı tür işlemleri yapmanın başka bir yoludur. Unutmayın, JavaScript politikası tarafından yürütülen JavaScript, API proxy akışında mevcut olan ve kapsamda bulunan tüm akış değişkenlerine erişebilir.

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

apigee-access modülünü zorunlu kılarak Edge'e dağıtılan Node.js kodundan 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. Ayarlandıktan sonra bu yeni değişken, Node.js kodu çalıştırıldıktan sonra proxy akışında gerçekleşen tüm politikalar veya diğer kodlar tarafından 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/');

Değişkenlerle çalışmak için apigee-access kullanma 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

Değişken kapsamı, bir API proxy ç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'sinde nasıl aktığını anlamak veya görselleştirmek önemlidir. API proxy'si, akış olarak düzenlenen bir dizi mesaj işleme adımından oluşur. Proxy, proxy akışındaki her adımda kendisine sunulan bilgileri değerlendirir ve sırada ne yapılacağına karar verir. Bu süreçte proxy, politika kodunu yürütebilir veya koşullu dallanma gerçekleştirebilir.

Aşağıdaki şekilde bu akış dizisi 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 keşfetmeye başlarken bu akış yapısını göz önünde bulundurun.

Değişken kapsamının proxy akışıyla ilişkisi

Daha önce açıklandığı gibi, mesajların bir proxy üzerinden nasıl aktığını görselleştirebildiğinizde değişken kapsamını anlamaya başlayabilirsiniz. Kapsam, proxy akışı yaşam döngüsünde bir değişkenin ilk kez oluşturulduğu noktadır.

Örneğin, ProxyEndpoint istek segmentine eklenmiş bir politikanız varsa bu politika, TargetEndpoint istek segmentinin kapsamına giren hiçbir değişkene 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 tamamı listelenmekte ve bunların proxy akışında ne zaman kullanılabilir oldukları belirtilmektedir.

Değişken kapsamı	Bu değişkenlerin doldurulduğu yerler
proxy isteği	ProxyEndpoint istek segmenti
hedef istek	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, proxy akışı yaşam döngüsünün tamamı boyunca kullanılabilir.

Örneğin, client.ip adlı yerleşik bir Edge değişkeni vardır. Bu değişkenin "proxy isteği" kapsamı vardır. Proxy olarak adlandırılan istemcinin IP adresiyle otomatik olarak doldurulur. Bir istek ProxyEndpoint'e ilk kez çarptığında doldurulur ve proxy akışı yaşam döngüsünün tamamı boyunca kullanılabilir durumda kalır.

target.url adlı başka bir yerleşik değişken de vardır. Bu değişkenin kapsamı "hedef istek"tir. TargetEndpoint istek segmentinde, arka uç hedefine gönderilen istek URL'si ile doldurulur. ProxyEndpoint istek segmentinde target.url öğesine erişmeye çalışırsanız NULL değer alırsınız. Bu değişkeni kapsama girmeden önce ayarlamaya çalışırsanız proxy hiçbir işlem yapmaz, hata oluşturmaz ve değişkeni aylamaz.

Aşağıda, değişken kapsamı hakkında nasıl düşünüleceğini gösteren basit bir örnek verilmiştir. Bir istek nesnesinin tüm içeriğini (başlıklar, parametreler, gövde) kopyalamak ve bunu çağrı uygulamasına geri gönderilecek yanıt yüküne atamak istediğinizi varsayalım. Bu görev için AssignmentMessage 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 kopyalar ve response nesnesine atar. Ancak bu politika, proxy akışına nereye yerleştirilmelidir? Yanıt, yanıt değişkeninin kapsamı "hedef yanıt" olduğu için TargetEndpoint yanıtına yerleştirilmesi gerektiğidir.

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 ön ekleri ayırır. Bu önekler şunları içerir:

• request
• response
• system
• target

Bir politikadaki değişkene referans vermek için değişkeni süslü ayraç 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, parantezler 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>

JavaScript ve Java kodunda da akış değişkenlerine referans verebilirsiniz. Daha fazla bilgi için aşağıdaki sayfaları inceleyin:

• JavaScript'te değişkenlerle çalışma
• Node.js'de akış değişkenlerine erişme
• JavaScript politikası

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

Bir akış değişkeninin her özelliğinin iyi tanımlanmış bir veri türü (ör. dize, uzun, tam sayı, boole veya koleksiyon) vardır. Listelenen 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 belirli politika referans konusuna bakın.

Manuel olarak oluşturduğunuz değişkenler, oluşturuldukları sırada belirtilen türü alır ve izin verilen değer türlerine bağlıdır. Örneğin, Node.js kodunda oluşturulan değişkenler Sayı, Dize, Boole, Boş veya Tanımlanmamış ile sınırlıdır.

Politikalarda akış değişkenleri kullanma

Birçok politika, normal yürütmelerinin bir parçası olarak akış değişkenleri oluşturur. Politika referansı, politikaya özel bu değişkenlerin tümünü belgeler.

Proxy'lerle ve politikalarla çalışırken hangi değişkenlerin oluşturulduğunu ve ne için kullanıldığını öğrenmek üzere politika referansına göz atın. Örneğin, Kota politikası kota sayıları ve sınırları, geçerlilik bitiş zamanı gibi bilgileri 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ışındaki belirli bir durumda hangi değişkenlerin ayarlandığını görmek için İzleme aracı'nı kullanabilirsiniz.

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

Aşağıdaki örnekte, Değişkenleri Ayıkla işlevi 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 özelleştirilebilen değişken oluşturur ve bunlara değer 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>

Yine de 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 konusunun altındaki Politika referansında açıklanmıştır.

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

Doğrudan API proxy bağlamında yürütülen JavaScript kodunda değişkenlere erişebilir ve değişkenleri ayarlayabilirsiniz. Edge'de çalışan 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 şu nesnelerin herhangi birinde alıcı/ayarlayıcı 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ış modelinin bilinen segmentleriyle 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ı öğrenmek için context nesnesinde getVariable() yöntemini çağırabilirsiniz:

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

Benzer şekilde, özelleştirilebilen bir değişkenin değerini veya hazır yazılabilir değişkenleri 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 nesnesi ile oluşturulduğundan tüm akış segmentleri tarafından kullanılabilir (aslında bu, genel bir değişken oluşturmaya benzer).

JavaCallout politikasıyla yürüttüğünüz Java kodunda proxy akış değişkenlerini de 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ü "zorunlu kılmak"tır. Ayrıntılar için Node.js'de akış değişkenlerine erişme başlıklı makaleyi inceleyin.

Hatırlamanız gerekenler

Akış değişkenleri hakkında akılda bulundurulması gereken bazı önemli noktalar şunlardır:

• Bazı "kullanıma hazır" değişkenler proxy'nin kendisi tarafından otomatik olarak oluşturulur ve doldurulur. Bunlar, Akış değişkenleri referansı bölümünde açıklanmıştır.
• Proxy akışında kullanılabilen ö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, proxy'nin yanıt akışı segmentinde doldurulur. Bu yanıt değişkenleri, yanıt segmenti yürütülene kadar tanımlanmaz.
• Politikalar yürütüldüğünde politikaya özgü değişkenler oluşturabilir ve doldurabilir. Her politikanın dokümanında, politikaya özgü bu değişkenlerin tümü 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şkenler kullanır. Bir politika tarafından oluşturulan bir değişken daha sonra başka bir politika tarafından kullanılıyor olabilir.
• Doğrudan JavaScript'i (ve JavaScript nesne modelimizi) veya Edge'de kod yürüten JavaCallout politikasını kullanarak Node.js'den birçok akış değişkeni alabilir ve ayarlayabilirsiniz.

İlgili kod örnekleri

GitHub'da bulunan API proxy örneklerini indirip kolayca kullanabilirsiniz. Örnekleri indirme ve kullanma hakkında bilgi edinmek için Örnek API proxy'lerini kullanma başlıklı makaleye bakın. API proxy örneklerinin ve işlevlerinin açıklaması 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, JSON ve XML mesaj içeriğine göre nasıl ayıklanıp ayarlanacağı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 amacıyla politika derlemeyi kullanan eksiksiz bir uygulama. Bu örnek hakkında daha fazla bilgi için Politika derlemeyi kullanma başlıklı makaleyi inceleyin.
• conditional-policy: Değişken değerlere dayalı basit koşullu politika yaptırımı uygular.

İlgili konular

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