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 HTTP üstbilgilerini dinamik olarak eklemek için JavaScript'i nasıl kullanacağınızı ve JSON yanıtını nasıl ayrıştırıp özelliklerinin bir alt kümesini istekte bulunan uygulamaya nasıl döndüreceğinizi öğreneceksiniz.

Örnek kodu indirip deneyin

Bu çözüm kitabı örneği hakkında

Bu çözüm kitabı örneğinde, API davranışını JavaScript'te uyguladığınız bir API proxy'si kalıbı gösterilmektedir. JavaScript örnekleri, basit değişkenler ve mesaj içeriğiyle nasıl çalışacağınızı göstermek için tasarlanmıştır. Bir örnekte değişkenleri nasıl alacağınız ve ayarlayacağınız gösterilmektedir. İkinci örnekte, JSON'u nasıl ayrıştıracağınız ve sonuçtan nasıl mesaj oluşturacağınız gösterilmektedir.

API proxy'sinde iki JavaScript örneği bulunur:

  • setHeaders.js: Bu JavaScript, bir API proxy'si çağrıldığında ayarlanan birkaç değişkenin değerlerini alır. JavaScript, bu değişkenleri yanıt mesajına ekler. Böylece, yaptığınız her istek için bu değişkenlerin 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ürdüğüdür. Bu nedenle, JavaScript yanıt mesajını ayrıştırır, birkaç ilginç özelliği çıkarır ve ardından bunları kullanarak yanıt mesajının içeriğini oluşturur.

setHeader.js için kod:

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 için kod:

// 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);

Bağlam nesnesi aracılığıyla JavaScript'teki akış değişkenlerine erişebilirsiniz. Bu nesne, Edge JavaScript nesne modelinin bir parçasıdır. Nesne modeliyle ilgili ayrıntılar için JavaScript nesne modeli başlıklı makaleyi inceleyin.

Başlamadan önce

Bu çözüm kitabı örneğini incelemeden önce aşağıdaki temel kavramlar hakkında da bilgi sahibi olmanız gerekir:

  • Politikalar ve bunları proxy'lere nasıl ekleyeceğiniz. Politikalarla ilgili iyi bir giriş için Politika nedir? başlıklı makaleyi inceleyin.
  • Akışları yapılandırma bölümünde açıklandığı gibi bir proxy akışının yapısı. Akışlar, politikaların API proxy'si tarafından yürütülme sırasını belirtmenize olanak tanır. Bu örnekte, birkaç politika oluşturulup bir API proxy akışına eklenir.
  • API proxy'si yapılandırma referansı'nda açıklandığı gibi, API proxy'si projesinin dosya sisteminizde nasıl düzenlendiği.
  • XML, JSON ve JavaScript hakkında bilgi sahibi olmak Bu örnekte, API proxy'sini ve politikalarını dosya sisteminde bulunan XML dosyalarıyla oluşturursunuz.

Örnek kodu indirdiyseniz bu konuda bahsedilen 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 bir API proxy'sinde yürütülmesini sağlamak için JavaScript'i "Adım" adı verilen bir politika eki kullanarak akışa eklemeniz gerekir. JavaScript türündeki bir politika (büyük harf kullanımına dikkat edin) yalnızca bir JavaScript dosyasının adına yapılan referansı içerir. ResourceURL öğesini kullanarak politikayı bir JavaScript dosyasına yönlendirirsiniz.

Örneğin, aşağıdaki politika setHeader.js adlı JavaScript dosyasına referans veriyor.

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

Bu politikayı, diğer politika türlerinde olduğu gibi bir API proxy akışına ekleyebilirsiniz. Politikayı API proxy akışına ekleyerek JavaScript'in nerede yürütülmesi gerektiğini belirtirsiniz. Bu sayede, API proxy'sinden "geçen" istek mesajları veya yanıt mesajlarıyla etkileşime giren JavaScript'i yürütebilirsiniz. Bu örnekte, politikalar iki işlem yaptığından her iki JavaScript de yanıt akışında yürütülür: Yanıt mesajında HTTP üstbilgilerini ayarlama ve Apigee Edge'in istekte bulunan uygulamaya döndürdüğü yanıt mesajını "küçültme".

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

Gezgin bölmesinde Proxy Endpoints > default > PostFlow'u seçin.

Aşağıda, "default" adlı ProxyEndpoint için ilgili XML yapılandırması 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ışın öğelerinin özetini aşağıda bulabilirsiniz.

  • <Request>: <Request> öğesi, birkaç <Step> öğesinden oluşur. Her adımda, bu konunun geri kalanında oluşturduğunuz politikalardan biri çağrılır. Bu politikalar, API proxy akışına bir JavaScript ekler ve politika ekleme konumu, JavaScript'in ne zaman yürütüleceğini belirler.
  • <Response>: <Response> öğesi <Steps> öğesini de içerir. Bu adımlar, hedeften gelen nihai yanıtın işlenmesinden sorumlu politikaları da çağırır (Bu örnekte, Apigee'nin sahte hizmet hedefi söz konusudur. /apiproxy/targets/default.xml bölümündeki HTTPTargetConnection ayarına dikkat edin).
  • <HTTPProxyConnection>: Uygulamaların bu API'yi kullanmak 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ıldığını belirtir.

Bir proxy'ye JavaScript kodu ekleme

JavaScript (ör. Python komut dosyaları, Java JAR dosyaları, XSLT dosyaları vb.) kaynak olarak depolanır. JavaScript ile çalışmaya yeni başladığınızda JavaScript dosyalarınızı API proxy'sinde saklamak en kolay yöntemdir. İlerledikçe JavaScript olabildiğince genel ve yeniden kullanılabilir hale getirilmeli, ardından ortam veya kuruluş düzeyinde depolanmalıdır. Bu sayede, aynı JavaScript dosyalarını birden fazla API proxy'sinde depolamanız gerekmez. Bu durum, kısa sürede yönetilemez hale gelebilir.

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

Deneyin

Proxy'yi dağıtma ve çağırma talimatları için JavaScript cookbook README başlıklı makaleyi inceleyin.

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

Değişiklik yaptıktan sonra API proxy'sini yönetim kullanıcı arayüzündeki API proxy oluşturucu aracında 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

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

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

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

JavaScript düzgün şekilde yürütülürse aşağıdakine benzer 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 JavaScript'i değiştirerek yeni şeyler deneyebilir, 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 her zaman dağıttığınızdan emin olun.

Komut dosyası hataları

JavaScript yazarken kaçınılmaz olarak hatalarla karşılaşırsınız. Bir API proxy'si tarafından verilen JavaScript hatalarının biçimi aşağıda gösterilmiştir.

{  
   "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 yol vardır. Mümkün olduğunda hazır politikaları kullanın ve API proxy'nizin tüm mantığını JavaScript'te kodlama isteğine karşı koyun. 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 yalnızca gereksinimlerinize özel işlevler için kullanın.

Özel işlevlerde performans önemliyse mümkün olduğunda Java'yı kullanın.

Özet

Bu çözüm kitabı konusunda, özel davranışları uygulamak için JavaScript'in API proxy'si yapılandırmasına nasıl dahil edilebileceğini öğrendiniz. Örnekler tarafından uygulanan özel davranış, değişkenlerin nasıl alınacağını, JSON'ın nasıl ayrıştırılacağını ve özel yanıt mesajlarının nasıl oluşturulacağını gösterir.