Politika bileşimini kullanma

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

Bu konuda, politika bileşimi özelliğini kullanarak nasıl mashup oluşturacağınızı öğreneceksiniz. Politika bileşimi, birden fazla arka uç hedefinden gelen sonuçları politikaları kullanarak tek bir yanıtta birleştirmenizi sağlayan bir Apigee proxy kalıbıdır.

Politika yapısına genel bir bakış için API Proxy Çözüm Kitabı kalıpları sayfasındaki "Politika bileşimi kalıbı" bölümüne bakın.

Örnek kodu indirip deneyin

Bu tarif defteri örneği hakkında

Bu tarif defteri örneği, politika bileşimi adlı bir API proxy kalıbını gösterir. Bu kalıp, birden fazla arka uç kaynağından gelen verileri birleştirmek için bir yol (başkaları da vardır) sağlar. Daha genel olarak bu konu, istenen sonucu elde etmek için politikaların nasıl birleştirilip zincirlendiğini gösterir. Bu kalıp ve diğer ilgili kalıplara genel bir bakış için API Proxy Kılavuzu kalıpları sayfasına bakın.

Burada açıklanan örnekte, aşağıdaki iki ayrı herkese açık API'den gelen verileri birleştirmek için politika bileşimi kullanılmaktadır:

  • Google Coğrafi Kodlama API'si: Bu API, adresleri (ör. "1600 Amphitheatre Parkway, Mountain View, CA") coğrafi koordinatlara (ör. 37.423021 enlem ve -122.083739 boylam) dönüştürür.
  • Google Elevation API Bu API, yükseklik verilerine yönelik olarak dünyadaki konumları sorgulamak için basit bir arayüz sağlar. Bu örnekte, Coğrafi Kodlama API'sinden döndürülen koordinatlar bu API'ye giriş olarak kullanılacaktır.

Uygulama geliştiriciler, bu API proxy'sini iki sorgu parametresiyle (posta kodu ve ülke kimliği) çağırır:

$ curl "http://{myorg}-test.apigee.net/policy-mashup-cookbook?country=us&postalcode=08008"

Yanıt, sağlanan posta kodu alanının merkezinin coğrafi konumu (enlem/boylam) içeren bir JSON nesnesidir ve bu konumdaki yükseltiyle birlikte.

{  
   "ElevationResponse":{  
      "status":"OK",
      "result":{  
         "location":{  
            "lat":"39.7500713",
            "lng":"-74.1357407"
         },
         "elevation":"0.5045232",
         "resolution":"76.3516159"
      }
   }
}

Başlamadan önce

Politika bileşimi kalıbıyla ilgili kısa bir genel bakış okumak isterseniz API Proxy Çözüm Kitabı kalıpları sayfasındaki "Politika bileşimi kalıbı" bölümüne bakın.

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, API 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 çeşitli politikalar oluşturulup API proxy'sinin 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. Bu tarif defteri konusu, API proxy'sini geliştirmek için yönetim kullanıcı arayüzünü kullanabileceğiniz bulut tabanlı geliştirmenin aksine yerel geliştirmeyi (dosya sistemi tabanlı) gösterir.
  • API anahtarı doğrulamasını kullanma. Bu, API'ler için yapılandırabileceğiniz en basit uygulama tabanlı güvenlik biçimidir. Daha fazla bilgi için API anahtarları konusuna bakın. Ayrıca, API anahtarlarını zorunlu kılarak API'nin güvenliğini sağlama eğiticisini de inceleyebilirsiniz.
  • XML ile çalışma bilgisi. Bu örnekte, API proxy'sini ve politikalarını dosya sisteminde bulunan XML dosyalarıyla oluşturuyoruz.

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

Akışa ayak uydurma

Politikalara geçmeden önce örnek API proxy'mizin ana akışına göz atalım. Aşağıda gösterilen akış XML'si; bu proxy, kullandığı politikalar ve bu politikaların adlandırılması hakkında bize çok şey anlatır.

Örnek indirmede bu XML'i doc-samples/policy-mashup-cookbook/apiproxy/proxies/default.xml dosyasında bulabilirsiniz.

