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

Wyświetlasz dokumentację Apigee Edge.
Zapoznaj się z dokumentacją Apigee X. info

Co

Zasada Service Callout umożliwia wywoływanie innej usługi z poziomu przepływu proxy interfejsu API. Możesz wykonywać wywołania usług zewnętrznych (np. zewnętrznego punktu końcowego usługi RESTful) lub usług wewnętrznych (np. serwera proxy interfejsu API w tej samej organizacji i środowisku).

• W przypadku zewnętrznego przypadku użycia wywołujesz interfejs API innej firmy, który jest zewnętrzny w stosunku do Twojego serwera proxy. Odpowiedź z interfejsu API innej firmy jest analizowana i wstawiana do wiadomości odpowiedzi interfejsu API, co wzbogaca i „miesza” dane dla użytkowników aplikacji. Możesz też wysłać żądanie za pomocą zasady Service Callout w przepływie żądania, a następnie przekazać informacje z odpowiedzi do elementu TargetEndpoint w proxy interfejsu API.
• W innym przypadku użycia wywołujesz serwer proxy, który znajduje się w tej samej organizacji i środowisku co serwer, z którego wywołujesz. Może to być przydatne na przykład wtedy, gdy masz serwer proxy, który oferuje pewną dyskretną funkcję niskiego poziomu, z której korzysta co najmniej 1 inny serwer proxy. Na przykład serwer proxy, który udostępnia operacje tworzenia, odczytywania, aktualizowania i usuwania w przypadku zaplecza pamięci danych, może być serwerem proxy docelowym dla wielu innych serwerów proxy, które udostępniają dane klientom.

Zasada obsługuje żądania przesyłane za pomocą protokołów 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>

Informacje o zasadzie wywołania usługi

W proxy interfejsu API możesz używać zasady wywołania usługi w wielu sytuacjach. Możesz na przykład skonfigurować serwer proxy interfejsu API, aby wywoływał zewnętrzną usługę w celu dostarczania danych geolokalizacyjnych, opinii klientów, produktów z katalogu detalicznego partnera itp.

Wywołanie zewnętrzne jest zwykle używane z 2 innymi zasadami: Przypisz wiadomość i Wyodrębnij zmienne.

• Żądanie: opcja Przypisz wiadomość wypełnia wiadomość z żądaniem wysłaną do usługi zdalnej.

• Odpowiedź: funkcja Wyodrębnij zmienne analizuje odpowiedź i wyodrębnia z niej określone treści.

Typowa struktura zasad wywołań usługi obejmuje:

1. Zasady przypisywania wiadomości: tworzy wiadomość z żądaniem, wypełnia nagłówki HTTP, parametry zapytania, ustawia czasownik HTTP itp.
2. Zasada Wywołanie usługi: odwołuje się do wiadomości utworzonej przez zasadę Przypisz wiadomość, określa docelowy adres URL wywołania zewnętrznego i definiuje nazwę obiektu odpowiedzi, który zwraca usługa docelowa.
   
   Aby zwiększyć wydajność, możesz też buforować odpowiedzi na wywołania usługi, jak opisano w tym wątku na forum społeczności Apigee: How can I store the results of the ServiceCallout policy in cache and later retrieve it from cache? (Jak mogę przechowywać wyniki zasady ServiceCallout w pamięci podręcznej i później je z niej pobierać?).
3. Extract Variables policy: zazwyczaj definiuje wyrażenie JSONPath lub XPath, które analizuje wiadomość wygenerowaną przez wywołanie usługi. Następnie zasada ustawia zmienne zawierające wartości przeanalizowane z odpowiedzi wywołania usługi.

Pełny przykładowy serwer proxy interfejsu API, który korzysta z zasad Service Callout wraz z zasadami Assign Message i Extract Variables, znajdziesz w artykule Korzystanie z kompozycji zasad.

Niestandardowa obsługa błędów

Odwołanie do elementu

Oto elementy i atrybuty, które możesz skonfigurować w tych zasadach:

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

Atrybuty <ServiceCallout>

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

&lt;DisplayName&gt; 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>

Element <Request>

Określa zmienną zawierającą wiadomość z żądaniem, która jest wysyłana z proxy interfejsu API do innej usługi. Zmienną może utworzyć poprzednia zasada w przepływie lub możesz ją utworzyć w zasadzie wywołania 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 zasady przypisywania wiadomości.

Zasady zwracają błąd, jeśli nie można rozpoznać wiadomości z żądaniem lub ma ona nieprawidłowy typ.

W najprostszym przykładzie przekazujesz zmienną zawierającą wiadomość żądania, która została wypełniona wcześniej w procesie serwera proxy interfejsu API:

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

Możesz też wypełnić wiadomość z prośbą wysyłaną do usługi zewnętrznej w samych zasadach wywołania 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

Element <Request>/<IgnoreUnresolvedVariables>

Jeśli zasada ma wartość true, ignoruje ona wszelkie nierozwiązane błędy zmiennych w żądaniu.

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

Element <Response>

Użyj tego elementu, gdy logika proxy API wymaga odpowiedzi z wywołania zdalnego do dalszego przetwarzania.

Jeśli ten element jest obecny, określa nazwę zmiennej, która będzie zawierać wiadomość z odpowiedzią otrzymaną z usługi zewnętrznej. Odpowiedź z usługi docelowej jest przypisywana do zmiennej tylko wtedy, gdy zasada odczyta całą odpowiedź. Jeśli wywołanie zdalne zakończy się niepowodzeniem z jakiegokolwiek powodu, zasada zwróci błąd.

