Zasady dotyczące objaśnień dotyczących usług

Przeglądasz dokumentację Apigee Edge.
Przejdź do Dokumentacja Apigee X. informacje.

Co

Zasada objaśnień dotyczących usługi umożliwia wywoływanie innej usługi z poziomu procesu serwera proxy interfejsu API. Ty może wysyłać wywołania do usługi zewnętrznej (takiej jak zewnętrzny punkt końcowy usługi REST) lub usług wewnętrznych (takich jak serwer proxy interfejsu API w tej samej organizacji i środowisku).

• W zewnętrznym przypadku użycia wykonujesz wywołanie interfejsu API innej firmy, który jest zewnętrzny w stosunku do Twojego serwera proxy. Odpowiedź z interfejsu API innej firmy jest analizowana i umieszczana w odpowiedzi interfejsu API przekazem, wzbogacającym i „łączonym” z zastosowaniem danych dla użytkowników aplikacji. Możesz też poprosić o nie używając w procesie żądania wywołań usługi, a następnie przekaż informacje w odpowiedzi do punktu docelowego punktu końcowego interfejsu API serwera proxy.
• W innym przypadku należy wywołać serwer proxy z tej samej organizacji i środowiska co ten, z którego dzwonisz. Może Ci się to przydać, jeśli masz serwer proxy, który oferuje pewne dyskretne funkcje niskiego poziomu, z których będzie korzystać jeden lub więcej innych serwerów proxy. Dla: na przykład serwer proxy, który udostępnia operacje tworzenia, odczytu, aktualizacji i usuwania przy użyciu magazynu danych backendu może być docelowym serwerem proxy dla wielu innych serwerów proxy, które udostępniają dane klientom.

Ta zasada obsługuje żądania przez HTTP i HTTPS.

Próbki

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

Zasady dotyczące objaśnień dotyczących usługi

Jest wiele sytuacji, w których możesz używać zasad objaśnień dotyczących usługi na serwerze proxy interfejsu API. Dla: można na przykład skonfigurować serwer proxy interfejsu API, aby wywoływał usługę zewnętrzną w celu dostarczenia dane geolokalizacyjne, opinie klientów, produkty z katalogu handlowego partnera itp.

Objaśnienie jest zwykle używane z 2 innymi zasadami: Przypisywanie wiadomości i Wyodrębnianie zmiennych.

• Request: Assign Message (Przypisz wiadomość) wypełnia wiadomość z prośbą wysłaną do pilota posprzedażna.

• Odpowiedź: funkcja Wyodrębnianie zmiennych analizuje odpowiedź i wyodrębnia określone dane. treści.

Typowa kompozycja zasad dotyczących objaśnień dotyczących usługi obejmuje:

1. Przypisz wiadomość zasada: tworzy wiadomość żądania, wypełnia nagłówki HTTP, parametry zapytania i ustawia protokół HTTP. czasownik itd.
2. Zasady objaśnień dotyczących usługi: odwołuje się do wiadomości utworzonej przez przypisanie wiadomości. określa docelowy URL wywołania zewnętrznego oraz nazwę obiektu odpowiedzi które zwraca usługa docelowa.
   
   Aby zwiększyć wydajność, możesz też buforować odpowiedzi objaśnień usługi, jak opisano w tym Wątek społeczności Apigee: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
3. Wyodrębnij zmienne zasada: zwykle definiuje wyrażenie JSONPath lub XPath, które analizuje wygenerowaną wiadomość przez Objaśnienie dotyczące usługi. Następnie ustawia zmienne zawierające wartości przeanalizowane z Odpowiedź z objaśnieniem dotyczącym usługi.

Zobacz Korzystanie z zasad kompozycja, aby uzyskać kompletny przykładowy serwer proxy interfejsu API, który korzysta z zasady objaśnienia usługi wraz z zasady „Przypisywanie wiadomości i wyodrębnianie zmiennych”.

Niestandardowa obsługa błędów

Odwołanie do elementu

Oto elementy i atrybuty, które możesz skonfigurować w tej zasadzie:

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

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

W tej tabeli opisano atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:

<DisplayName> element

Używaj oprócz atrybutu name do oznaczania zasady w edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

<Request> element

