Hizmet çağrısı politikası

Apigee Edge belgelerini görüntülüyorsunuz.
. Git: Apigee X belgeleri. bilgi

Ne?

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

• Harici bir kullanım örneğinde, temsil eder. Üçüncü taraf API'nin yanıtı ayrıştırılır ve API'nizin yanıtına eklenir mesaj, zenginleştirme ve "birleştirme" uygulama son kullanıcıları için veriler. Ayrıca isterseniz istek akışında Hizmet Çağrısı politikasını kullanarak, ardından bilgileri yanıtta ileterek API proxy'sinin TargetEndpoint'ine bağlayın.
• Başka bir kullanım örneğinde de ondan çok şey var. Örneğin, aynı dili kullanan bir proxy'niz olduğunda bunu bir veya daha fazla proxy'nin yararlanacağı bazı ayrı alt düzey işlevler sunar. Örneğin, örnek olarak, arka uç veri deposuyla oluşturma/okuma/güncelleme/silme işlemlerini sunan bir proxy verileri istemcilere gösteren diğer birç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 açıklama metni politikası hakkında

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

Açıklama metni genellikle diğer iki politikayla birlikte kullanılır: Mesaj Atama ve Değişkenleri Çıkar.

• İstek: "Mesaj Ata" seçeneği, uzaktan kumandaya gönderilen istek mesajını doldurur. geliştirmenizi sağlar.

• Yanıt: Değişkenleri Ayıklama, yanıtı ayrıştırır ve belirli içerik.

Tipik Hizmet Çağrısı Politikası yapısında şunlar bulunur:

1. Mesaj Ata policy: Bir istek mesajı oluşturur, HTTP üstbilgilerini, sorgu parametrelerini doldurur, HTTP fiil vb.
2. Hizmet Açıklama Metni politikası: "İleti Ata" tarafından oluşturulan bir iletiye politika, harici çağrı için bir hedef URL ve yanıt nesnesi için bir ad tanımlar geri döndüğü anlamına gelir.
   .
   . Daha iyi performans için Hizmet Çağrısı yanıtlarını bu Apigee Topluluğu ileti dizisi: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
3. Değişkenleri Ayıklayın politika: Genellikle oluşturulan mesajı ayrıştıran bir JSONPath veya XPath ifadesi tanımlar (Hizmet Çağrı Çağrısı tarafından) Ardından politika, Hizmet açıklama metni yanıtı.

Bkz. Politika kullanma bileşimi. İleti Ata ve Değişkenleri Ayıklama politikaları.

Ö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> özellikler

<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> öğ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> öğe

API proxy'sinden başka bir hizmetten yararlanın. Değişken, akıştaki önceki bir politika tarafından ya da kendiniz oluşturulabilir. satır içi olarak ayarlayın.

<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 Mesaj Ata politikası hakkında daha fazla bilgi edinin.

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

En basit örnekte, gönderdiğiniz istek mesajını içeren bir değişken ile şu adımları izleyin:

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

Dilerseniz 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

&lt;Request&gt;/&lt;IgnoreUnresolvedVariables&gt; öğe

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

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

&lt;Response&gt; öğe

API proxy mantığı mantığı için uzak çağrının yanıtı gerektiğinde bu öğeyi dahil et: devam edebilir.

Bu öğe mevcut olduğunda, yanıt iletisi almalısınız. Hedeften gelen yanıt, değişkeni yalnızca yanıtın tamamı politika tarafından başarıyla okunduğunda yapılır. Uzak çağrı herhangi bir nedenle başarısız olursa politika bir hata döndürür.

Bu öğe eklenmezse API proxy'si bir yanıt beklemez. API Proxy akışı sonraki akış adımlarıyla devam eder. Ayrıca, açıkça belirtmek gerekirse Response öğesi olursa hedeften gelen yanıt tarafından işlenemez. ve proxy akışının uzak çağrıdaki bir hatayı algılaması mümkün değildir. ServiceCondition kullanılırken Response öğesinin atlanması için genel bir kullanım: günlüğe kaydetmek harici bir sisteme gönderebilirsiniz.

 <Response>calloutResponse</Response> 

<Zaman Aşımı> öğe

Hizmet Çağrısı politikasının, hedefi belirleyebilirsiniz. Çalışma zamanında bu değeri dinamik olarak ayarlayamazsınız. Hizmet Çağrısı zaman aşımına uğrarsa HTTP 500 döndürülür, politika başarısız olur ve API proxy'si aşağıdaki şekilde hata durumuna geçer: Hataları işleme bölümünde açıklanmıştır.