Jeśli ten element zostanie pominięty, serwer proxy interfejsu API nie będzie czekać na odpowiedź, a wykonywanie przepływu serwera proxy interfejsu API będzie kontynuowane z kolejnymi krokami przepływu. Ponadto, co oczywiste, bez elementu Response odpowiedź z usługi docelowej nie jest dostępna do przetworzenia w kolejnych krokach, a przepływ proxy nie może wykryć błędu w wywołaniu zdalnym. Częstym zastosowaniem pomijania elementu Response podczas korzystania z elementu ServiceCallout jest rejestrowanie wiadomości w systemie zewnętrznym.

 <Response>calloutResponse</Response>

Element <Timeout>

Czas w milisekundach, przez jaki zasada wywołania usługi będzie czekać na odpowiedź z miejsca docelowego. Nie możesz ustawić tej wartości dynamicznie w czasie działania programu. Jeśli wywołanie usługi osiągnie limit czasu, zwracany jest kod HTTP 500, zasady nie działają, a proxy interfejsu API przechodzi w stan błędu, jak opisano w sekcji Obsługa błędów.

<Timeout>30000</Timeout>

Element <HTTPTargetConnection>

Zawiera szczegóły transportu, takie jak URL, TLS/SSL i właściwości HTTP. Zapoznaj się z <TargetEndpoint> odniesieniem do konfiguracji.

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

Element <HTTPTargetConnection>/<URL>

Adres URL wywoływanej usługi:

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

Część adresu URL możesz podać dynamicznie za pomocą zmiennej. Część adresu URL zawierająca protokół, czyli http://, nie może być jednak określona przez zmienną. W następnym przykładzie użyjesz zmiennej, aby określić wartość parametru 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, a drugiej zmiennej dla pozostałych części adresu URL:

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

Element <HTTPTargetConnection>/<SSLInfo>

Konfiguracja TLS/SSL usługi backendu. Pomoc dotyczącą konfiguracji TLS/SSL znajdziesz w artykułach Konfigurowanie protokołu TLS od Edge do backendu (Cloud i Private Cloud) oraz „Konfiguracja TargetEndpoint 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 znajdziesz w dokumentacji właściwości punktu końcowego.

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

Element <HTTPTargetConnection>/<LoadBalancer>

wywoływać co najmniej 1 serwer docelowy i równoważyć na nim obciążenie; Zobacz przykładowy kod Wywoływanie serwerów docelowych w sekcji Przykłady. Zobacz też Równoważenie obciążenia na serwerach backendu. Zapoznaj się też z tym postem na forum, w którym omawiamy sposoby wywoływania serwerów docelowych zarówno za pomocą zasady Service Callout, jak i reguł routingu.

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

Element <LocalTargetConnection>

Określa lokalny serwer proxy – czyli serwer proxy w tej samej organizacji i środowisku – jako cel wywołań usługi.

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

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

Element <LocalTargetConnection>/<APIProxy>

Nazwa proxy interfejsu API, który jest celem wywołania lokalnego. Serwer proxy musi znajdować się w tej samej organizacji i środowisku co serwer proxy, który wykonuje wywołanie.

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

Oprócz elementu <APIProxy> dodaj element <ProxyEndpoint>, aby określić nazwę punktu końcowego serwera proxy, do którego ma być kierowane połączenie.

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

Element <LocalTargetConnection>/<ProxyEndpoint>

Nazwa punktu końcowego serwera proxy, który ma być celem połączeń. Jest to punkt końcowy proxy w proxy interfejsu API określony za pomocą elementu <APIProxy>.

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

Element <LocalTargetConnection>/<Path>

Ścieżka do punktu końcowego, na który kierowane są reklamy. Punkt końcowy musi odwoływać się do serwera proxy w tej samej organizacji i środowisku co serwer proxy, który wykonuje wywołanie.

Używaj tego tagu zamiast pary <APIProxy>/<ProxyEndpoint>, gdy nie znasz nazwy serwera proxy lub nie możesz na niej polegać. Ścieżka może być wiarygodnym celem.

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

Schematy

Zmienne przepływu

Zmienne przepływu umożliwiają dynamiczne działanie zasad i przepływów w czasie działania na podstawie nagłówków HTTP, treści wiadomości lub kontekstu przepływu. Po wykonaniu zasady wywołania usługi dostępne są te wstępnie zdefiniowane zmienne Flow: Więcej informacji o zmiennych przepływu znajdziesz w dokumentacji zmiennych.

Wywołania usługi mają własne żądanie i odpowiedź, a dostęp do tych danych możesz uzyskać za pomocą zmiennych. Główna wiadomość używa prefiksów zmiennych request.* i response.*, więc użyj prefiksów myrequest.* i calloutResponse.* (domyślnych w konfiguracji wywołania usługi), aby uzyskać dane wiadomości specyficzne dla wywołania usługi. Pierwszy przykład w tabeli poniżej pokazuje, jak uzyskać nagłówki HTTP w wywołaniu usługi.

Błędy

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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 dotyczących wiadomości
• Wyodrębnianie zmiennych: zasady Extract Variables
• Zmienne: Zmienne odwołanie
• Konfiguracja TLS/SSL
  • Konfigurowanie protokołu TLS od Edge do backendu (Cloud i Private Cloud)
  • „Konfiguracja TLS/SSL TargetEndpoint” w dokumentacji konfiguracji proxy interfejsu API
• Właściwości transportu HTTP: Dokumentacja właściwości punktu końcowego
• Alternatywa dla wywołania usługi: HTTPClient napisany w JavaScript, patrz model obiektów JavaScript