ServiceCallout policy

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

Was

Mit der Service-Callout-Richtlinie können Sie über Ihren API-Proxy-Ablauf einen anderen Dienst aufrufen. Sie können Callouts entweder an einen externen Dienst (z. B. einen externen RESTful-Endpunkt) oder an interne Dienste (z. B. einen API-Proxy in derselben Organisation und Umgebung) senden.

• Bei einem externen Anwendungsfall senden Sie ein Callout an eine Drittanbieter-API, die sich außerhalb Ihres Proxys befindet. Die Antwort von der Drittanbieter-API wird geparst und in die Antwortnachricht Ihrer API eingefügt, um die Daten für App-Endnutzer zu konsolidieren und zu erweitern. Sie können auch eine Anfrage mit der ServiceCallout-Richtlinie im Anfragefluss stellen und dann die Informationen in der Antwort an den TargetEndpoint des API-Proxys übergeben.
• In einem anderen Anwendungsfall rufen Sie einen Proxy auf, der sich in derselben Organisation und Umgebung befindet wie der Proxy, von dem aus Sie aufrufen. Dies kann beispielsweise bei einem Proxy hilfreich sein, der eine eigenständige Funktionalität auf niedriger Ebene bietet, die von einem oder mehreren anderen Proxys genutzt wird. Ein Proxy, der Vorgänge zum Erstellen, Lesen, Aktualisieren und Löschen mit einem Back-End-Datenspeicher verfügbar macht, kann beispielsweise der Zielproxy für mehrere andere Proxys sein, die die Daten für Clients verfügbar machen.

Die Richtlinie unterstützt Anfragen über HTTP und HTTPS.

Beispiele

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

ServiceCallout-Richtlinie

Es gibt viele Szenarien, in denen Sie eine ServiceCallout-Richtlinie in Ihrem API-Proxy verwenden können. Beispielsweise können Sie einen API-Proxy so konfigurieren, dass Aufrufe an einen externen Dienst gesendet werden, um Geostandortdaten, Kundenrezensionen, Artikel aus dem Einzelhandelskatalog eines Partners usw. bereitzustellen.

In den meisten Fällen werden zwei Zusatzrichtlinien verwendet: "AssignMessage" und "ExtractVariables".

• Anfrage: AssignMessage füllt die an den Remote-Dienst gesendete Anfragenachricht aus.

• Antwort: ExtractVariables parst die Antwort und extrahiert bestimmte Inhalte.

Eine typische ServiceCallout-Richtlinie setzt sich so zusammen:

1. AssignMessage-Richtlinie: Erstellt eine Anfragenachricht, füllt HTTP-Header aus, Abfrageparameter, legt HTTP-Verb fest usw.
2. ServiceCallout-Richtlinie: Verweist auf eine Nachricht, die mit der AssignMessage-Richtlinie erstellt wurde, definiert eine Ziel-URL für den externen Aufruf und definiert einen Namen für das Antwortobjekt, das der Zieldienst zurückgibt.
   
   Zur Verbesserung der Leistung können Sie auch ServiceCallout-Antworten im Cache speichern, wie in diesem Apigee Community-Thread beschrieben: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html
3. ExtractVariables-Richtlinie: Definiert in der Regel einen JSONPath- oder XPath-Ausdruck, der die von der ServiceCallout-Richtlinie erzeugte Nachricht parst. Die Richtlinie legt dann Variablen mit den Werten fest, die aus der ServiceCallout-Antwort geparst wurden.

Unter Richtlinienzusammensetzung verwenden finden Sie einen vollständigen API-Beispielproxy, der die ServiceCallout-Richtlinie zusammen mit den Richtlinien „AssignMessage“ und „ExtractVariables“ verwendet.

Benutzerdefinierte Fehlerbehandlung

Elementverweis

Die folgenden Elemente und Attribute können Sie für diese Richtlinie konfigurieren:

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

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

In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:

<DisplayName>-Element

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

<DisplayName>Policy Display Name</DisplayName>

<Request>-Element

Gibt die Variable mit der Anfragenachricht an, die vom API-Proxy an den anderen Dienst gesendet wird. Die Variable kann durch eine vorherige Richtlinie im Ablauf erstellt oder inline in die Service Callout-Richtlinie eingefügt werden.

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

Die Syntax für die Tags <Remove>, <Copy>, <Add> und <Set> entspricht der Syntax für die AssignMessage-Richtlinie.

Die Richtlinie gibt einen Fehler zurück, wenn die Anfragenachricht nicht aufgelöst werden kann oder einen ungültigen Nachrichtentyp hat.

Im einfachsten Beispiel übergeben Sie eine Variable mit der Anfragenachricht, die bereits im Ablauf des API-Proxys ausgefüllt wurde:

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

Sie können auch die an den externen Dienst gesendete Anfragenachricht in der ServiceCallout-Richtlinie selbst ausfüllen:

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

Attribute

<Request>/<IgnoreUnresolvedVariables>-Element

Ist für diesen Wert true (wahr) festgelegt, ignoriert die Richtlinie jeden nicht behobenen Variablenfehler in der Anfrage.

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

<Response>-Element

Geben Sie dieses Element an, wenn die API-Proxy-Logik die Antwort vom Remote-Aufruf zur weiteren Verarbeitung erfordert.

Mit diesem Element wird der Name der Variablen angegeben, die die vom externen Dienst empfangene Antwortnachricht enthält. Die Antwort des Ziels wird der Variablen nur dann zugewiesen, wenn die gesamte Antwort von der Richtlinie erfolgreich gelesen wurde. Wenn der Remote-Aufruf aus irgendeinem Grund fehlschlägt, gibt die Richtlinie einen Fehler zurück.

Wird dieses Element weggelassen, wartet der API-Proxy nicht auf eine Antwort. Die Ausführung des API-Proxy-Ablaufs wird dann mit allen nachfolgenden Ablaufschritten fortgesetzt. Anders ausgedrückt: Ohne das Element Response ist die Antwort des Ziels nicht für die Verarbeitung durch nachfolgende Schritte verfügbar und im Proxyablauf kann kein Fehler im Remote-Aufruf ermittelt werden. Häufig wird das Element Response bei Verwendung von ServiceCallout weggelassen, wenn Nachrichten an ein externes System protokolliert werden sollen.

 <Response>calloutResponse</Response> 

<Timeout>-Element

Die Zeit in Millisekunden, die die ServiceCallout-Richtlinie auf eine Antwort vom Ziel wartet. Sie können diesen Wert zur Laufzeit nicht dynamisch festlegen. Wenn die ServiceCallout-Richtlinie das Zeitlimit überschreitet, wird der HTTP-Fehler 500 zurückgegeben, die Richtlinie schlägt fehl und der API-Proxy wird in einen Fehlerstatus versetzt, wie unter Fehler beheben beschrieben.

<Timeout>30000</Timeout>

<HTTPTargetConnection>-Element

Stellt Transportdetails wie URL, TLS/SSL und HTTP-Attribute bereit. Weitere Informationen finden Sie in der Konfigurationsreferenz zu <TargetEndpoint>.

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

<HTTPTargetConnection>/<URL>-Element

Die URL für den Dienst, der aufgerufen wird:

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

Sie können einen Teil der URL dynamisch mit einer Variablen bereitstellen. Der Protokollteil der URL (http://) unten kann jedoch nicht über eine Variable angegeben werden. Im nächsten Beispiel verwenden Sie eine Variable, um den Wert eines Abfrageparameters anzugeben:

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

Sie haben auch die Möglichkeit, einen Teil des URL-Pfads über eine Variable festzulegen:

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

Wenn Sie die Domain und den Port der URL mit einer Variablen angeben möchten, verwenden Sie nur eine Variable für die Domain und den Port und eine zweite Variable für die anderen Teile der URL:

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

<HTTPTargetConnection>/<SSLInfo>-Element

Die TLS/SSL-Konfiguration für den Back-End-Dienst. Hilfe zur TLS/SSL-Konfiguration finden Sie in der Referenz zur API-Proxy-Konfiguration unter TLS von Edge zum Back-End (Cloud und Private Cloud) konfigurieren und „TLS/SSL TargetEndpoint-Konfiguration“.

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

HTTP transport properties to the backend service. Weitere Informationen finden Sie unter Referenz für Endpunktattribute.

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

Rufen Sie einen oder mehrere Zielserver auf und führen Sie Load-Balancing auf ihnen aus. Sehen Sie sich das Beispiel Zielserver aufrufen im Abschnitt "Beispiele" an. Siehe auch Load-Balancing über Back-End-Server. In diesem Communitybeitrag erfahren Sie, wie Sie Zielserver sowohl über die ServiceCallout-Richtlinie als auch mithilfe von Routingregeln aufrufen.

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

<LocalTargetConnection>-Element

Gibt einen lokalen Proxy an, d. h. einen Proxy in derselben Organisation und in derselben Umgebung wie das Ziel von Dienstaufrufen.

Wenn Sie das Ziel genauer angeben möchten, verwenden Sie die Elemente <APIProxy> und <ProxyEndpoint> oder das Element <Path>.

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

<LocalTargetConnection>/<APIProxy>-Element

Der Name eines API-Proxys, der das Ziel eines lokalen Aufrufs ist. Der Proxy muss sich in derselben Organisation und Umgebung befinden wie der Proxy, der den Aufruf ausführt.

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

Geben Sie zusammen mit dem Element <APIProxy> das Element <ProxyEndpoint> an, um den Namen des Proxy-Endpunkts anzugeben, der für den Aufruf ausgerichtet werden soll.

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

<LocalTargetConnection>/<ProxyEndpoint>-Element

Der Name des Proxyendpunkts, der das Ziel von Aufrufen sein soll. Dies ist ein Proxyendpunkt im API-Proxy, der mit dem Element <APIProxy> angegeben wird.

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

<LocalTargetConnection>/<Path>-Element

Ein Pfad zum Endpunkt, der das Ziel darstellt. Der Endpunkt muss sich auf einen Proxy in derselben Organisation und Umgebung beziehen wie der Proxy der den Aufruf ausführt.

Verwenden Sie diesen Pfad anstelle eines <APIProxy>/<ProxyEndpoint>-Paares, wenn Sie den Proxynamen nicht kennen oder dieser nicht verwendet werden sollte. Der Pfad kann ein zuverlässiges Ziel sein.

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

Schemas

Ablaufvariablen

Ablaufvariablen ermöglichen ein dynamisches Verhalten von Richtlinien und Abläufen zur Laufzeit, basierend auf HTTP-Headern, Nachrichteninhalten oder dem Ablaufkontext. Die folgenden vordefinierten Ablaufvariablen sind verfügbar, nachdem eine ServiceCallout-Richtlinie ausgeführt wurde. Weitere Informationen zu Ablaufvariablen finden Sie in der Variablenreferenz.

ServiceCallouts haben eigene Anfragen und Antworten. Sie können über Variablen auf diese Daten zugreifen. Da die Hauptnachricht die Variablenpräfixe request.* und response.* verwendet, verwenden Sie die Präfixe myrequest.* und calloutResponse.* (die Standardwerte in der ServiceCallout-Konfiguration), um Nachrichtendaten zum ServiceCallout abzurufen. Das erste Beispiel in der folgenden Tabelle zeigt, wie Sie HTTP-Header in einem ServiceCallout erhalten.

Fehler

In diesem Abschnitt werden die Fehlercodes und Fehlermeldungen beschrieben, die zurückgegeben werden, sowie die Fehlervariablen, die von Edge festgelegt werden, wenn diese Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlervariablen

Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Beispiel für eine Fehlerantwort

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

Beispiel für eine Fehlerregel

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

Weitere Informationen

• Nachrichten erstellen oder ändern: AssignMessage-Richtlinie
• Variablen extrahieren: ExtractVariables-Richtlinie
• Variablen: Referenz zu Variablen
• TLS/SSL-Konfiguration
  • TLS von Edge zum Back-End (Cloud und Private Cloud) konfigurieren
  • "TLS/SSL-TargetEndpoint-Konfiguration" in der API-Proxy-Konfigurationsreferenz
• HTTP-Transport-Attribute: Referenz zu Endpoint-Attributen
• Alternative zu Service Callout: HTTPClient in JavaScript geschrieben, siehe JavaScript-Objektmodell