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 veya yardımcı programlarınızdan (İzleme aracı aracı gibi) erişebileceğiniz nesnelerdir. Apigee Edge tarafından işlenen bir API işlemiyle ilişkili durumu korumanızı sağlar.

Video

Aşağıdaki video, akış değişkenlerine giriş niteliğindedir:

Akış değişkenleri nedir?

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

• İstekte bulunan uygulamadan gönderilen IP adresi, üst bilgiler, URL yolu ve yük
• Edge'in istek aldığı tarih ve saat gibi sistem bilgileri
• Bir politika yürütüldüğünde türetilen 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 alınan yanıtla ilgili bilgiler

Bazı değişkenler Edge'de "yerleşiktir" ve bir API isteği alındığında otomatik olarak doldurulur. Bir API işlemi boyunca kullanılabilirler. 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 nerede erişilebilecekleri, 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 yürütülen tüm politikalarda ve kodda kullanılabilir.

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

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

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

  Örneğin, bir VerifyJWT politikası doğrulanacak jetonu bir akış değişkeninden alıp doğrulamayı bu jeton üzerinde gerçekleştirebilir. Başka bir örnek olarak, JavaScript politikası akış değişkenlerini alıp bu değişkenlerde yer alan verileri kodlayabilir.

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

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

Bu bağlamların her birinde değişkenlerin nasıl kullanıldığına ilişkin örneklere göz atalı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 alarak My-Client-IP adlı bir istek başlığına yerleştirir. İstek akışına eklenirse bu politika, arka uç hedefine geçirilen bir üst bilgiyi 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 vermek gerekirse 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 (burada my-quota-policy, ilgilendiğiniz kota politikasının adıdır).

Daha sonra, "Geçerli kota sayısı maksimum değerin% 50'sinin altındaysa ve saat 09:00 ile 17:00 arasındaysa farklı bir kota uygula" şeklinde bir koşullu akış yürütebilirsiniz. Bu koşul, mevcut kota sayısının değerine ve yerleşik Edge değişkenlerinden biri olan system.time adlı akış değişkenine bağlı olabilir.

Koşullu akışlarda 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.

Bir proxy akış adımında request.verb değişkeninin değerini değerlendiren koşullu bir akışı burada bulabilirsiniz. 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>

Şimdi request.verb, client.ip ve system.time gibi değişkenlerin nereden geldiğini merak edebilirsiniz. Bunlar ne zaman örneklenir ve bir değerle doldurulur? Değişkenlerin ne zaman oluşturulduğunu ve ne zaman kullanılabilir olduğunu anlamanıza yardımcı olması için Akış değişkeni kapsamını anlama sayfasını inceleyin.

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

JavaScript politikası sayesinde JavaScript kodunu bir API proxy akışı bağlamında yürütebilirsiniz. Bu politika tarafından yürütülen JavaScript, Apigee JavaScript nesne modeli kullanır. Bu model, kodunuzun çalıştırıldığı API proxy akışıyla ilişkili istek, yanıt ve bağlam nesnelerine özel kod erişiminizi sağlar. Örneğin bu kod, target.name akış değişkeninden alınan 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'i kullanma tekniği, assignMessage politikası (önceden gösterildiği) ile yapabileceğiniz işleme benzer. Bu, Edge'de aynı tür şeyleri yapmanın bir başka yoludur. Unutulmaması gereken önemli nokta, JavaScript politikası tarafından yürütülen JavaScript'in, API proxy akışında bulunan ve kapsamda bulunan tüm akış değişkenlerine erişiminin olmasıdır.

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

apigee-access modülünü zorunlu kılarak Edge'e dağıtılan Node.js kodunun içinden akış değişkenlerine erişim sağlayabilir ve değişkenlere erişebilirsiniz.

