Hizmet çağrısı politikası

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

Ne

Hizmet Açıklama Metni 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 (ör. aynı kuruluş ve ortamdaki bir API proxy'si) çağrı yapabilirsiniz.

• Harici bir kullanım alanında, proxy'nizin dışındaki bir üçüncü taraf API'ye açıklama metni oluşturursunuz. Üçü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 Hedef Uç Noktası'na 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 kullanacağı ayrı alt düzey işlevler sunan bir proxy'niz olduğunda bunu faydalı 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'nin hedef proxy'si olabilir.

Politika, HTTP ve HTTPS üzerinden 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. yayınlamak için harici bir hizmete çağrı yapmak amacıyla bir API proxy'si yapılandırabilirsiniz.

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

• İstek: Mesaj ata, uzak hizmete gönderilen istek mesajını doldurur.

• Yanıt: Değişkenleri Çıkar seçeneği, yanıtı ayrıştırır ve belirli içeriği ayıklar.

Tipik Hizmet Çağrısı politika bileşimi şunları içerir:

1. Mesaj Politikası Atayın: Bir istek mesajı oluşturur, HTTP üstbilgilerini, sorgu parametrelerini doldurur, HTTP fiilini vb. ayarlar.
2. Hizmet Açıklama Metni 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.
   
   Daha iyi performans için şu Apigee Topluluğu iş parçacığında açıklandığı gibi Hizmet Açıklama Metni yanıtlarını da ö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çıklama Metni politikasını kullanan eksiksiz bir API proxy'si için Mesaj Atayın ve Değişkenleri Ayıklayın politikaları ile 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 belirtilmiş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 yaygın olarak kullanılan özellikler açıklanmaktadır:

<DisplayName> öğesi

Yönetim kullanıcı arayüzü proxy'sinde politikayı 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ıştaki önceki bir politika tarafından veya Hizmet Çağrısı politikasında satır içi olarak 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>

<Remove>, <Copy>, <Add> ve <Set> etiketlerinin söz dizimi, İleti 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 iletirsiniz:

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

Alternatif olarak, harici hizmete gönderilen istek mesajını Hizmet Çağrısı politikasının kendisinde de 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

Politika, true değerine ayarlandığında istekteki tüm çözümlenmemiş değişken hatalarını yoksayar.

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

<Response> öğesi

API proxy mantığının daha fazla işlem için uzak çağrıdan yanıt alması 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ışının yürütülmesi, sonraki tüm akış adımlarıyla devam eder. Ayrıca, bariz bir bilgiyi Response öğesi olmadan belirtmek gerekirse, hedeften gelen yanıt sonraki adımlarla işlenemez ve proxy akışının uzak çağrıda bir hata algılaması mümkün değildir. Mesajları harici bir sisteme günlüğe kaydetmek için ServiceDescription kullanılırken Response öğesinin atlanması için yaygın bir kullanımdır.

 <Response>calloutResponse</Response> 

<Timeout> öğesi

Hizmet Açıklama Metni politikasının hedeften yanıt 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 bir hata durumuna girer.

<Timeout>30000</Timeout>

<HTTPTargetConnection> öğesi

URL, TLS/SSL ve HTTP özellikleri gibi aktarım ayrıntıları 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ı 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 değişken kullanıyorsunuz:

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

Veya URL yolunun bir kısmını değişkenle ayarlayın:

<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 ve bağlantı noktası için bir değişken, URL'nin diğer tüm bölümü için ise ikinci bir değişken kullanın:

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

<HTTPTargetConnection>/<SSLInfo> öğesi

Arka uç hizmetine TLS/SSL yapılandırması. TLS/SSL yapılandırmasıyla ilgili yardım almak için API proxy yapılandırması referansı bölümündeki Edge'den arka uca TLS'yi yapılandırma (Cloud ve Private Cloud) ve "TLS/SSL TargetEndpoint Configuration" (TLS/SSL TargetEndpoint 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 aktarım özellikleri. Daha fazla bilgi için Uç nokta özellikleri referansı bölümüne bakın.

<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çıklama metni politikasından ve Rota Kurallarını kullanarak hedef sunucuları çağırma yöntemlerini ele alan bu topluluk yayınına da 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 bir yerel proxy'yi (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'sinde bulunan 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 ortamda bulunan bir proxy'ye başvuruda bulunmalıdır.

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

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

Şemalar

Akış değişkenleri

Akış değişkenleri, çalışma zamanında politikaların ve Akışların HTTP üstbilgilerine, mesaj içeriğine veya Akış içeriğine göre dinamik davranışını etkinleştirir. Aşağıdaki önceden tanımlanmış Akış değişkenleri, bir Hizmet Çağrısı politikası yürütüldükten sonra kullanılabilir. Akış değişkenleri hakkında daha fazla bilgi için Değişkenler referansı bölümüne bakın.

Hizmet çağrılarının kendi istekleri ve yanıtları 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ğrısı'nda HTTP üst bilgilerini nasıl alacağınız gösterilmektedir.

Hatalar

Bu bölümde, döndürülen hata kodları ve hata mesajları ile bu politika bir hatayı tetiklediğinde Edge tarafından ayarlanan hata değişkenleri açıklanmaktadır. Bu bilgiler, hataları ele alacak hata kuralları geliştirip geliştirmediğinizi bilmeniz önemlidir. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler ve Hataları işleme hakkında bilgi edinin.

Çalışma zamanı hataları

Bu hatalar, politika yürütüldüğünde ortaya çıkabilir.

Dağıtım hataları

Bu hatalar, bu politikayı içeren bir proxy dağıttığınızda oluşabilir.

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

Örnek hata kuralı

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

İlgili konular

• İleti oluşturma veya değiştirme: İleti politikası atayın
• Değişkenleri ayıklama: Değişkenleri Çıkarma politikası
• Değişkenler: Değişkenler referansı
• TLS/SSL yapılandırması
  • TLS'yi uçtan arka uca yapılandırma (Cloud ve Private Cloud)
  • API proxy yapılandırma referansı bölümündeki "TLS/SSL TargetEndpoint Configuration" (TLS/SSL TargetEndpoint Yapılandırması)
• HTTP aktarımı özellikleri: Uç nokta özellikleri referansı
• Hizmet Açıklama Metnine alternatif: JavaScript'te yazılmış HTTPClient için JavaScript nesne modeli bölümüne bakın