Hizmet çağrısı politikası

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

Ne?

Hizmet Çağrısı politikası, API proxy akışınızdan başka bir hizmete çağrı göndermenizi sağlar. Harici bir hizmete (ör. harici bir RESTful hizmet uç noktası) veya dahili hizmetlere (ör. aynı kuruluş ve ortamdaki bir API proxy'si) çağrı yapabilirsiniz.

• Harici bir kullanım alanında, proxy'nizin dışında olan bir üçüncü taraf API'sine çağrı yaparsınız. Üçüncü taraf API'sinden 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 "birleştirilir". Ayrıca, istek akışında Service Callout politikasını kullanarak istekte bulunabilir, ardından yanıttaki bilgileri API proxy'sinin TargetEndpoint'ine iletebilirsiniz.
• Başka bir kullanım alanında, arama yaptığınız yerle aynı kuruluşta ve ortamda bulunan bir proxy'yi ararsınız. Örneğin, bir veya daha fazla başka proxy'nin kullanacağı bazı ayrı düşük düzeyli işlevler sunan bir proxy'niz olduğunda bu işlevden yararlanabilirsiniz. Örneğin, arka uç veri deposuyla oluşturma/okuma/güncelleme/silme işlemlerini kullanıma sunan bir proxy, verileri istemcilere sunan diğer birç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 açıklama 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. sunmak için harici bir hizmete çağrı yapacak şekilde bir API proxy'si yapılandırabilirsiniz.

Açıklama genellikle diğer iki politikayla birlikte kullanılır: İleti Atama ve Değişkenleri Çıkarma.

• İstek: Assign Message (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çerikleri ayıklar.

Tipik bir hizmet açıklama metni politikası şunları içerir:

1. Assign Message policy: İstek mesajı oluşturur, HTTP başlıklarını ve sorgu parametrelerini doldurur, HTTP fiilini ayarlar vb.
2. Service Callout (Hizmet Çağrısı) politikası: Assign Message (Mesaj Atama) 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 bu Apigee Topluluğu ileti dizisinde açıklandığı gibi hizmet açıklama metni yanıtlarını da önbelleğe alabilirsiniz: How can I store the results of the ServiceCallout policy in cache and later retrieve it from cache? (ServiceCallout politikasının sonuçlarını nasıl önbellekte saklayabilir ve daha sonra önbellekten nasıl alabilirim?)
3. Değişkenleri Ayıklama politikası: Genellikle, Service Callout tarafından oluşturulan mesajı ayrıştıran bir JSONPath veya XPath ifadesini tanımlar. Ardından politika, hizmet çağrısı yanıtından ayrıştırılan değerleri içeren değişkenleri ayarlar.

Assign Message ve Extract Variables politikalarıyla birlikte Service Callout politikasını kullanan eksiksiz bir örnek API proxy'si için 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>

<ServiceCallout> ö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:

&lt;DisplayName&gt; öğe

Politikayı name özelliğine ek olarak farklı bir doğal dil adına sahip yönetim arayüzü proxy düzenleyicisi.

<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 oluşturulabilir veya değişkeni Hizmet Çağrısı politikasında satır içi olarak oluşturabilirsiniz.

<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, Assign Message politikasıyla aynıdır.

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

En basit örnekte, API proxy'sinin akışında daha önce doldurulmuş olan istek mesajını içeren bir değişkeni iletiyorsunuz:

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

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

Doğru olarak ayarlandığında politika, istekteki çözümlenmemiş değişken hatalarını yoksayar.

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

<Response> öğesi

API proxy mantığı, uzaktan yapılan çağrıdan gelen yanıtın daha fazla işlenmesini gerektirdiğ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. Hedefin yanıtı, yalnızca yanıtın tamamı politika tarafından başarıyla okunduğunda değişkene atanır. Uzak arama herhangi bir nedenle başarısız olursa politika hata döndürür.

Bu öğe atlanırsa API proxy'si yanıt beklemez. API proxy akışı yürütme, sonraki akış adımlarıyla devam eder. Ayrıca, açıkça belirtmek gerekirse Response öğesi olmadan hedeften gelen yanıt, sonraki adımlar tarafından işlenemez ve proxy akışının uzak çağrıda bir hata algılaması mümkün değildir. ServiceCallout kullanılırken Response öğesinin atlanmasının yaygın bir kullanım alanı: iletileri harici bir sisteme kaydetmek.

 <Response>calloutResponse</Response>

<Timeout> öğesi

Hizmet Çağrısı politikasının hedefinden yanıt bekleyeceği süre (milisaniye cinsinden). Bu değeri çalışma zamanında dinamik olarak ayarlayamazsınız. Hizmet çağrısı zaman aşımına uğrarsa Hataları işleme bölümünde açıklandığı gibi HTTP 500 döndürülür, politika başarısız olur ve API proxy'si 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 bölümünü değişkenle dinamik olarak sağlayabilirsiniz. Ancak URL'nin protokol kısmı (aşağıdaki http://) bir değişkenle belirtilemez. Sonraki örnekte, bir sorgu parametresinin değerini belirtmek için değişken kullanıyorsunuz:

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

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

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

<HTTPTargetConnection>/<SSLInfo> öğesi

Arka uç hizmeti için TLS/SSL yapılandırması. TLS/SSL yapılandırmasıyla ilgili yardım için Uçtan arka uca (Cloud ve Private Cloud) TLS yapılandırma ve API proxy yapılandırma referansı'ndaki "TLS/SSL TargetEndpoint Yapılandırması" bölümüne 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ı 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. Örnekler bölümündeki Hedef sunucuları arama örneğini inceleyin. Ayrıca Arka uç sunucularında yük dengeleme başlıklı makaleye de bakın. Ayrıca, hem hizmet çağrısı politikasından hem de rota kuralları kullanılarak hedef sunucuların nasıl çağrılacağını 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ğrılarının hedefi olarak yerel bir proxy'yi (aynı kuruluş ve ortamdaki bir proxy) belirtir.

Hedefi daha ayrıntılı olarak belirtmek için <APIProxy> ve <ProxyEndpoint> öğelerini ya da <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, aramayı yapan proxy ile aynı kuruluşta ve ortamda olmalıdır.

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

<APIProxy> öğesinin yanı sıra, çağrı için hedeflenmesi gereken proxy uç noktasının adını belirtmek üzere <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 yol. Uç nokta, çağrıyı yapan proxy ile aynı kuruluştaki ve ortamdaki bir proxy'yi referans almalıdır.

Proxy adını bilmiyorsanız veya proxy adına güvenemiyorsanız <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 üstbilgilerine, ileti içeriğine veya akış bağlamına göre politikaların ve akışların çalışma zamanında dinamik davranışını sağlar. 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şken referansı başlıklı makaleyi inceleyin.

Hizmet açıklama metinlerinin kendi istek ve yanıtları vardır ve bu verilere değişkenler aracılığıyla erişebilirsiniz. Ana mesajda request.* ve response.* değişken önekleri kullanıldığından, hizmet açıklama metnine ö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 üstbilgilerinin nasıl alınacağı gösterilmektedir.

Hatalar

Bu bölümde, bu politika bir hatayı tetiklediğinde döndürülen hata kodları ve hata mesajlarının yanı sıra Edge tarafından ayarlanan hata değişkenleri açıklanmaktadır. Hata kuralları geliştirirken bu bilgilerin farkında olmanız önemlidir. hoşuma gitmesi için bir fırsattır. Daha fazla bilgi için Bilmeniz gerekenler Politika hataları ve Kullanım sorun.

Çalışma zamanı hataları

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

Dağıtım hataları

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

Hata değişkenleri

Bu değişkenler, çalışma zamanı hatası oluştuğunda ayarlanır. Daha fazla bilgi için Bilmeniz gerekenler hakkında daha fazla bilgi edinin.

Ö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ı 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 (Cloud ve Private Cloud) TLS'yi yapılandırma
  • API proxy'si yapılandırma referansındaki "TLS/SSL TargetEndpoint Yapılandırması"
• HTTP taşıma özellikleri: Uç nokta özellikleri referansı
• Hizmet Çağrısına Alternatif: JavaScript ile yazılmış HTTPClient, bkz. JavaScript nesne modeli