custom.foo adlı bir değişkenin Bar değerine ayarlandığı basit bir örneği aşağıda görebilirsiniz. Bu yeni değişken, ayarlandığında Node.js kodu yürütüldükten sonra proxy akışında ortaya çıkan tüm politikalar veya diğer kodlar tarafından kullanılabilir hale gelir.

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 bölümünde 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 API proxy'si üzerinden akış şeklini anlamak veya görselleştirmek önemlidir. API proxy'si, akış şeklinde düzenlenmiş bir dizi mesaj işleme adımından oluşur. Proxy akışının her adımında, proxy mevcut bilgileri değerlendirir ve daha sonra ne yapılması gerektiğine karar verir. Proxy, bu süreçte politika kodu yürütebilir veya koşullu kollara ayırma işlemi gerçekleştirebilir.

Aşağıdaki şekilde, bu akış dizisi gösterilmektedir. Akışların şu dört ana segmentten nasıl oluştuğuna dikkat edin: ProxyEndpoint isteği, TargetEndpoint isteği, TargetEndpoint yanıtı ve ProxyEndpoint yanıtı.

Konunun geri kalanındaki 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 akışını görselleştirebildiğiniz anda değişken kapsamı anlamaya başlayabilirsiniz. Kapsam, proxy akışı yaşam döngüsünde bir değişkenin ilk kez örneklendiği noktayı ifade eder.

Ö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ülmemesi ve bu nedenle API proxy'sinin bu kapsamdaki değişkenleri doldurma fırsatı olmamasıdır.

Aşağıdaki tabloda, değişken kapsamlarının tamamı listelenmekte ve bunların proxy akışında ne zaman kullanılabilir olacağı 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 erişilebilir	Proxy bir istek alır almaz. Bu değişkenler, proxy akışı yaşam döngüsünün tamamında kullanılabilir.

Örneğin, client.ip adlı yerleşik bir Edge değişkeni var. Bu değişkenin "proxy request" (proxy isteği) kapsamı var. Bu alan, proxy adı verilen istemcinin IP adresiyle otomatik olarak doldurulur. Bu alan, bir istek ilk olarak ProxyEndpoint'e ulaştığında doldurulur ve proxy akışı yaşam döngüsünün tamamında kullanılabilir durumda kalır.

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

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 (üstbilgiler, parametreler, gövde) kopyalamak ve bunu çağrı 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 aşağıdaki gibi görünür:

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

Bu politika yalnızca request nesnesini kopyalar ve response nesnesine atar. Peki bu politika, proxy akışında nereye yerleştirilmelidir? Yanıt değişkeninin kapsamı "hedef yanıt" olduğundan, yanıt değişkeninin 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 olan bir adlandırma kuralına sahiptir. Bu kural, değişkenin amacını belirlemeyi kolaylaştırır. Örneğin, system.time.hour ve request.content.

Apigee, alakalı değişkenleri uygun şekilde düzenlemek için çeşitli ön ekler kullanır. Bu ön ekler ş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 AssignmentMessage politikası, client.ip değişkeninin değerini alır ve bunu 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 kodundaki akış değişkenlerine de başvurabilirsiniz. Daha fazla bilgi için aşağıdaki sayfaları inceleyin:

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

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

Bir akış değişkeninin her özelliği, Dize, Uzun, Tamsayı, Boole veya Koleksiyon gibi iyi tanımlanmış bir veri türüne sahiptir. Veri türlerini Akış değişkenleri referansında bulabilirsiniz. Bir politika tarafından oluşturulan değişkenlerle ilgili olarak veri türü bilgileri için ilgili politika referans konusuna bakın.

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

Politikalarda akış değişkenlerini kullanma

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

Proxy'ler ve politikalarla çalışırken, hangi değişkenlerin oluşturulduğunu ve ne için kullanıldığını öğrenmek için mutlaka politika referansına başvurun. Örneğin Kota politikası; kota sayıları ve sınırları, süre sonu vb. bilgiler içeren bir dizi değişken 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.

Değişkenleri Ayıklama politikası, özel değişkenleri mesajlardan çıkarılan verilerle doldurmanıza olanak tanır. Sorgu parametrelerini, başlıkları ve diğer verileri ayıklayabilirsiniz. Örneğin, mesajlardan belirli verileri çıkarmak için kalıpları kullanarak istek ve yanıt mesajlarını 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, iki özel değişken (geocoderesponse.latitude ve geocoderesponse.longitude) oluşturup 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>

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. Söz konusu değişkenler, her bir politika konusu altındaki Politika referansında açıklanmıştır.

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