<Timeout>30000</Timeout>

&lt;HTTPTargetConnection&gt; öğe

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

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

&lt;HTTPTargetConnection&gt;/&lt;URL&gt; öğe

Çağrılan hizmetin URL'si:

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

URL'nin bir bölümünü dinamik olarak bir değişkenle sağlayabilirsiniz. Ancak, aşağıdaki http:// URL'si bir değişkenle belirtilir. Sonraki örnekte, bir sorgunun değerini belirtmek için değişken parametresi:

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

Alternatif olarak, URL yolunun bir kısmını değişkenle 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 değişken kullanmak istiyorsanız tek bir değişken kullanın hem alan adı hem de bağlantı noktası için, URL'nin diğer herhangi bir bölümü için ikinci bir değişken:

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

&lt;HTTPTargetConnection&gt;/&lt;SSLInfo&gt; öğe

Arka uç hizmetine TLS/SSL yapılandırması. TLS/SSL yapılandırmasıyla ilgili yardım için bkz. TLS'yi Yapılandırma uçtan uca (Cloud ve Private Cloud) ve "TLS/SSL Hedef Uç Nokta Yapılandırması" API proxy yapılandırma referansı.

<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 bkz. Uç nokta özellikleri referansı.

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

&lt;HTTPTargetConnection&gt;/&lt;LoadBalancer&gt; öğe

Bir veya daha fazla hedef sunucuyu çağırın ve bu sunucularda yük dengeleme işlemi yapın. Bkz. Arama hedefi sunucuları örneğiyle ilgili bilgileri Sana Özel bölümünde bulabilirsiniz. Ayrıca bkz. Arka uç genelinde yük dengeleme tıklayın. Ayrıca bu topluluğa bakın hem Hizmet Çağrısı politikasındaki hem de hedef sunucuları çağırma yöntemlerinin ele alındığı, nasıl kullanacağınızı göstereceğim.

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

&lt;LocalTargetConnection&gt; öğe

Web sunucunuzla aynı kuruluş ve ortamda bulunan bir proxy'yi hizmet açıklama metinlerinin hedefidir.

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

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

&lt;LocalTargetConnection&gt;/&lt;APIProxy&gt; öğe

Yerel bir çağrının hedefi olan API proxy'sinin adı. Proxy değeri aynı olmalıdır çevreyi ve organizasyonu temsil eder.

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

<APIProxy> öğesiyle birlikte kullanılması gereken proxy uç noktasının adını belirten <ProxyEndpoint> öğesi görüşmenin hedeflenmesine izin vermelidir.

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

&lt;LocalTargetConnection&gt;/&lt;ProxyEndpoint&gt; öğe

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

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

&lt;LocalTargetConnection&gt;/&lt;Path&gt; öğe

Hedeflenen uç noktanın yolu. Uç nokta, aynı çevreyi ve organizasyonu temsil eder.

Kullanmadığınızda <APIProxy>/<ProxyEndpoint> çifti yerine bunu kullanın proxy adını bilir veya bunlara güvenemez. Yol, güvenilir bir hedef olabilir.

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

Şemalar

Akış değişkenleri

Akış değişkenleri, politikaların ve Akışların çalışma zamanında HTTP'ye göre dinamik davranışını etkinleştirir üstbilgileri, ileti içeriğini veya Akış bağlamını yansıtabilir. Aşağıdaki önceden tanımlanmış Akış değişkenleri kullanılabilir Hizmet Çağrısı politikası yürütüldükten sonra. 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 isteği ve yanıtı vardır. Bu verilere değişkenlerine karşılık gelir. Çünkü ana mesajda request.* ve response.* değişken önekleri için, myrequest.* ve calloutResponse.* ön eklerini (Hizmet Çağrısı yapılandırmasındaki varsayılanlar) Hizmet Çağrısına özel mesaj verileri almak. Aşağıdaki tabloda yer alan ilk örnek, Hizmet Çağrısı'nda HTTP üstbilgilerini nasıl alacağınızı öğrenebilirsiniz.

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ıklayın: Değişkenleri Ayıklayın politika
• Değişkenler: Değişkenler referans
• TLS/SSL yapılandırması
  • Yapılandırma Uçtan arka uca TLS (Bulut ve Private Cloud)
  • "TLS/SSL Hedef Uç Nokta Yapılandırması" API proxy yapılandırma referansı'nda
• HTTP aktarım özellikleri: Uç nokta özellikleri referansı
• Hizmet Çağrısına Alternatif: JavaScript'te yazılmış HTTPClient, bkz. JavaScript nesne modeli