Hizmet çağrısı politikası

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

Ne

Hizmet Çağrı Politikası, API proxy akışınızdan başka bir hizmeti çağırmanıza olanak tanır. Harici bir hizmete (harici RESTful hizmet uç noktası gibi) veya dahili hizmetlere (aynı kuruluş ve ortamdaki bir API proxy'si gibi) çağrı yapabilirsiniz.

• Harici bir kullanım durumunda, proxy'nizin dışındaki bir üçüncü taraf API'ye çağrı yaparsınız. Üçüncü taraf API'den gelen yanıt ayrıştırılır ve API'nizin yanıt mesajına eklenir. Böylece uygulama son kullanıcıları için veriler zenginleştirilir ve "derlenir". Ayrıca istek akışında Hizmet Çağrı Politikası'nı kullanarak istekte bulunabilir, ardından yanıttaki bilgileri API proxy'sinin TargetEndpoint'ine aktarabilirsiniz.
• Başka bir kullanım durumunda, çağrı yaptığınız kuruluş ve ortamda bulunan bir proxy'yi çağırırsınız. Örneğin, bir veya daha fazla proxy'nin tüketeceği münferit alt düzey işlevler sunan bir proxy'niz olduğunda bunu yararlı bulabilirsiniz. Örneğin, bir arka uç veri deposuna sahip oluşturma/okuma/güncelleme/silme işlemlerini açığa çıkaran bir proxy, verileri istemcilere sunan diğer birden çok proxy için hedef proxy olabilir.

Politika, HTTP ve HTTPS üzerinden yapılan istekleri destekler.

Örnekler

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

<ServiceCallout name="ServiceCallout-GeocodingRequest1">
    <DisplayName>Inline request message</DisplayName>
    <Request variable="authenticationRequest">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
          <QueryParam name="region">{request.queryparam.country}</QueryParam>
          <QueryParam name="sensor">false</QueryParam>
        </QueryParams>
      </Set>
    </Request>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout">
    <DisplayName>service-callout</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <LoadBalancer>
            <Algorithm>RoundRobin</Algorithm>
            <Server name="httpbin"/>
            <Server name="yahoo"/>
        </LoadBalancer>
        <Path>/get</Path>
    </HTTPTargetConnection>
</ServiceCallout>

Hizmet metni politikası hakkında

API proxy'nizde Hizmet Çağrısı politikası kullanabileceğiniz birçok senaryo vardır. Örneğin, coğrafi konum verileri, müşteri yorumları, iş ortağının perakende kataloğundaki öğeler vb. göndermek amacıyla harici bir hizmete çağrı yapacak şekilde bir API proxy'si yapılandırabilirsiniz.

Ek bilgi genellikle diğer iki politikayla kullanılır: Mesaj Ata ve Değişkenleri Ayıkla.

• Request (İstek): Mesaj Ata, uzak hizmete gönderilen istek mesajını doldurur.

• Yanıt: Değişkenleri Ayıkla, yanıtı ayrıştırır ve belirli içeriği çıkarır.

Hizmet Çağrısı politikalarının tipik yapısı şunlardır:

1. Mesaj Politikası Atayın: Bir istek mesajı oluşturur, HTTP üstbilgilerini, sorgu parametrelerini doldurur, HTTP fiilini ayarlar vb.
2. Hizmet Çağrısı politikası: Mesaj Ata politikası tarafından oluşturulan bir mesaja referans verir, harici çağrı için bir hedef URL tanımlar ve hedef hizmetin döndürdüğü yanıt nesnesi için bir ad tanımlar.
   
   Performansı artırmak için Hizmet Çağrısı yanıtlarını da şu Apigee Topluluğu iş parçacığında açıklandığı gibi önbelleğe alabilirsiniz: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
3. Değişkenleri Ayıklama politikası: Genellikle Hizmet Çağrısı tarafından oluşturulan mesajı ayrıştıran bir JSONPath veya XPath ifadesi tanımlar. Politika daha sonra Hizmet Çağrısı yanıtından ayrıştırılan değerleri içeren değişkenleri ayarlar.

Hizmet Çağrısı politikasını kullanan tam bir örnek API proxy'si için Mesaj Ata ve Değişken Ayıklama politikalarıyla birlikte Politika bileşimini kullanma bölümüne bakın.

Özel hata işleme

Öğe referansı

Bu politikada yapılandırabileceğiniz öğeler ve özellikler aşağıda verilmiştir:

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

<ServiceDescription> özellikleri

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

Aşağıdaki tabloda, tüm politika üst öğelerinde ortak olan özellikler açıklanmaktadır:

<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>

<Request> öğesi

API proxy'sinden diğer hizmete gönderilen istek mesajını içeren değişkeni belirtir. Değişken, akışta daha önceki bir politika tarafından veya Hizmet Çağrı Politikası politikasında satır içinde oluşturulabilir.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

<Kaldır>, <Kopyala>, <Ekle> ve <Ayarla> etiketlerinin söz dizimi, Mesaj Ata politikası ile aynıdır.

İstek mesajı çözümlenemezse veya geçersiz bir istek mesajı türüne sahipse politika hata döndürür.

En basit örnekte, API proxy'sinin akışında daha önce doldurulan istek mesajını içeren bir değişken geçirirsiniz:

<Request clearPayload="true" variable="myRequest"/>

Alternatif olarak, harici hizmete gönderilen istek mesajını Hizmet Açıklama Metni Politikası'nda da doldurabilirsiniz:

<Request>
  <Set>
    <Headers>
      <Header name="Accept">application/json</Header>
    </Headers>
    <Verb>POST</Verb>
    <Payload contentType="application/json">{"message":"my test message"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>

Özellikler

<Request>/<ignoreUnresolvedVariables> öğesi

true (doğru) değerine ayarlandığında politika, istekteki çözümlenmemiş değişken hatalarını yok sayar.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request> 

<Response> öğesi

API proxy mantığı, daha fazla işlem için uzak çağrıdan yanıt verilmesi gerektiğinde bu öğeyi ekleyin.

Bu öğe mevcut olduğunda, harici hizmetten alınan yanıt mesajını içerecek değişkenin adını belirtir. Hedeften gelen yanıt, yalnızca yanıtın tamamı politika tarafından başarıyla okunduğunda değişkene atanır. Uzak çağrı herhangi bir nedenle başarısız olursa politika bir hata döndürür.

Bu öğe atlanırsa API proxy'si yanıt beklemez. API Proxy akışı yürütme işlemi, sonraki tüm akış adımlarıyla devam eder. Ayrıca, bariz olanı Response öğesi olmadan belirtmek gerekirse hedeften gelen yanıt sonraki adımlarda işlenmeye uygun değildir ve proxy akışının uzak çağrıdaki bir hatayı algılaması mümkün değildir. ServiceCall'u kullanırken mesajları harici bir sisteme günlüğe kaydetmek amacıyla Response öğesinin atlanması için yaygın olarak kullanılan bir uygulama.

 <Response>calloutResponse</Response> 

<Timeout> öğesi

Hizmet Açıklama Metni politikasının hedeften yanıt almak için bekleyeceği milisaniye cinsinden süredir. Bu değeri çalışma zamanında dinamik olarak ayarlayamazsınız. Hizmet Çağrısı zaman aşımına uğrarsa bir HTTP 500 döndürülür, politika başarısız olur ve API proxy'si, Hataları işleme bölümünde açıklandığı gibi hata durumuna geçer.

<Timeout>30000</Timeout>

<HTTPTargetConnection> öğesi

URL, TLS/SSL ve HTTP özellikleri gibi aktarım ayrıntılarını sağlar. <TargetEndpoint> yapılandırma referansına bakın.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>

<HTTPTargetConnection>/<URL> öğesi

Çağrılan hizmetin URL'si:

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>

URL'nin bir kısmını bir değişkenle dinamik olarak sağlayabilirsiniz. Ancak, URL'nin protokol kısmı (aşağıdaki http://) bir değişken tarafından belirtilemez. Sonraki örnekte, sorgu parametresinin değerini belirtmek için bir değişken kullanacaksınız:

<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>

Alternatif olarak, URL yolunun bir kısmını değişkenle de ayarlayabilirsiniz:

<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>

URL'nin alan adını ve bağlantı noktasını belirtmek için bir değişken kullanmak istiyorsanız yalnızca alan adı ve bağlantı noktası için bir değişken ve URL'nin diğer herhangi bir bölümü için ikinci bir değişken kullanın:

<URL>http://{request.dom_port}/{request.resourcePath}</URL>

<HTTPTargetConnection>/<SSLInfo> öğesi

Arka uç hizmetinde TLS/SSL yapılandırması. TLS/SSL yapılandırmasıyla ilgili yardım almak için API proxy yapılandırma referansı bölümündeki Uçtan arka uca TLS'yi yapılandırma (Cloud ve Private Cloud) ve "TLS/SSL TargetEndpoint Configuration" (TLS/SSL Hedef Uç Yapılandırması) bölümlerine bakın.

<HTTPTargetConnection>
    <URL>https://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://mykeystoreref</KeyStore>  ## Use of a reference is recommended
        <KeyAlias>myKey</KeyAlias>
        <TrustStore>myTruststore</TrustStore>
        <Ciphers/>
        <Protocols/>
    </SSLInfo>
</HTTPTargetConnection>

Arka uç hizmetine HTTP aktarma özellikleri. Daha fazla bilgi için Uç nokta özellikleri referansı başlıklı makaleyi inceleyin.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <Properties>
        <Property name="allow.http10">true</Property>
        <Property name="request.retain.headers">
          User-Agent,Referer,Accept-Language
        </Property>
    </Properties>
</HTTPTargetConnection>

<HTTPTargetConnection>/<LoadBalancer> öğesi

Bir veya daha fazla hedef sunucuyu çağırın ve bunlar üzerinde yük dengeleme yapın. Sana Özel bölümündeki Arama hedef sunucuları örneğine bakın. Arka uç sunucuları arasında yük dengeleme bölümünü de inceleyin. Ayrıca, Hizmet Açıklaması politikasından ve Rota Kurallarını kullanarak hedef sunucuları çağırma yöntemlerini açıklayan bu topluluk gönderisine de göz atın.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>

<LocalTargetConnection> öğesi

Hizmet açıklama metinlerinin hedefi olarak yerel bir proxy'yi (yani aynı kuruluş ve ortamdaki bir proxy) belirtir.

Hedefi daha ayrıntılı belirtmek için <APIProxy> ve <ProxyEndpoint> öğelerini veya <Path> öğesini kullanın.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>

<LocalTargetConnection>/<APIProxy> öğesi

Yerel çağrının hedefi olan bir API proxy'sinin adı. Proxy, çağrıyı yapan proxy ile aynı kuruluş ve ortamda olmalıdır.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

Çağrı için hedeflenmesi gereken proxy uç noktasının adını belirtmek için <APIProxy> öğesiyle birlikte <ProxyEndpoint> öğesini ekleyin.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection> 

<LocalTargetConnection>/<ProxyEndpoint> öğesi

Çağrıların hedefi olması gereken proxy uç noktasının adı. Bu, <APIProxy> öğesiyle belirtilen API proxy'sindeki bir proxy uç noktasıdır.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

<LocalTargetConnection>/<Path> öğesi

Hedeflenen uç noktaya giden bir yol. Uç nokta, çağrıyı yapan proxy ile aynı kuruluş ve ortamdaki bir proxy'ye başvuruda bulunmalıdır.

Proxy adını bilmediğinizde veya güvenemediğinizde <APIProxy>/<ProxyEndpoint> çifti yerine bunu kullanın. Yol, güvenilir bir hedef olabilir.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>

Şemalar

Akış değişkenleri

Akış değişkenleri, HTTP üstbilgileri, mesaj içeriği veya Akış bağlamına göre çalışma zamanında politikaların ve Akışların dinamik davranışını etkinleştirir. Aşağıdaki önceden tanımlanmış Akış değişkenleri, bir Hizmet Çağrı Politikası politikası yürütüldükten sonra kullanılabilir. Akış değişkenleri hakkında daha fazla bilgi için Değişkenler referansı başlıklı makaleyi inceleyin.

Hizmet Açıklama metinlerinin kendi isteği ve yanıtı vardır. Bu verilere değişkenler aracılığıyla erişebilirsiniz. Ana mesaj, request.* ve response.* değişken öneklerini kullandığından Hizmet Açıklama Metni'ne özel mesaj verilerini almak için myrequest.* ve calloutResponse.* öneklerini (Hizmet Açıklama Metni yapılandırmasındaki varsayılanlar) kullanın. Aşağıdaki tablodaki ilk örnekte, hizmet açıklama metninde HTTP üst bilgilerini nasıl alacağınız gösterilmektedir.

Hatalar

Bu bölümde, bu politika bir hatayı tetiklediğinde Edge tarafından ayarlanan hata kodları ile hata mesajları ve döndürülen hata mesajları ile Edge tarafından ayarlanan hata değişkenleri açıklanmaktadır. Bu bilgiyi, hataları ele almak için hata kuralları geliştirip geliştirmediğinizi bilmeniz ö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.

Dağıtım hataları

Bu hatalar, bu politikayı içeren bir proxy dağıttığınızda ortaya çıkabilir.

Hata değişkenleri

Bu değişkenler, bir çalışma zamanı hatası oluştuğunda ayarlanır. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler bölümüne bakın.

Örnek hata yanıtı

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: 
            request variable data_str value is not of type Message"
   }
}

Hata kuralı örneği

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

İlgili konular

• Mesaj oluşturma veya değiştirme: Mesaj politikası atama
• Değişkenleri ayıklama: Değişkenleri Ayıklama politikası
• Değişkenler: Değişkenler referansı
• TLS/SSL yapılandırması
  • Uç'tan arka uca TLS'yi yapılandırma (Cloud ve Private Cloud)
  • API proxy yapılandırma referansı "TLS/SSL TargetEndpoint Configuration" (TLS/SSL Hedef Uç Nokta Yapılandırması)
• HTTP aktarımı özellikleri: Uç nokta özellikleri referansı
• Hizmet Açıklaması'na alternatif: JavaScript'te yazılmış HTTPClient. JavaScript nesne modeli sayfasını inceleyin.