Değişkenlere doğrudan bir API proxy'si bağlamında çalışan JavaScript kodunda erişip ayarlayabilirsiniz. Apigee JavaScript nesne modeli sayesinde, Edge'de JavaScript çalıştırmak proxy akışı değişkenlerine doğrudan erişebilir.

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

• context
• proxyRequest
• proxyResponse
• targetRequest
• targetResponse

Gördüğünüz gibi bu nesne referansları, daha önce API proxy'sinin akışını görselleştirme bölümünde 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ı almak için context nesnesinde getVariable() çağırabilirsiniz:

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

Benzer şekilde, özelleştirilebilen bir değişkenin veya herhangi bir yazılabilir değişkenin değerini ayarlamak için setVariable() yöntemini çağırabilirsiniz. Şimdi, organization.name.myorg adında 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ğundan tüm akış segmentleri için kullanılabilir olacaktır (aslında bu, genel değişken oluşturmak gibidir).

JavaCall politikası ile 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 kodundaki akış değişkenlerini alabilir, ayarlayabilir ve silebilirsiniz. Tek yapmanız gereken, kodunuzdaki Apigee-access modülünü "zorunlu kılmak"tır. Ayrıntılar için Node.js'de akış değişkenlerine erişme bölümüne bakın.

Unutmamanız gerekenler

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

• Bazı "kullanıma hazır" değişkenler, proxy'nin kendisi tarafından otomatik olarak örneklenir ve doldurulur. Bunlar, Akış değişkenleri referansında açıklanmıştır.
• Proxy akışında kullanmak üzere özelleştirilebilen değişkenler oluşturabilirsiniz. assignMessage politikası ve JavaScript politikası gibi politikaları kullanarak ve Node.js kodunda değişkenler 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ımsız kalır.
• Politikalar yürütüldüğünde politikaya özel değişkenler oluşturup bunları doldurabilirler. Her politikaya ilişkin dokümanlarda, söz konusu politikaya özel bu değişkenlerin tümü listelenmektedir.
• 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 girdi veya çıkış olarak değişkenleri kullanır. Bir politika tarafından oluşturulan bir değişken daha sonra başka bir politika tarafından kullanılıyor olabilir.
• Düz JavaScript'i (ve JavaScript nesne modelimizi) veya Edge'de kod yürüten JavaCall politikasını kullanarak Node.js'nin içinden birçok akış değişkenini alabilir ve ayarlayabilirsiniz.

İlgili kod örnekleri

API proxy örnekleri, GitHub'da yer almaktadır. Bu örnekleri kolayca indirip kullanabilirsiniz. Örnekleri indirme ve kullanma hakkında bilgi edinmek için Örnek API proxy'lerini kullanma bölümüne bakın. API proxy örneklerinin açıklaması ve bunların ne işe yaradığıyla ilgili bilgi edinmek için Örnekler listesi bölümüne bakın.

Değişkenler ve değişken işleme kullanımını içeren örnek proxy'ler arasında şunlar bulunur:

• değişkenler: Aktarıma, JSON ve XML mesaj içeriğine göre değişkenlerin nasıl ayıklanacağını ve ayarlanacağını gösterir.
• policy-mashup- Cookbook - İki herkese açık API'yi çağırmak için politika bileşimini kullanan, sonuçları birleştiren ve istemci uygulaması için zengin bir yanıt oluşturan eksiksiz bir uygulama. Bu örnekle ilgili daha fazla bilgi için Politika bileşimini kullanma bölümüne bakın.
• koşullu politika: Değişken değerleri temel alan basit koşullu politika yaptırımı uygular.

İlgili konular

• API proxy'sinde otomatik olarak doldurulan tüm değişkenler Akış değişkenleri referansında listelenmiştir. 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.