Określa zmienną zawierającą żądanie, które jest wysyłane z serwera proxy interfejsu API do z inną usługą. Zmienną może zostać utworzona przez poprzednią zasadę w procesie lub możesz ją utworzyć w zasadach dotyczących wywołań usługi.

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

Składnia tagów <Remove>, <Copy>, <Add> i <Set> jest taka sama jak w przypadku tagu Przypisz wiadomość .

Zasada zwraca błąd, jeśli komunikatu z żądaniem nie można rozwiązać lub jest on nieprawidłowy typ wiadomości z prośbą.

W najprostszym przykładzie należy przekazać zmienną zawierającą treść żądania, która została wypełniona podczas przesyłania serwera proxy interfejsu API:

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

Możesz też uzupełnić wiadomość żądania wysłaną do usługi zewnętrznej w samych zasadach dotyczących objaśnień usługi:

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

Atrybuty

&lt;Request&gt;/&lt;IgnoreUnresolvedVariables&gt; element

Jeśli zasada ma wartość true, zasada ignoruje każdy nierozwiązany błąd zmiennej w żądaniu.

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

&lt;Response&gt; element

Dołącz ten element, gdy logika serwera proxy interfejsu API wymaga odpowiedzi ze zdalnego wywołania dla na dalsze przetwarzanie.

Ten element określa nazwę zmiennej, która będzie zawierać parametr wiadomość z odpowiedzią odebraną z usługi zewnętrznej. Odpowiedź ze środowiska docelowego jest przypisana do zmienną tylko wtedy, gdy cała odpowiedź zostanie poprawnie odczytana przez zasadę. Jeśli wywołanie zdalne z jakiegokolwiek powodu nie powiedzie się, zasada zwraca błąd.

Jeśli ten element zostanie pominięty, serwer proxy interfejsu API nie będzie czekać na odpowiedź. Przepływ serwera proxy interfejsu API jego działanie będzie kontynuowane w kolejnych krokach przepływu. Pamiętaj też o oczywistych kwestiach: Response, odpowiedź z celu nie może zostać przetworzona przez kolejne kroki i nie ma możliwości wykrycia przez serwer proxy awarii w wywołaniu zdalnym. Typowy sposób pomijania elementu Response podczas korzystania z objaśnienia ServiceCallout: do logowania wiadomości do systemu zewnętrznego.

 <Response>calloutResponse</Response> 

<Limit czasu> element

Czas oczekiwania (w milisekundach) na odpowiedź zasad dotyczących wywołań usługi cel. Nie można ustawić tej wartości dynamicznie w czasie działania. Jeśli objaśnienie usługi osiągnie limit czasu, zwracany jest kod HTTP 500, zasada kończy się niepowodzeniem, a serwer proxy interfejsu API przechodzi w stan błędu: opisane w sekcji Obsługa błędów.

<Timeout>30000</Timeout>

&lt;HTTPTargetConnection&gt; element

Podaje szczegóły transportu, takie jak adres URL, właściwości TLS/SSL i HTTP. Zobacz Dokumentacja konfiguracji <TargetEndpoint>.

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

&lt;HTTPTargetConnection&gt;/&lt;URL&gt; element

Adres URL wywoływanej usługi:

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

Część adresu URL możesz dostarczyć dynamicznie za pomocą zmiennej. Część protokołu adres URL, http:// poniżej, nie może zostać określony przez zmienną. W następnym przykładzie używasz zmiennej do określenia wartości zapytania :

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

Możesz też ustawić część ścieżki adresu URL za pomocą zmiennej:

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

Jeśli chcesz użyć zmiennej do określenia domeny i portu adresu URL, użyj jednej zmiennej tylko dla domeny i portu oraz drugą zmienną dla dowolnej innej części adresu URL:

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

&lt;HTTPTargetConnection&gt;/&lt;SSLInfo&gt; element

Konfiguracja TLS/SSL dla usługi backendu. Pomoc na temat konfiguracji TLS/SSL znajdziesz tutaj: Konfigurowanie TLS z Edge do backendu (chmura i chmura Private Cloud) oraz „Konfiguracja punktu końcowego TLS/SSL” w dokumentacji konfiguracji serwera proxy interfejsu API.

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

Właściwości transportu HTTP do usługi backendu. Więcej informacji: Informacje o właściwościach punktów końcowych.

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

Wywołaj co najmniej jeden serwer docelowy i skonfiguruj równoważenie obciążenia na nim. Zobacz Cel połączeń serwerów w sekcji Przykłady. Zobacz też Równoważenie obciążenia w backendzie . Zobacz też tę społeczność , w którym omawiamy sposoby wywoływania serwerów docelowych zarówno z zasad dotyczących wywołań usługi, jak i za pomocą reguł trasy.

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

&lt;LocalTargetConnection&gt; element

Określa lokalny serwer proxy – czyli serwer proxy w tej samej organizacji i środowisku – co cel objaśnień dotyczących usługi.

Aby dokładniej określić cel, użyj elementów <APIProxy> i <ProxyEndpoint> lub elementu <Path>.

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

&lt;LocalTargetConnection&gt;/&lt;APIProxy&gt; element

Nazwa serwera proxy interfejsu API, który jest miejscem docelowym wywołania lokalnego. Serwer proxy musi być w tym samym miejscu w organizacji i środowisku w roli serwera proxy wykonującego wywołanie.

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

Oprócz elementu <APIProxy> dołącz też zmienne <ProxyEndpoint> określający nazwę punktu końcowego serwera proxy, który powinien być celem połączenia.

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

&lt;LocalTargetConnection&gt;/&lt;ProxyEndpoint&gt; element

Nazwa punktu końcowego serwera proxy, który powinien być miejscem docelowym wywołań. To jest punkt końcowy serwera proxy w: serwer proxy interfejsu API określony za pomocą elementu <APIProxy>.

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

&lt;LocalTargetConnection&gt;/&lt;Path&gt; element

Ścieżka do docelowego punktu końcowego. Punkt końcowy musi odnosić się do serwera proxy w tym samym w organizacji i środowisku w roli serwera proxy wykonującego wywołanie.

Używaj tego zamiast pary <APIProxy>/<ProxyEndpoint>, gdy nie używasz nazwę serwera proxy lub nie może na niej polegać. Ścieżka może być niezawodnym celem.

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

Schematy

Zmienne przepływu

Zmienne przepływu umożliwiają dynamiczne zachowanie zasad i przepływów w czasie działania na podstawie protokołu HTTP nagłówki, treść wiadomości lub kontekst przepływu. Dostępne są następujące wstępnie zdefiniowane zmienne przepływu po wykonaniu zasady dotyczącej wywołań usługi. Więcej informacji o zmiennych Flow znajdziesz w dokumentacji zmiennych.

Objaśnienia dotyczące usługi mają własne żądania i odpowiedzi, a dostęp do tych danych możesz uzyskać w zmiennych. Ponieważ główny przekaz zawiera request.* i przedrostków zmiennych response.*, użyj myrequest.* i Prefiksy calloutResponse.* (domyślne w konfiguracji objaśnienia usługi) na uzyskać dane wiadomości charakterystyczne dla objaśnienia usługi. Pierwszy przykład w poniższej tabeli pokazuje, jak otrzymać nagłówki HTTP w objaśnieniu usługi.

Błędy

W tej sekcji opisano kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wyzwala błąd. Warto o tym wiedzieć, jeśli rozwijasz reguły błędów, aby obsługi błędów. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z zasadami i postępowaniu z błędami

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego tę zasadę.

Zmienne błędów

Te zmienne są ustawiane po wystąpieniu błędu działania. Więcej informacji znajdziesz w artykule Podstawowe informacje o błędach związanych z naruszeniem zasad.

Przykładowa odpowiedź na błąd

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

Przykładowa reguła błędu

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

Powiązane artykuły

• Generowanie i modyfikowanie wiadomości: Przypisywanie zasad wiadomości
• Wyodrębnianie zmiennych: Wyodrębnianie zmiennych
• Zmienne: zmienne odniesienie
• Konfiguracja TLS/SSL
  • Konfigurowanie Protokół TLS z Edge do backendu (chmura i chmura Private Cloud)
  • „Konfiguracja docelowego punktu końcowego TLS/SSL” w dokumentacji konfiguracji serwera proxy interfejsu API.
• Właściwości transportu HTTP: informacje o właściwościach punktów końcowych
• Alternatywa dla objaśnienia usługi: HTTPClient napisany w języku JavaScript, zobacz Obiektowy model JavaScript