Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi
Ne
Bu politika, API proxy akışı bağlamında çalışan özel JavaScript kodu eklemenize olanak tanır. Özel JavaScript kodunuzda Apigee Edge JavaScript nesne modelinin nesnelerini, yöntemlerini ve özelliklerini kullanabilirsiniz. Nesne modeli, proxy akışı bağlamında değişkenleri almanızı, ayarlamanızı ve kaldırmanızı sağlar. Nesne modeliyle sağlanan temel şifreleme işlevlerini de kullanabilirsiniz.
Hakkında
JavaScript politikasının birçok kullanım alanı vardır. Örneğin, akış değişkenlerini alıp ayarlayabilir, özel mantık yürütebilir, hata işleme, istek veya yanıtlardan veri çıkarabilir, arka uç hedef URL'sini dinamik olarak düzenleyebilir ve daha pek çok işlem yapabilirsiniz. Bu politika, diğer standart Edge politikalarının kapsamına girmeyen özel davranışlar uygulamanıza olanak tanır. Aslında,assignMessage ve ExtractVariable gibi diğer politikaların uyguladığı davranışların birçoğunu gerçekleştirmek için bir JavaScript politikası kullanabilirsiniz.
JavaScript politikası için önermediğimiz bir kullanım alanı günlük kaydıdır. Message Logging politikası; Splunk, Sumo ve Loggly gibi üçüncü taraf günlük kaydı platformlarının günlük kaydı için çok daha uygundur. Ayrıca, yanıt istemciye geri gönderildikten sonra yürütülen PostClientFlow'da Message Logging politikasını yürüterek API proxy'si performansını iyileştirirsiniz.
JavaScript politikası, yürütülecek bir JavaScript kaynak dosyası belirtmenize olanak tanır veya JavaScript kodunu <Source>
öğesiyle doğrudan politikanın yapılandırmasına ekleyebilirsiniz.
Her iki durumda da politikanın eklendiği adım yürütüldüğünde JavaScript kodu yürütülür.
Kaynak dosya seçeneğinde kaynak kodu, her zaman proxy paketi içindeki standart bir konumda depolanır: apiproxy/resources/jsc
. Alternatif olarak, kaynak kodunu ortam veya kuruluş düzeyinde bir kaynak dosyasında depolayabilirsiniz. Talimatlar için Kaynak dosyaları başlıklı makaleyi inceleyin. JavaScript'inizi Apigee kullanıcı arayüzü proxy düzenleyicisi aracılığıyla da yükleyebilirsiniz.
JavaScript kaynak dosyalarının her zaman bir .js
uzantısı olmalıdır.
Şu anda desteklenen JavaScript sürümü için Desteklenen yazılımlar ve desteklenen sürümler bölümüne bakın.
Video
JavaScript politikasını kullanarak özel politika uzantılarının nasıl oluşturulacağını öğrenmek için kısa bir video izleyin.
Sana Özel
Hedef URL'yi yeniden yazma
Yaygın bir kullanım alanı şu şekildedir: Bir istek gövdesinden veri ayıklama, bir akış değişkeninde depolama ve bu akış değişkenini proxy akışında başka bir yerde kullanma. Kullanıcının adını bir HTML formuna girip gönderdiği bir uygulamanız olduğunu varsayalım. API proxy'sinin form verilerini çıkarmasını ve bu verileri arka uç hizmetini çağırmak için kullanılan URL'ye dinamik olarak eklemesini istersiniz. Bir JavsScript politikasında bunu nasıl yapabilirsiniz?
Not: Bu örneği denemek isterseniz proxy düzenleyicide yeni bir proxy oluşturduğunuzu varsayıyoruz. Projeyi oluştururken arka uç hizmeti URL'sini şu şekilde vermeniz yeterlidir: http://www.example.com. Bu örnekte, arka uç URL'sini dinamik bir şekilde yeniden yazacağız. Yeni bir proxy'yi nasıl oluşturacağınızı bilmiyorsanız başlangıç eğiticisine bakın. .
- Edge kullanıcı arayüzünde, proxy düzenleyicide oluşturduğunuz proxy'yi açın.
- Geliştirme sekmesini seçin.
- Yeni menüsünden Yeni Komut Dosyası'nı seçin.
- İletişim kutusunda JavaScript'i seçin ve komut dosyasına
js-example
gibi bir ad verin. - Aşağıdaki kodu kod düzenleyiciye yapıştırın ve proxy'yi kaydedin. Dikkat edilmesi gereken önemli nokta
context
nesnesidir. Bu nesne, proxy akışının herhangi bir yerinde JavaScript kodu tarafından kullanılabilir. Akışa özgü sabit değerler elde etmek, faydalı "al/set" yöntemleri çağırmak ve daha fazla işlem için kullanılır. Bu nesne bölümü, Edge'in JavaScript nesne modeline aittir.target.url
akış değişkeninin, Hedef İstek akışında erişilebilen yerleşik bir okuma/yazma değişkeni olduğunu da unutmayın. Bu değişkeni API URL'si ile ayarladığımızda Edge, arka uç çağrısını bu URL'ye yapar. Aslında, proxy'yi oluştururken belirttiğiniz orijinal hedef URL'yi yeniden yazdık (ör. http://www.example.com).
if (context.flow=="PROXY_REQ_FLOW") { var username = context.getVariable("request.formparam.user"); context.setVariable("info.username", username); } if (context.flow=="TARGET_REQ_FLOW") { context.setVariable("request.verb", "GET"); var name = context.getVariable("info.username"); var url = "http://mocktarget.apigee.net/" context.setVariable("target.url", url + "?user=" + name); }
- Yeni Politika menüsünde JavaScript'i seçin.
- Politikaya
target-rewrite
gibi bir ad verin. Varsayılanları kabul edin ve politikayı kaydedin. - Gezinme'de Proxy Uç Nokta Ön Akışı'nı seçerseniz politikanın bu akışa eklendiğini görürsünüz.
- Gezgin'de Hedef Uç Nokta Ön Akış simgesini seçin.
- Gezgin'den JavaScript politikasını akış düzenleyicide Hedef Uç Nokta'nın İstek tarafına sürükleyin.
- Kaydet'e dokunun.
- API'yi şu şekilde çağırarak doğru kuruluş adınızı ve proxy adınızı uygun şekilde değiştirin:
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example
Son olarak, bu örnekte kullanılan JavaScript politikasının XML tanımına göz atalım. Dikkat edilmesi gereken önemli nokta, yürütülecek JavaScript kaynak dosyasını belirtmek için <ResourceURL>
öğesinin kullanılmasıdır. Aynı kalıp tüm JavaScript kaynak dosyaları için kullanılır: jsc://filename.js
. JavaScript kodunuzda "ekleme" özelliği gerekliyse bunu yapmak için bu referansın ilerleyen bölümlerinde açıklandığı gibi bir veya daha fazla <IncludeURL>
öğesi kullanabilirsiniz.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite"> <DisplayName>target-rewrite</DisplayName> <Properties/> <ResourceURL>jsc://js-example.js</ResourceURL> </Javascript>
JavaScript'ten özellik değeri al
Yapılandırmaya bir <Property>
öğesi ekleyebilir, ardından çalışma zamanında JavaScript ile öğenin değerini alabilirsiniz.
JavaScript kodundan mülke erişilecek adı belirtmek için öğenin name
özelliğini kullanın. <Property>
öğesinin değeri (açılış ve kapanış etiketleri arasındaki değer), JavaScript tarafından alınacak değişmez değerdir.
JavaScript'te politika özelliği değerini, aşağıda gösterildiği gibi Properties
nesnesinin bir özelliği olarak erişerek alırsınız:
- Mülkü yapılandırın. Burada, özellik değeri
response.status.code
değişken adıdır.<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavascriptURLRewrite"> <DisplayName>JavascriptURLRewrite</DisplayName> <Properties> <Property name="source">response.status.code</Property> </Properties> <ResourceURL>jsc://JavascriptURLRewrite.js</ResourceURL> </Javascript>
- Özelliği JavaScript ile alın. Burada, alınan değer (değişken adı) daha sonra
getVariable
işlevi tarafından değişkenin değerini almak için kullanılır.var responseCode = properties.source; // Returns "response.status.code" var value = context.getVariable(responseCode); // Get the value of response.status.code context.setVariable("response.header.x-target-response-code", value);
Hataları işleme
JavaScript açıklama metninde kullanabileceğiniz hata işleme teknikleriyle ilgili örnekler ve tartışma için Apigee Topluluğu'ndaki bu yayına göz atın. Apigee Topluluğu'nda sunulan öneriler yalnızca bilgi amaçlıdır ve her zaman Apigee'nin önerdiği en iyi uygulamaları yansıtmayabilir.
Öğe referansı
Öğe referansı, JavaScript politikasının öğelerini ve özelliklerini açıklar.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavaScript-1"> <DisplayName>JavaScript 1</DisplayName> <Properties> <Property name="propName">propertyValue</Property> </Properties> <SSLInfo> <Enabled>trueFalse</Enabled> <ClientAuthEnabled>trueFalse</ClientAuthEnabled> <KeyStore>ref://keystoreRef</KeyStore> <KeyAlias>keyAlias</KeyAlias> <TrustStore>ref://truststoreRef</TrustStore> </SSLInfo> <IncludeURL>jsc://a-javascript-library-file</IncludeURL> <ResourceURL>jsc://my-javascript-source-file</ResourceURL> <Source>insert_js_code_here</Source> </Javascript>
<Javascript> Özellikleri
<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">
Aşağıdaki özellikler bu politikaya özeldir.
Özellik | Açıklama | Varsayılan | Varlık |
---|---|---|---|
timeLimit |
Komut dosyasının çalışmasına izin verilen maksimum süreyi (milisaniye cinsinden) belirtir. Örneğin, 200 ms'lik bir sınır aşılırsa politika şu hatayı verir:
Not: Ücretsiz deneme hesapları için yürütme süresi 200 ms ile sınırlıdır. |
Yok | Gerekli |
Aşağıdaki tabloda, tüm politika üst öğelerinde ortak olan özellikler açıklanmaktadır:
Özellik | Açıklama | Varsayılan | Varlık |
---|---|---|---|
name |
Politikanın dahili adı. İsteğe bağlı olarak, politikayı yönetim kullanıcı arayüzü proxy düzenleyicisinde farklı bir doğal dil adıyla etiketlemek için |
Yok | Gerekli |
continueOnError |
Bir politika başarısız olduğunda hata döndürülmesi için Bir politika başarısız olduktan sonra bile akış yürütülmesinin devam etmesi için |
false | İsteğe bağlı |
enabled |
Politikayı uygulamak için Politikayı devre dışı bırakmak için |
true | İsteğe bağlı |
async |
Bu özellik kullanımdan kaldırıldı. |
false | Kullanımdan kaldırıldı |
<DisplayName> öğesi
Politikayı, yönetim kullanıcı arayüzü proxy düzenleyicisinde farklı bir doğal dil adıyla etiketlemek için name
özelliğine ek olarak kullanın.
<DisplayName>Policy Display Name</DisplayName>
Varsayılan |
Yok Bu öğeyi çıkarırsanız politikanın |
---|---|
Varlık | İsteğe bağlı |
Tür | Dize |
<IncludeURL> öğesi
<ResourceURL>
veya <Source>
öğesiyle belirtilen ana JavaScript dosyasına bağımlılık olarak yüklenecek bir JavaScript kitaplık dosyası belirtir. Komut dosyaları, politikada listelendikleri sırayla değerlendirilir. Kodunuz, JavaScript nesne modelinin nesnelerini, yöntemlerini ve özelliklerini kullanabilir.
Ek <IncludeURL>
öğeleriyle birden fazla JavaScript bağımlılık kaynağı ekleyin.
<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>
Varsayılan: | Yok |
Bulunma: | İsteğe bağlı |
Tür: | Dize |
Örnek
Örnekler bölümündeki Temel Örnek'e bakın.
<Mülk> öğesi
Çalışma zamanında JavaScript kodundan erişebileceğiniz bir özelliği belirtir.
<Properties> <Property name="propName">propertyValue</Property> </Properties>
Varsayılan: | Yok |
Bulunma: | İsteğe bağlı |
Tür: | Dize |
Özellikler
Özellik | Açıklama | Varsayılan | Varlık |
---|---|---|---|
ad |
Özelliğin adını belirtir. |
Yok | Zorunlu. |
Örnek
Sana Özel bölümündeki örneğe bakın.
<ResourceURL> öğesi
API akışında yürütülecek ana JavaScript dosyasını belirtir. Bu dosyayı, Kaynak dosyaları bölümünde açıklandığı gibi API proxy kapsamında (API proxy paketindeki /apiproxy/resources/jsc
altında veya API proxy düzenleyicisinin Gezgini bölmesindeki Komut Dosyaları bölümünde) ya da birden çok API proxy'si arasında yeniden kullanım için kuruluş veya ortam kapsamlarında saklayabilirsiniz. Kodunuz, JavaScript nesne modelinin nesnelerini, yöntemlerini ve özelliklerini kullanabilir.
<ResourceURL>jsc://my-javascript.js</ResourceURL>
Varsayılan: | Yok |
Bulunma: | <ResourceURL> veya <Source> gereklidir. <ResourceURL> ve <Source> mevcutsa <ResourceURL> yoksayılır. |
Tür: | Dize |
Örnek
Örnekler bölümündeki Temel Örnek'e bakın.
<Source> öğesi
JavaScript'i doğrudan politikanın XML yapılandırmasına eklemenize olanak tanır. Eklenen JavaScript kodu, politika API akışında yürütüldüğünde yürütülür.
Varsayılan: | Yok |
Bulunma: | <ResourceURL> veya <Source> gereklidir. <ResourceURL> ve <Source> mevcutsa <ResourceURL> yoksayılır. |
Tür: | Dize |
Örnek
<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' > <Properties> <Property name='inboundHeaderName'>specialheader</Property> <Property name='outboundVariableName'>json_stringified</Property> </Properties> <Source> var varname = 'request.header.' + properties.inboundHeaderName + '.values.string'; var h = context.getVariable(varname); if (h) { h = JSON.parse(h); h.augmented = (new Date()).valueOf(); var v = JSON.stringify(h, null, 2) + '\n'; // further indent var r = new RegExp('^(\S*)','mg'); v= v.replace(r,' $1'); context.setVariable(properties.outboundVariableName, v); } </Source> </Javascript>
<SSLInfo> öğesi
JavaScript politikası tarafından oluşturulan tüm HTTP istemci örnekleri için TLS'yi yapılandırmak üzere kullanılan özellikleri belirtir.
<SSLInfo> <Enabled>trueFalse</Enabled> <ClientAuthEnabled>trueFalse</ClientAuthEnabled> <KeyStore>ref://keystoreRef</KeyStore> <KeyAlias>keyAlias</KeyAlias> <TrustStore>ref://truststoreRef</TrustStore> </SSLInfo>
Varsayılan: | Yok |
Bulunma: | İsteğe bağlı |
Tür: | Dize |
Bir HTTP istemcisi için TLS'yi yapılandırma işlemi, bir TargetEndpoint/TargetServer için TLS'yi yapılandırmak üzere kullandığınız süreçle aynıdır. Daha fazla bilgi için Edge'den arka uca TLS'yi yapılandırma bölümüne bakın.
Kullanım notları
JavaScript politikaları gerçek kod içermez. Bunun yerine, JavaScript politikası bir JavaScript "kaynağına" referans verir ve API akışında JavaScript'in yürütüldüğü Adımı tanımlar. Komut dosyanızı Yönetim Kullanıcı Arayüzü proxy düzenleyicisi aracılığıyla yükleyebilir veya yerel olarak geliştirdiğiniz API proxy'lerindeki /resources/jsc
dizinine ekleyebilirsiniz.
JavaScript politika kodunda hata ayıklama
print() işlevini kullanarak İzleme Aracı'ndaki işlem çıkış paneline hata ayıklama bilgileri çıktısı alabilirsiniz. Ayrıntılar ve örnekler için JavaScript print() ifadeleriyle hata ayıklama bölümüne göz atın.
Yazdırma ifadelerini Trace'te görüntülemek için:
- İzleme Aracı'nı açın ve JavaScript politikanızı içeren bir proxy için izleme oturumu başlatın.
- Proxy'yi çağırın.
- İzleme Aracı'nda, çıkış panelini açmak için Tüm İşlemlerden çıkış'ı tıklayın.
- Basılı özetleriniz bu panelde görünür.
İzleme aracına hata ayıklama bilgilerinin çıktısını vermek içinprint() işlevini kullanabilirsiniz. Bu işleve doğrudan JavaScript nesne modeli üzerinden erişilebilir. Ayrıntılar için "print() ifadeleriyle JavaScript hatalarını ayıklama" bölümüne göz atın.
Akış Değişkenleri
Bu politika varsayılan olarak değişkenleri doldurmaz ancak bağlam nesnesinde yöntemler çağırarak JavaScript kodunuzda akış değişkenlerini ayarlayabilir (ve alabilirsiniz). Tipik bir kalıp şöyle görünür:
context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))
Bağlam nesnesi, Apigee Edge JavaScript nesne modelinin bir parçasıdır.
Hata referansı
Bu bölümde, bu politika bir hatayı tetiklediğinde Edge tarafından ayarlanan hata kodları ve hata mesajları ile döndürülen hata değişkenleri açıklanmaktadır. Hataları ele almak için hata kuralları geliştiriyorsanız bu bilgiye sahip olmanız önemlidir. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler ve Hataları işleme bölümlerine bakın.
Çalışma zamanı hataları
Politika yürütüldüğünde bu hatalar ortaya çıkabilir.
Hata kodu | HTTP durumu | Neden | Düzelt |
---|---|---|---|
steps.javascript.ScriptExecutionFailed |
500 | JavaScript politikası, birçok farklı türde ScriptExecutionFailed hatası verebilir. Yaygın olarak görülen hata türleri arasında RangeError, ReferenceError, SyntaxError, TypeError ve URIError bulunur. | build |
steps.javascript.ScriptExecutionFailedLineNumber |
500 | JavaScript kodunda bir hata oluştu. Ayrıntılar için hata dizesine bakın. | Yok |
steps.javascript.ScriptSecurityError |
500 | JavaScript yürütüldüğünde bir güvenlik hatası oluştu. Ayrıntılar için hata dizesine bakın. | Yok |
Dağıtım hataları
Bu hatalar, bu politikayı içeren bir proxy dağıttığınızda ortaya çıkabilir.
Hata adı | Neden | Düzelt |
---|---|---|
InvalidResourceUrlFormat |
JavaScript politikasının <ResourceURL> veya <IncludeURL> öğesi içinde belirtilen kaynak URL'sinin biçimi geçersizse API proxy'sinin dağıtımı başarısız olur. |
build |
InvalidResourceUrlReference |
<ResourceURL> veya <IncludeURL> öğeleri mevcut olmayan bir JavaScript dosyasına başvuruda bulunuyorsa API proxy'sinin dağıtımı başarısız olur.
Başvurulan kaynak dosya API proxy'si, ortam veya kuruluş düzeyinde bulunmalıdır. |
build |
WrongResourceType |
Bu hata, JavaScript politikasının <ResourceURL> veya <IncludeURL> öğeleri jsc (JavaScript dosyası) dışındaki bir kaynak türüne referans veriyorsa dağıtım sırasında ortaya çıkar. |
build |
NoResourceURLOrSource |
<ResourceURL> öğesi bildirilmemişse veya kaynak URL'si bu öğe içinde tanımlı değilse JavaScript politikasının dağıtımı bu hatayla başarısız olabilir.
<ResourceURL> öğesi zorunlu bir öğe. Alternatif olarak, <IncludeURL> öğesi açıklanır ancak kaynak URL'si bu öğe içinde tanımlı değildir. <IncludeURL> öğesi isteğe bağlıdır ancak belirtilmesi durumunda kaynak URL'si <IncludeURL> öğesi içinde belirtilmelidir. |
build |
Hata değişkenleri
Bu değişkenler, bu politika çalışma zamanında bir hata tetiklediğinde ayarlanır. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler bölümüne bakın.
Değişkenler | Konum | Örnek |
---|---|---|
fault.name="fault_name" |
fault_name, yukarıdaki Çalışma zamanı hataları tablosunda listelenen hatanın adıdır. Hata adı, hata kodunun son kısmıdır. | fault.name Matches "ScriptExecutionFailed" |
javascript.policy_name.failed |
policy_name, hataya neden olan politikanın kullanıcı tarafından belirtilen adıdır. | javascript.JavaScript-1.failed = true |
Örnek hata yanıtı
{ "fault": { "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"", "detail": { "errorcode": "steps.javascript.ScriptExecutionFailed" } } }
Hata kuralı örneği
<FaultRule name="JavaScript Policy Faults"> <Step> <Name>AM-CustomErrorResponse</Name> <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition> </Step> <Condition>(javascript.JavaScript-1.failed = true) </Condition> </FaultRule>
Şema
Her politika türü, bir XML şeması (.xsd
) ile tanımlanır. Referans olarak, GitHub'da politika şemaları bulunabilir.
İlgili konular
- JavaScript nesne modeli
- Talimatlar, politika örnekleri ve JavaScript örnekleri için API proxy'lerini JavaScript ile programlama sayfasına bakın.
Apigee Topluluğu makaleleri
Apigee Topluluğu'nda ilgili şu makaleleri bulabilirsiniz: