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

Oglądasz dokumentację Apigee Edge.
Wyświetl dokumentację Apigee X.

Co

Zasada Objaśnienie usługi umożliwia wywołanie innej usługi przez serwer proxy interfejsu API. Możesz dodawać objaśnienia do usługi zewnętrznej (np. zewnętrznego punktu końcowego usługi RESTowego) lub usług wewnętrznych (np. serwera proxy interfejsu API w tej samej organizacji i środowisku).

• W zewnętrznym przypadku użycia dodajesz objaśnienie do interfejsu API firmy zewnętrznej, który jest dostępny poza serwerem proxy. Odpowiedź z interfejsu API innej firmy jest analizowana i umieszczana w odpowiedzi odpowiedzi interfejsu API, co wzbogaca dane użytkowników o dane aplikacji i „łączy je”. Możesz też wysłać żądanie za pomocą zasady Objaśnienie usługi, a następnie przekazać informacje w odpowiedzi do docelowego punktu końcowego serwera proxy interfejsu API.
• W innym przypadku wywołasz serwer proxy należący do tej samej organizacji i środowiska, z którego wywołujesz. Może to być przydatne, jeśli korzystasz z serwera proxy, który oferuje niektóre funkcje niskiego poziomu, z których będzie korzystać co najmniej jeden inny serwer proxy. Na przykład serwer proxy, który udostępnia operacje tworzenia, odczytu, aktualizowania lub usuwania z użyciem magazynu danych backendu, może być docelowym serwerem proxy wielu innych serwerów proxy, które udostępniają dane klientom.

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ług – informacje

Istnieje wiele sytuacji, w których możesz użyć zasad dotyczących objaśnień dotyczących usług na serwerze proxy interfejsu API. Możesz na przykład skonfigurować serwer proxy interfejsu API, aby wysyłał wywołania do usługi zewnętrznej w celu dostarczania danych geolokalizacyjnych, opinii klientów, elementów z katalogu partnera itd.

Objaśnienie jest zwykle używane z 2 innymi zasadami: przypisywanie wiadomości i pobieranie zmiennych.

• Prośba: w polu Przypisz wiadomość znajduje się wiadomość wysłana do usługi zdalnej.

• Odpowiedź: wyodrębnia zmienne i wyodrębnia konkretną treść.

Typowy skład zasad dotyczących objaśnień dotyczących usług:

1. Przypisz zasadę wiadomości: tworzy wiadomość z żądaniem, wypełnia nagłówki HTTP, parametry zapytania, ustawia czasownik HTTP itp.
2. Wyjaśnienie dotyczące usługi: odwołuje się do wiadomości utworzonej przez zasadę Przypisz wiadomość, definiuje docelowy adres URL wywołania zewnętrznego i określa nazwę obiektu odpowiedzi zwracanego przez usługę docelową.
   
   Aby uzyskać lepszą wydajność, możesz też zapisywać w pamięci podręcznej odpowiedzi na wywołania usługi w sposób opisany w tym wątku w społeczności Apigee: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
3. Pobierz zasady zmiennych: zwykle definiuje wyrażenie JSONPath lub XPath, które analizuje komunikat wygenerowany przez objaśnienie usługi. Zasada ustawia wtedy zmienne zawierające wartości przeanalizowane w odpowiedzi na objaśnienie usługi.

Pełny przykładowy serwer proxy interfejsu API, który korzysta z zasad Objaśnienia usługi wraz z zasadami przypisywania wiadomości i wyodrębniania zmiennych, znajdziesz w artykule Korzystanie z kompozycji zasad.

Niestandardowa obsługa błędów

Dokumentacja elementu

Poniżej znajdziesz 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>

Atrybuty <ServiceCallout>

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

Tabela poniżej opisuje atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:

Element <DisplayName>

Używaj atrybutu name tak, aby oznaczyć zasadę w edytorze proxy interfejsu zarządzania inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <Request>

Określa zmienną zawierającą komunikat z żądaniem, który jest wysyłany z serwera proxy interfejsu API do innej usługi. Zmienna może być utworzona przez poprzednią zasadę w ramach przepływu lub można ją utworzyć w tekście zasady dotyczącej 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 zasad przypisywania wiadomości.

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

W najprostszym przykładzie przekazujesz zmienną zawierającą wiadomość z żądaniem, która została wypełniona wcześniej w ramach przepływu pracy serwera proxy interfejsu API:

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

Możesz też wypełnić komunikat żądania wysłany do usługi zewnętrznej w zasadach dotyczących objaśnienia dotyczących 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, zasada ignoruje w żądaniu błąd nieusuniętej zmiennej.

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

Element <Response>

Uwzględnij ten element, jeśli logika serwera proxy interfejsu API wymaga odpowiedzi ze wywołania zdalnego w celu dalszego przetwarzania.

Jeśli ten element jest obecny, określa nazwę zmiennej, która będzie zawierać komunikat odpowiedzi otrzymany z usługi zewnętrznej. Odpowiedź z elementu docelowego jest przypisywana do zmiennej tylko wtedy, gdy zasada odczyta ją w całości. Jeśli z jakiegoś powodu wywołanie zdalne się nie powiedzie, zasada zwróci błąd.

Jeśli ten element zostanie pominięty, serwer proxy interfejsu API nie będzie czekać na odpowiedź. Wykonywanie kolejnych procesów serwera proxy interfejsu API jest kontynuowane. Ponadto zaznaczono, że bez elementu Response odpowiedź z środowiska docelowego nie jest dostępna do przetworzenia w kolejnych krokach. Nie ma też sposobu na wykrycie błędu przez wywołanie zdalne. Typowe zastosowanie pomijania elementu Response w przypadku użycia elementu ServiceCallout: logowanie komunikatów do systemu zewnętrznego.

 <Response>calloutResponse</Response> 

Element <Timeout>

Czas oczekiwania (w milisekundach) na objaśnienie usługi. Nie możesz ustawić tej wartości dynamicznie w czasie działania. Jeśli objaśnienie wywołania przekracza limit czasu, zwracany jest kod HTTP 500, zasada nie działa, a serwer proxy interfejsu API przechodzi w stan błędu zgodnie z opisem w sekcji Obsługa błędów.

<Timeout>30000</Timeout>

Element <HTTPTargetConnection>

Zawiera informacje o transporcie, takie jak URL, TLS/SSL i HTTP. Zobacz dokumentację konfiguracji <TargetEndpoint>.

<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 przekazywać dynamicznie za pomocą zmiennej. Jednak część adresu URL http:// poniżej nie może być określona przez zmienną. W następnym przykładzie użyjesz zmiennej, by określić wartość parametru zapytania:

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

Możesz też ustawić część ścieżki adresu URL zawierającą zmienną:

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

Jeśli chcesz użyć zmiennej, by określić domenę i adres 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 dla usługi backendu. Pomoc dotyczącą konfiguracji TLS/SSL znajdziesz w artykułach Konfigurowanie protokołu TLS z brzegu do backendu (chmura i chmura prywatna) oraz „Konfiguracja TLS/SSL celu końcowego” w artykule o 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 HTTP do usługi backendu. Więcej informacji znajdziesz w przewodniku po 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>

Element <HTTPTargetConnection>/<LoadBalancer>

Wywołaj co najmniej 1 serwer docelowy i zrównoważ równoważenie obciążenia. Przykład próbki serwerów docelowych połączeń znajdziesz w sekcji Przykłady. Zobacz też Równoważenie obciążenia na serwerach backendu. Zapoznaj się też z tym postem na karcie Społeczność, w którym omawiamy sposoby wywoływania serwerów docelowych z poziomu zasad dotyczących wywołań usługi oraz 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 (tj. serwer proxy w tej samej organizacji i środowisku) jako miejsce docelowe objaśnień dotyczących usług.

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

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

Element <LocalTargetConnection>/<APIProxy>

Nazwa serwera proxy interfejsu API, który jest celem wywołania lokalnego. Serwer proxy musi być w tej samej organizacji i tym samym środowisku co serwer proxy wywołujący.

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

Razem z elementem <APIProxy> dodaj element <ProxyEndpoint>, by określić nazwę punktu końcowego serwera proxy, na który powinno być kierowane wywołanie.

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

Element <LocalTargetConnection>/<ProxyEndpoint>

Nazwa punktu końcowego serwera proxy, który powinien być celem połączeń. Jest to punkt końcowy serwera proxy na serwerze proxy interfejsu API określonym w elemencie <APIProxy>.

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

Element <LocalTargetConnection>/<ścieżka>

Ścieżka do docelowego punktu końcowego. Punkt końcowy musi odwoływać się do serwera proxy znajdującego się w tej samej organizacji i tym samym środowisku co serwer proxy wywołujący wywołanie.

Używaj go 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 zachowanie zasad i przepływów w czasie działania na podstawie nagłówków HTTP, treści wiadomości lub kontekstu przepływu. Poniższe wstępnie zdefiniowane zmienne przepływu są dostępne po wykonaniu zasady dotyczącej objaśnienia usługi. Więcej informacji o zmiennych procesu znajdziesz w artykule o zmiennych.

Objaśnienia usługi mają własne żądania i odpowiedzi. Masz do nich dostęp za pomocą zmiennych. Ponieważ główna wiadomość zawiera prefiksy zmiennych request.* i response.*, użyj prefiksów myrequest.* i calloutResponse.* (takich jak domyślne w objaśnieniu usługi), aby uzyskać dane dotyczące wiadomości. Pierwszy przykład w tabeli poniżej pokazuje, jak uzyskać 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, a także wartości zmiennych ustawionych przez Edge w momencie aktywowania tej zasady. Ta informacja jest ważna, gdy opracowujesz reguły obsługi błędów. Więcej informacji znajdziesz w artykułach Co musisz wiedzieć o błędach zasad i Obsługa błędów.

Błędy w czasie wykonywania

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

Błędy wdrażania

Te błędy mogą wystąpić, gdy wdrażasz serwer proxy zawierający tę zasadę.

Zmienne błędów

Zmienne te są ustawiane po wystąpieniu błędu działania. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach 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 awarii

<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ębnij zmienne: Pobierz zasady zmiennych
• Zmienne: odwołania do zmiennych
• Konfiguracja TLS/SSL
  • Konfigurowanie protokołu TLS z brzegu do backendu (chmura i chmura prywatna)
  • „Konfiguracja celu końcowego TLS/SSL” w przewodniku po konfiguracji serwera proxy interfejsu API
• Właściwości transportu HTTP: informacje o właściwościach punktu końcowego
• Alternatywa dla objaśnienia usługi: HTTPClient napisane w języku JavaScript (zobacz model obiektów JavaScript).