Hizmet çağrısı politikası

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

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'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 "birleştirilir". Ayrıca, istek akışında Hizmet Çağrısı politikasını kullanarak bir 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ş 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şlevi yararlı bulabilirsiniz. Ö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'nin hedef proxy'si 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ı gönderecek şekilde bir API proxy'si yapılandırabilirsiniz.

Açıklama metni 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 hizmet açıklama metni politikası bileşimi şunları içerir:

1. Assign Message policy: İstek mesajı oluşturur, HTTP üstbilgilerini 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: Hizmet açıklama metni politikasının sonuçlarını önbellekte nasıl saklayabilirim ve daha sonra önbellekten nasıl alabilirim?
3. Değişkenleri Çıkarma politikası: Genellikle, Hizmet Çağrısı 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ı ile 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ığı, daha fazla işlem için uzak çağrıdan yanıt 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'si akışının yürütülmesi, 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 hedeften 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ı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 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ı" başlıklı makaleyi inceleyin.

<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 taşıma ö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 bu sunucularda 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, bu topluluk gönderisinde hem hizmet çağrısı politikasından hem de rota kuralları kullanılarak hedef sunucuların nasıl çağrılacağı açıklanmaktadır.

<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, çağrıyı 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ş 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ış Flow 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ı başlıklı makaleyi inceleyin.

Hizmet açıklama metinlerinin kendi istek ve yanıtları vardır. 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 üstbilgilerini nasıl alacağınız 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 yapılandırma
  • API proxy'si yapılandırma referansındaki "TLS/SSL TargetEndpoint Yapılandırması"
• HTTP aktarım özellikleri: Uç nokta özellikleri referansı
• Hizmet Çağrısı Alternatifi: JavaScript ile yazılmış HTTPClient, bkz. JavaScript nesne modeli