<ProxyEndpoint name="default">
  <Flows>
    <Flow name="default">
      <Request>
            <!-- Generate request message for the Google Geocoding API -->
            <Step><Name>GenerateGeocodingRequest</Name></Step>
            <!-- Call the Google Geocoding API -->
            <Step><Name>ExecuteGeocodingRequest</Name></Step>
            <!-- Parse the response and set variables -->
            <Step><Name>ParseGeocodingResponse</Name></Step>
            <!-- Generate request message for the Google Elevation API -->
            <Step><Name>AssignElevationParameters</Name></Step>
      </Request>
      <Response>
            <!-- Parse the response message from the Elevation API -->
            <Step><Name>ParseElevationResponse</Name></Step>
            <!-- Generate the final JSON-formatted response with JavaScript -->
            <Step><Name>GenerateResponse</Name></Step>
      </Response>
    </Flow>
  </Flows>

  <HTTPProxyConnection>
    <!-- Add a base path to the ProxyEndpoint for URI pattern matching-->
    <BasePath>/policy-mashup-cookbook</BasePath>
    <!-- Listen on both HTTP and HTTPS endpoints -->
    <VirtualHost>default</VirtualHost>
    <VirtualHost>secure</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <!-- Connect ProxyEndpoint to named TargetEndpoint under /targets -->
    <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şturacağımız politikalardan birini çağırır. Bu politikalar; istek mesajı oluşturma, gönderme ve yanıtı ayrıştırma ile ilgilidir. Bu konuyu bitirdiğinizde bu politikaların her birinin rolünü öğrenmiş olacaksınız.
  • <Response>: <Response> öğesi ayrıca <Steps>'i içerir. Bu adımlar aynı zamanda hedef uç noktadan (Google Elevation API) son yanıtı işlemekten sorumlu politikaları da çağırır.
  • <HttpProxyConnection> - Bu öğe, uygulamaların bu API proxy'sine nasıl bağlanacağıyla ilgili ayrıntıları belirtir. Bu API'nin nasıl çağrılacağını belirten <BasePath> de dahildir.
  • <RouteRule> - Bu öğe, gelen istek mesajları işlendikten hemen sonra ne olacağını belirtir. Bu durumda, TargetEndpoint çağrılır. Bu önemli adımla ilgili daha fazla bilgiyi bu konunun ilerleyen bölümlerinde açıklayacağız.

Politikaları oluşturma

Aşağıdaki bölümlerde bu politika bileşimi örneğini oluşturan politikaların her biri açıklanmaktadır.

İlk AtaMessage politikasını oluşturun

Aşağıda listelenen ilk AssignMessage politikası, Google Coğrafi Kodlama hizmetine gönderilecek bir istek mesajı oluşturur.

Önce politika koduyla başlayalım ve ardından bileşenlerini daha ayrıntılı olarak açıklayacağız. Örnek indirmede bu XML'i doc-samples/policy-mashup-cookbook/apiproxy/policies/GenerateGeocodingRequest.xml dosyasında bulabilirsiniz.

<AssignMessage name="GenerateGeocodingRequest">
  <AssignTo createNew="true" type="request">GeocodingRequest</AssignTo>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
      <QueryParam name="region">{request.queryparam.country}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <!-- Set variables for use in the final response -->
  <AssignVariable>
    <Name>PostalCode</Name>
    <Ref>request.queryparam.postalcode</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

Aşağıda, bu politikanın unsurlarıyla ilgili kısa bir açıklama yer almaktadır. Bu politikayla ilgili daha fazla bilgiyi Mesaj politikası atama başlıklı makalede bulabilirsiniz.

  • <AssignmentMessage name> - Bu politikaya bir ad verir. Ad, bir akışta politikaya referans verildiğinde kullanılır.
  • <AssignTo> - GeocodingRequest adlı bir adlandırılmış değişken oluşturur. Bu değişken, ServiceCall politikası tarafından arka uca gönderilecek istek nesnesini içerir.
  • <QueryParams> - Arka uç API çağrısının ihtiyaç duyduğu sorgu parametrelerini ayarlar. Bu durumda Coğrafi Kodlama API'sinin konumu (bir posta kodu ve ülke kimliği ile) bilmesi gerekir. Uygulama kullanıcısı bu bilgileri sağlar, biz de bilgileri buradan alırız. sensor parametresi API için zorunlu kılınır ve doğru ya da yanlıştır. Parametreyi burada false (yanlış) olarak kodlıyoruz.
  • <Verb>: Bu örnekte, API'ye basit bir GET isteği yaparız.
  • <AssignVariable> - Bu değişkenler, API'ye ilettiğimiz değerleri depolar. Bu örnekte, değişkenlere daha sonra istemciye döndürülen yanıtta erişilir.

