JavaScript ile API proxy'lerini programlama

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

Bu konuda, yanıt mesajına dinamik olarak HTTP başlıkları eklemek için JavaScript'i nasıl kullanacağınızı, JSON yanıtını ayrıştırıp özelliklerinin bir alt kümesini istekte bulunan uygulamaya nasıl döndüreceğinizi öğreneceksiniz.

Örnek kodu indirip deneyin

Bu tarif defteri örneği hakkında

Bu tarif defteri örneği, JavaScript'te API davranışını uyguladığınız bir API proxy kalıbını göstermektedir. JavaScript örnekleri, basit değişkenler ve mesaj içeriğiyle nasıl çalışacağınızı göstermek için tasarlanmıştır. Aşağıda, değişkenlerin nasıl alınacağı ve ayarlanacağı gösterilmektedir. İkinci örnek, JSON'u nasıl ayrıştıracağınız ve sonuçtan nasıl mesaj oluşturacağınız gösterir.

API proxy'sinde iki JavaScript örneği bulunmaktadır:

• setHeaders.js: Bu JavaScript, bir API proxy'si çağrıldığında ayarlanan birkaç değişkenin değerini alır. JavaScript, bu değişkenleri yanıt mesajına ekler. Böylece, yaptığınız her istek için değerlerini görebilirsiniz.
• minimize.js: Bu JavaScript, mesaj içeriğiyle nasıl çalışacağınızı gösterir. Bu örneğin arkasındaki fikir, bir hizmetin genellikle gerekenden daha fazla veri döndürmesidir. Böylece JavaScript, yanıt mesajını ayrıştırır, birkaç ilginç özelliği çıkarır ve ardından bunları yanıt mesajının içeriğini oluşturmak için kullanır.

setHeader.js kodu:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

minimize.js kodu:

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

JavaScript'teki akış değişkenlerine bağlam nesnesi aracılığıyla erişebilirsiniz. Bu nesne, Edge JavaScript nesne modelinin bir parçasıdır. Nesne modeliyle ilgili ayrıntılar için JavaScript nesne modeli bölümüne bakın.

Başlamadan önce

Bu tarif defteri örneğini incelemeden önce şu temel kavramlar hakkında da bilgi sahibi olmanız gerekir:

• Politikalar nedir ve proxy'lere nasıl eklenir? Politikalar hakkında iyi bir giriş için Politika nedir? bölümüne bakın.
• Akışları yapılandırma bölümünde açıklandığı üzere, proxy akışının yapısı. Akışlar, politikaların bir API proxy'si tarafından yürütülme sırasını belirtmenizi sağlar. Bu örnekte birkaç politika oluşturulup API proxy akışına eklenmiştir.
• API proxy yapılandırması referansı bölümünde açıklandığı gibi, bir API proxy projesinin dosya sisteminizde nasıl düzenlendiği.
• XML, JSON ve JavaScript ile ilgili çalışma bilgisi. Bu örnekte, API proxy'sini ve politikalarını dosya sisteminde bulunan XML dosyalarıyla oluşturacaksınız.

Örnek kodu indirdiyseniz bu konuda tartışılan tüm dosyaları javascript-cookbook örnek klasöründe bulabilirsiniz. Aşağıdaki bölümlerde örnek kod ayrıntılı olarak ele alınmaktadır.

Proxy akışını anlama

JavaScript'in API proxy'sinde çalışmasını sağlamak için bunu, "Adım" adı verilen bir politika eki kullanarak bir akışa eklemeniz gerekir. JavaScript türündeki bir politika (not büyük harf kullanımı), yalnızca JavaScript dosyasının adına bir referans içerir. Politikayı, ResourceURL öğesini kullanarak bir JavaScript dosyasına yönlendirirsiniz.

Örneğin, aşağıdaki politikada setHeader.js adlı JavaScript dosyasına referans verilmiştir.

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

Bu politikayı, diğer politika türlerinde olduğu gibi API proxy akışına ekleyebilirsiniz. Politikayı API proxy akışına ekleyerek JavaScript'in nerede yürütülmesi gerektiğini belirtirsiniz. Böylece, istek mesajları veya yanıt mesajları API proxy'si üzerinden "akış" şeklinde etkileşim kuran JavaScript'leri yürütebilirsiniz. Bu örnekte, politikaların iki şey yapması nedeniyle her iki JavaScript de yanıt akışında yürütülür: yanıt mesajında HTTP üstbilgileri ayarlamak ve Apigee Edge'in istekte bulunan uygulamaya döndürdüğü yanıt mesajını "en aza indirmek".

Bu akış yapılandırmasını yönetim kullanıcı arayüzünde açarsanız aşağıda akış yapılandırmasını görürsünüz.

Gezgin bölmesinde Proxy Uç Noktaları > varsayılan > PostFlow'u seçin.