İsteği ServiceDescription ile gönderme

Politika bileşim sırasının bir sonraki adımı bir ServiceCallout politikası oluşturmaktır. Aşağıda listelenen Service Console politikası, önceki AtaMessage politikasında oluşturduğumuz istek nesnesini Google Coğrafi Kodlama hizmetine gönderir ve sonucu GeocodingResponse adlı bir değişkene kaydeder.

Daha önce olduğu gibi, önce koda göz atalım. Ayrıntılı açıklama aşağıda yer almaktadır. Bu politika hakkında daha fazla bilgiyi Hizmet Çağrı Politikası'nda bulabilirsiniz. Örnek indirmede bu XML'i doc-samples/policy-mashup-cookbook/apiproxy/policies/ExecuteGeocodingRequest.xml dosyasında bulabilirsiniz.

<ServiceCallout name="ExecuteGeocodingRequest">
  <Request variable="GeocodingRequest"/>
  <Response>GeocodingResponse</Response>
  <HTTPTargetConnection>
    <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
  </HTTPTargetConnection>
</ServiceCallout>

Bu politikanın unsurlarıyla ilgili kısa bir açıklamayı aşağıda bulabilirsiniz.

  • <ServiceCallout> - Önceki politikada olduğu gibi, bunun bir adı vardır.
  • <Request}{ (İstek değişkeni) - Bu, AtaMessage politikasında oluşturulan değişkendir. Arka uç API'sine giden isteği içerir.
  • <Response> - Bu öğe, yanıtın saklandığı bir değişkeni adlandırır. Gördüğünüz üzere bu değişkene daha sonra ExtractVariables politikası tarafından erişilir.
  • <HTTPTargetConnection> - Arka uç API'sinin hedef URL'sini belirtir. Bu durumda, API'nin bir JSON yanıtı döndürdüğünü belirtiriz.

Artık arka uç API'sini (Google'ın Coğrafi Kodlama API'si) kullanmak için gereken istek bilgilerini belirten ve ikincisi isteği arka uç API'sine gönderen olmak üzere iki politikamız var. Sonrasında yanıtı biz hallederiz.

Yanıtı ExtractVariables ile ayrıştırın

Değişkenleri Ayıklama politikası, bir ServiceCall politikası tarafından alınan yanıt mesajındaki içeriği ayrıştırmak için basit bir mekanizma sağlar. ExtractVariables, JSON veya XML'i ayrıştırmak için ya da URI yollarından, HTTP üstbilgilerinden, sorgu parametrelerinden ve form parametrelerinden içerik ayıklamak için kullanılabilir.

ExtractVariables politikasının listesini aşağıda bulabilirsiniz. Bu politikayla ilgili daha fazla bilgiyi Değişkenleri Ayıklama politikası bölümünde bulabilirsiniz. Örnek indirmede bu XML'i doc-samples/policy-mashup-cookbook/apiproxy/policies/ParseGeocodingResponse.xml dosyasında bulabilirsiniz.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>GeocodingResponse</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>

ExtractVariable politikasının temel öğeleri şunlardır:

  • <ExtractVariables name>: Politika adı, bir akışta kullanıldığında politikayı belirtmek için kullanılır.
  • <Source> - ServiceCall politikasında oluşturduğumuz yanıt değişkenini belirtir. Bu politika, verileri çıkarmak için bu değişkendir.
  • <VariablePrefix> - Değişken öneki, bu politikada oluşturulan diğer değişkenler için bir ad alanı belirtir. Ön ek, Edge'ın önceden tanımlanmış değişkenleri tarafından tanımlanan ayrılmış adlar hariç herhangi bir ad olabilir.
  • <JSONPayload> - Bu öğe, bizi ilgilendiren yanıt verilerini alır ve adlandırılmış değişkenlere yerleştirir. Hatta Coğrafi Kodlama API'si, enlem ve boylamdan çok daha fazla bilgi döndürür. Ancak bu örnek için ihtiyacımız olan tek değerler budur. Geocoding API tarafından döndürülen JSON dosyasının eksiksiz bir oluşturulmasını API'nin dokümanlarında görebilirsiniz. geometry.location.lat ve geometry.location.lng değerleri, döndürülen JSON nesnesindeki pek çok alandan yalnızca ikisidir.

Çok açık olmasa da Değişken Ayıklamalarının, adları politikada belirtilen değişken ön ek (coğrafi yanıt) ve gerçek değişken adlarından oluşan iki değişken ürettiğini bilmek önemlidir. Bu değişkenler, API proxy'sinde depolanır ve göreceğiniz gibi proxy akışındaki diğer politikalar tarafından kullanılabilir. Değişkenler şunlardır:

  • geocoderesponse.latitude
  • geocoderesponse.longitude

İşin çoğu tamamlandı. Bir istek oluşturan, bir arka uç API'sini çağıran ve döndürülen JSON verilerini ayrıştıran üç politikadan oluşan bir bileşik oluşturduk. Son adımlarda, akışın bu bölümündeki verileri başka bir AtaMessage politikasına aktaracak, ikinci arka uç API'sini (Google Elevation API) çağıracak ve derlenmiş verilerimizi uygulama geliştiricisine iade edeceğiz.

AtaMessage ile ikinci isteği oluşturma

Aşağıdaki AtaMessage politikası, depoladığımız ilk arka uçtan (Google Coğrafi Kodlama) döndürülen değişkenleri kullanır ve bunları ikinci API'ye (Google Elevation) hedefleyen bir isteğe ekler. Daha önce belirtildiği gibi, bu değişkenler coğrafi yanıt.Enlem ve coğrafya kodu/boylam değişkenidir.

Örnek indirmede bu XML'i doc-samples/policy-mashup-cookbook/apiproxy/policies/AssignElevationParameters.xml dosyasında bulabilirsiniz.

<AssignMessage name="AssignElevationParameters">
<Remove>
    <QueryParams>
      <QueryParam name="country"/>
      <QueryParam name="postalcode"/>
    </QueryParams>
  </Remove>
  <Set>
    <QueryParams>
      <QueryParam name="locations">{geocoderesponse.latitude},{geocoderesponse.longitude}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

Google Elevation API'yi incelerseniz iki sorgu parametresi aldığını görürsünüz. İlki locations olarak adlandırılır. Değeri ise enlem ve boylamdır (virgülle ayrılmış değerler). Diğer parametre, zorunlu olup doğru veya yanlış olması gereken sensor değeridir. Bu noktada dikkat edilmesi gereken en önemli nokta, burada oluşturacağımız istek mesajı için bir ServiceSpecification gerekmemesidir. Arka uç API'sini proxy'nin TargetEndpoint'inden çağırabildiğimiz için bu noktada bir ServiceCall'dan ikinci API'yi çağırmamıza gerek yoktur. Google Elevations API'yi çağırmak için gereken tüm veriler elimizde mevcut demektir Bu adımda oluşturulan istek mesajı, ana istek ardışık düzeni için oluşturulan istek olarak bir ServiceDescription gerektirmez ve bu API proxy'si için yapılandırılan RouteRule uygulanarak ProxyEndpoint tarafından TargetEndpoint'e yönlendirilir. TargetEndpoint, uzak API ile bağlantıyı yönetir. (Yükseltme API'sine ait URL'nin, TargetEndpoint'in HTTPConnection'ında tanımlandığını hatırlayın. Daha fazla bilgi için Elevation API belgelerine göz atın. Daha önce depoladığımız country ve postalcode adlı QueryParam'lara artık ihtiyaç duyulmadığından bunları buradan kaldırıyoruz.

Kısa bir duraklama: Akışa geri dönün

Bu noktada, neden başka bir ServiceCallout politikası oluşturmadığımızı merak ediyor olabilirsiniz. Sonuçta başka bir mesaj oluşturduk. Bu mesaj Google Elevation API hedefine nasıl gönderilir? Yanıt, akışın <RouteRule> öğesindedir. <RouteRule>, akışın <Request> bölümü yürütüldükten sonra kalan istek mesajlarıyla ne yapılacağını belirtir. Bu <RouteRule> tarafından belirtilen TargetEndpoint, API proxy'sine mesajı http://maps.googleapis.com/maps/api/elevation/xml hizmetine iletmesini bildirir.

Örnek API proxy'sini indirdiyseniz TargetProxy XML'yi doc-samples/policy-mashup-cookbook/apiproxy/targets/default.xml dosyasında bulabilirsiniz.

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <!-- This is where we define the target. For this sample we just use a simple URL. -->
    <URL>http://maps.googleapis.com/maps/api/elevation/xml</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Şimdi sadece Google Elevation API'den gelen yanıtı işlememiz gerekiyor.

Yanıtı XML'den JSON'a dönüştürün

Bu örnekte, Google Elevation API'den gelen yanıt XML olarak döndürülür. "Ekstra kredi" için yanıtı XML'den JSON'a dönüştürmek için bileşenimize bir politika daha ekleyelim.

Bu örnekte, dönüştürme işlemi için GenerateResponse adlı JavaScript politikası ve JavaScript kodunu içeren bir kaynak dosyası kullanılmaktadır. Aşağıda, GenerateResponse politika tanımı gösterilmektedir:

<Javascript name="GenerateResponse" timeout="10000">
  <ResourceURL>jsc://GenerateResponse.js</ResourceURL>
</Javascript>

GenerateResponse.js kaynak dosyası, dönüşümü gerçekleştirmek için kullanılan JavaScript'i içerir. Bu kodu doc-samples/policy-mashup-cookbook/apiproxy/resources/JSC/GenerateResponse.js dosyasında görebilirsiniz.

Apigee, XML'i JSON'a dönüştürmek için kullanıma hazır bir politika olan XMLToJSON da sunar. Bunun yerine aşağıda gösterilen xmltojson politikasını kullanmak için ProxyEndpoint'i düzenleyebilirsiniz.

<XMLToJSON name="xmltojson">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

Örneği test etme

Henüz yapmadıysanız policy-mashup-Recipebook örneğini indirmeyi, dağıtmayı ve çalıştırmayı deneyin. Bu örneği, Apigee Edge örnek deposu GitHub'daki doc-samples klasöründe bulabilirsiniz. Policy-mashup- Cookbook klasöründeki README dosyasındaki talimatları uygulamanız yeterlidir. Alternatif olarak buradaki kısa talimatları da uygulayabilirsiniz: Örnek API proxy'lerini kullanma.

Özetlemek gerekirse, bileşik API'yi aşağıdaki gibi çağırabilirsiniz. {myorg} bölümünü kuruluşunuzun adıyla değiştirin:

$ curl "http://{myorg}-test.apigee.net/policy-mashup-cookbook?country=us&postalcode=08008"

Yanıtta, uygulama son kullanıcısı tarafından sağlanan posta kodu merkezinin coğrafi kodlamalı konumu, coğrafi kodlaması yapılan konumdaki yükseklik ile birlikte yer alır. Veriler iki arka uç API'sinden alındı, API proxy'sine ekli politikalarla karıştırıldı ve tek bir yanıtla istemciye döndürüldü.

{  
   "country":"us",
   "postalcode":"08008",
   "elevation":{  
      "meters":0.5045232,
      "feet":1.6552599030345978
   },
   "location":{  
      "latitude":39.75007129999999,
      "longitude":-74.1357407
   }
}

Özet

Bu tarif defteri konusu, birden fazla arka uç kaynağından karma bir veri oluşturmak için politika bileşimi kalıbının nasıl kullanılacağını açıklar. Politika bileşimi, API'nize reklam öğesi işlevselliği eklemek için API proxy'si geliştirmede yaygın olarak kullanılan bir kalıptır.