"Varsayılan" adlı ProxyEndpoint için karşılık gelen XML yapılandırması aşağıda gösterilmektedir.

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Akıştaki öğelerin özetini burada bulabilirsiniz.

• <Request> - <Request> öğesi, birkaç <Step> öğesinden oluşur. Her adım, bu konunun geri kalanında oluşturduğunuz politikalardan birini çağırır. Bu politikalar, API proxy akışına bir JavaScript ekler ve politika ekinin konumu, JavaScript'in ne zaman yürütüleceğini belirler.
• <Response>: <Response> öğesi ayrıca <Steps>'i içerir. Bu adımlar aynı zamanda hedeften gelen son yanıtı (bu örnekte Apigee'nin sahte hizmet hedefidir) işlemekten sorumlu politikaları da çağırır. /apiproxy/targets/default.xml bölümündeki HTTPTargetConnection ayarına dikkat edin.
• <HTTPProxyConnection> - Uygulamaların bu API'yi tüketmek için çağırdığı ağ adresini tanımlayan ana makineyi ve URI yolunu belirtir.
  
• <RouteRule> - Bu öğe, ProxyEndpoint tarafından hangi TargetEndpoint yapılandırmasının çağrılacağını belirtir.

Proxy'ye JavaScript kodu ekleme

JavaScript (Python komut dosyaları, Java JAR dosyaları, XSLT dosyaları vb.) kaynak olarak depolanır. JavaScript ile çalışmaya yeni başlıyorsanız JavaScript dosyalarınızı API proxy'sinde depolamak en kolayıdır. İlerleyen zamanlarda JavaScript'in olabildiğince genel ve yeniden kullanılabilir olması, ardından ortam veya kuruluş düzeyinde depolanması gerekir. Böylece aynı JavaScript dosyalarını birden fazla API proxy'sinde depolamak zorunda kalmazsınız. Bu durum kısa sürede yönetilemez.

Kaynakları kuruluş ve ortam düzeyinde depolama hakkında bilgi edinmek için Kaynak dosyaları başlıklı makaleye bakın.

Deneyin

Proxy'yi dağıtma ve çağırma talimatları için JavaScript çözüm kitabı BENİOKU'yu inceleyin.

API proxy'sini içe aktarma ve dağıtma

Değişiklik yaptıktan sonra yönetim kullanıcı arayüzündeki API proxy oluşturucu aracındaki API proxy'sini kaydedebilirsiniz.

Alternatif olarak, /api-platform-samples/doc-samples/javascript-cookbook dizininde aşağıdaki komutu çalıştırabilirsiniz.

$ sh deploy.sh

JavaScript'i test etme

/api-platform-samples/doc-samples/javascript-cookbook dizininde aşağıdaki komutu çalıştırın.

$ sh invoke.sh

-v curl işareti, kabuk komut dosyasında JavaScript tarafından değiştirilen yanıt mesajındaki HTTP üst bilgilerini görüntülemek için kullanılır.

Aşağıdaki şekilde doğrudan istek gönderebilirsiniz:

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook 

JavaScript düzgün bir şekilde çalışıyorsa aşağıdaki gibi bir yanıt görürsünüz:

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

Artık yeni şeyler denemek için JavaScript'i değiştirebilir, API proxy'sini yeniden dağıtabilir ve aynı isteği göndererek sonuçları doğrulayabilirsiniz. Değişikliklerinizin geçerli olması için JavaScript'inizi içeren API proxy'sini dağıttığınızdan her zaman emin olun.

Komut dosyası hataları

JavaScript yazarken kaçınılmaz olarak hatalar görürsünüz. Bir API proxy'si tarafından verilen JavaScript hatalarının biçimi aşağıda gösterilmektedir.

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

JavaScript ne zaman kullanılır?

Apigee Edge'de belirli işlevleri uygulamak için genellikle birden fazla yöntem vardır. Mümkün olduğunda kullanıma hazır politikaları kullanın ve API proxy mantığınızın tamamını JavaScript'te kodlamaktan kaçının. Apigee Edge performansı artırmak için derlenmiş JavaScript'ten yararlansa da JavaScript'in Politikalar kadar iyi performans göstermesi olası değildir. JavaScript'in bakımı ve hata ayıklaması daha zor olabilir. JavaScript'i, gereksinimlerinize özel işlevler için ayırın.

Performans, özel işlevlerle ilgiliyse mümkünse Java kullanın.

Özet

Bu tarif defteri konusunda, özel bir davranış uygulamak için API proxy yapılandırmasına JavaScript'in nasıl dahil edilebileceğini öğrendiniz. Örneklerin uyguladığı özel davranış, değişkenlerin nasıl alınacağını, JSON'un nasıl ayrıştırılacağını ve özel yanıt mesajlarının nasıl oluşturulacağını gösterir.