ServiceCallout-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Richtliniensymbol

Was

Mit der ServiceCallout-Richtlinie können Sie aus Ihrem 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.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

  • 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

Lokaler Aufruf an einen internen Proxy

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

In diesem Beispiel wird ein Callout an einen lokalen API-Proxy erstellt, der sich in derselben Organisation und Umgebung befindet. Dabei wird der Proxyendpunkt data-manager mit dem Namen default angegeben.

URL als Variable

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

Bei diesem Beispiel wird eine Variable in der URL verwendet, um einen Teil der Ziel-URL dynamisch festzulegen. Der Protokollteil http:// der URL kann nicht durch eine Variable angegeben werden. Außerdem müssen Sie für den Domainteil der URL und für die restliche URL unterschiedliche Variablen verwenden.

Google Geocoding/Anfrage definieren

<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>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

Anstatt eine Richtlinie wie die AssignMessage-Richtlinie zum Erstellen des Anfrageobjekts zu verwenden, können Sie es direkt in der ServiceCallout-Richtlinie definieren. In diesem Beispiel legt die ServiceCallout-Richtlinie die Werte von drei Abfrageparametern fest, die an den externen Dienst übergeben werden. In der ServiceCallout-Richtlinie können Sie eine vollständige Anfragenachricht erstellen, in der eine Nutzlast, ein Codierungstyp wie application/xml, ein Header, Formularparameter usw. angegeben werden.

Im folgenden Beispiel wird die Anfrage erstellt, bevor die ServiceCallout-Richtlinie erreicht wird.

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

Der Inhalt der Anfragenachricht wird aus einer Variablen namens GeocodingRequest extrahiert, die beispielsweise mit einer AssignMessage-Richtlinie festgelegt werden kann. Die Antwortnachricht wird der Variable GeocodingResponse zugewiesen, wobei sie durch eine ExtractVariables-Richtlinie oder durch benutzerdefinierten Code in JavaScript oder Java geparst werden kann. Die Richtlinie wartet 30 Sekunden auf die Antwort von der Google Geocoding API, bevor eine Zeitüberschreitung auftritt.

Zielserver aufrufen

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

Diese Richtlinie verwendet das LoadBalancer-Attribut, um Zielserver aufzurufen und dafür ein Load-Balancing auszuführen. In diesem Beispiel wird die Arbeitslast auf zwei Zielserver namens httpbin und yahoo verteilt. Informationen zum Einrichten von Zielservern für Ihren Proxy und zum Konfigurieren des Load-Balancing finden Sie unter Load-Balancing über Back-End-Server.

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 ServiceCallout-Antworten auch zwischenspeichern, wie unter Wie kann ich die Ergebnisse der ServiceCallout-Richtlinie im Cache zwischenspeichern und später aus dem Cache abrufen? erläutert.

  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.

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>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleAccessToken>
            <Scopes>
              <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
            </Scopes>
            <LifetimeInSeconds ref="{variable}">3600</LifetimeInSeconds>
          </GoogleAccessToken>
        </Authentication>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleIDToken>
            <Audience ref="{variable}" useTargetUrl="BOOLEAN">{hostname}</Audience>
            <IncludeEmail ref="{variable}">true</IncludeEmail>
          </GoogleIDToken>
        </Authentication>
    </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:

Attribut Beschreibung Standard Presence
name

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

 – Erforderlich
continueOnError

Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten.

Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Siehe auch:

 false Optional
enabled

Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen.

Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.

 true Optional
async

Dieses Attribut wurde verworfen.

 false Verworfen

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

–

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Presence Optional
Typ String

<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 in der ServiceCallout-Richtlinie inline erstellt werden.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <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>
Standard Wenn Sie das Anfrageelement oder eines seiner Attribute weglassen, weist Apigee die folgenden Standardwerte zu:

<Request clearPayload="true" variable="servicecallout.request"/>

Sehen wir uns nun an, was diese Standardwerte bedeuten. Erstens bedeutet clearPayload=true, dass bei jeder Ausführung der ServiceCallout-Richtlinie ein neues Anfrageobjekt erstellt wird. Die Anfrage und der Anfrage-URI-Pfad werden also immer nur einmal verwendet. Zweitens ist der Name servicecallout.request der Standardvariablen ein reservierter Name, der der Anfrage zugewiesen wird, wenn Sie keinen Namen angeben.

Wenn Sie Datenmaskierung verwenden, müssen Sie den Standardnamen beachten. Wenn Sie den Variablennamen weglassen, müssen Sie servicecallout.request zur Maskenkonfiguration hinzufügen. Wenn Sie beispielsweise den Autorisierungsheader maskieren möchten, damit er nicht in Debugging-Sitzungen angezeigt wird, fügen Sie Folgendes in die Maskenkonfiguration ein, um den Standardnamen zu erfassen:

servicecallout.request.header.Authorization.
Presence Optional.
Typ –

Attribute

Attribut Beschreibung Standard Presence
Variable

Name der Variable, die die Anfragenachricht enthält.

 servicecallout.request Optional
clearPayload

Bei true wird die Variable mit der Anfragenachricht gelöscht, nachdem die Anfrage an das HTTP-Ziel gesendet wurde, um den von der Anfragenachricht verwendeten Arbeitsspeicher freizugeben.

Setzen Sie die Option clearPayload nur auf „false“, wenn die Anfragenachricht nach der Ausführung von ServiceCallout erforderlich ist.

 true Optional

<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>
Standard false
Presence Optional
Typ Boolesch

<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>
Standard NA
Presence Optional
Typ String

<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 Fehlerzustand versetzt, wie unter Fehler beheben beschrieben.

<Timeout>30000</Timeout>
Standard 55.000 Millisekunden (55 Sekunden), die Standardeinstellung für das HTTP-Zeitlimit für Apigee
Presence Optional
Typ Ganzzahl

<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>
Standard –
Presence Erforderlich
Typ –

<HTTPTargetConnection>/<LoadBalancer>-Element

Generiert Google OAuth 2.0- oder von Google ausgestellte OpenID Connect-Tokens für authentifizierte Aufrufe an Google-Dienste und benutzerdefinierte Dienste, die in bestimmten Google Cloud-Produkten ausgeführt werden, z. B. Cloud Functions und Cloud Run. Die Verwendung des Elements erfordert eine Einrichtung und Bereitstellung wie unter Google-Authentifizierung verwenden erläutert. Bei korrekter Einrichtung erstellt die Richtlinie automatisch ein Authentifizierungstoken und fügt es der Dienstanfrage hinzu.

Mit den untergeordneten Elementen GoogleAccessToken und GoogleIDToken können Sie die Richtlinie so konfigurieren, dass entweder Google OAuth- oder OpenID Connect-Token generiert werden. Je nach Art des Dienstes, den Sie aufrufen möchten, müssen Sie eines dieser untergeordneten Elemente auswählen.

Die ServiceCallout-Richtlinie unterstützt nur den Aufruf von HTTP-basierten Diensten.

Standard –
Erforderlich? Optional.
Typ Komplexer Typ
Übergeordnetes Element <HTTPTargetConnection>
Untergeordnete Elemente <HeaderName>
<GoogleAccessToken>
<GoogleIDToken>

Das Authentication-Element verwendet die folgende Syntax:

Syntax

<ServiceCallout>
...
  <HTTPTargetConnection>
    <Authentication>
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
          ...
        </Scopes>
        <!-- NOTE: The default value for LifetimeInSeconds is 3600. Change the default only
        if you want to limit the risk of leaked access tokens or improve performance. -->
        <LifetimeInSeconds ref="{variable}">INTEGER</LifetimeInSeconds>
      </GoogleAccessToken>

    --OR--
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
      </GoogleIDToken>
    </Authentication>
  </HTTPTargetConnection>
</ServiceCallout>

GoogleAccessToken verwenden

Das folgende Beispiel zeigt das Element GoogleAccessToken:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

GoogleIDToken verwenden

Das folgende Beispiel zeigt das Element GoogleIDToken:

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>false</IncludeEmail>
  </GoogleIDToken>
</Authentication>

HeaderName verwenden

Das folgende Beispiel zeigt das Element HeaderName:

  <Authentication>
    <HeaderName>X-Serverless-Authorization</HeaderName>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
    </GoogleAccessToken>
  </Authentication>

LifetimeInSeconds verwenden

Das folgende Beispiel zeigt das Element HeaderName:

  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
      <LifetimeInSeconds ref="variable">3600</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>

Attribute

Keine.

Untergeordnetes HeaderName-Element

Wenn eine Authentifizierungskonfiguration vorhanden ist, generiert Apigee standardmäßig ein Inhabertoken und fügt es in den Header Authorization in die Nachricht ein, die an das Zielsystem gesendet wird. Mit dem Element HeaderName können Sie den Namen eines anderen Headers angeben, der dieses Inhabertoken enthält. Dieses Feature ist besonders nützlich, wenn das Ziel ein Cloud Run-Dienst ist, der den Header X-Serverless-Authorization verwendet. Der Authorization-Header, falls vorhanden, bleibt unverändert und wird auch in der Anfrage gesendet.

Standard –
Erforderlich? Nein
Typ String
Übergeordnetes Element <Authentication>
Untergeordnete Elemente –

Das HeaderName-Element verwendet die folgende Syntax:

Syntax

<ServiceCallout>
...
  <Authentication>
    <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
    <GoogleAccessToken>
      ...
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

Mit statischem String

In diesem Beispiel wird das generierte Inhabertoken standardmäßig einem Header namens X-Serverless-Authorization hinzugefügt, der an das Zielsystem gesendet wird. Der Authorization-Header, falls vorhanden, bleibt unverändert und wird auch in der Anfrage gesendet.

<Authentication>
  <HeaderName>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Mit Variablenverweis

In diesem Beispiel wird das generierte Inhabertoken standardmäßig einem Header namens X-Serverless-Authorization hinzugefügt, der an das Zielsystem gesendet wird. Wenn my-variable einen Wert hat, wird dieser Wert anstelle des Standardstrings verwendet. Der Authorization-Header, falls vorhanden, bleibt unverändert und wird auch in der Anfrage gesendet.

<Authentication>
  <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Untergeordnetes GoogleAccessToken-Element

Generiert Google OAuth 2.0-Tokens für authentifizierte Aufrufe an Google-Dienste. Google OAuth-Tokens können zum Aufrufen vieler Arten von Google-Diensten verwendet werden, z. B. für Cloud Logging und Secret Manager.

Standard –
Erforderlich? Es muss das untergeordnete Element GoogleAccessToken oder GoogleIDToken vorhanden sein.
Typ String
Übergeordnetes Element <Authentication>
Untergeordnete Elemente <Scopes>
<LifetimeInSeconds>

Das GoogleAccessToken-Element verwendet die folgende Syntax:

Syntax

<ServiceCallout>
...
  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>SCOPE_1</Scope>
        ...
      </Scopes>
      <!-- NOTE: The default value for LifetimeInSeconds is 3600. We do not recommend changing
      the default unless you want to limit the risk of leaked access tokens or improve performance. -->
      <LifetimeInSeconds ref="FLOW_VARIABLE">INTEGER</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

Beispiel 1

Das folgende Beispiel zeigt das GoogleAccessToken-Element:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Beispiel 2

Im folgenden Beispiel wird gezeigt, wie Sie eine Verbindung zum Secret Manager herstellen, um ein Secret mithilfe der ServiceCallout-Richtlinie abzurufen. 

<ServiceCallout name="ServiceCallout-sm">
  <Response>SecretManagerResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
  </HTTPTargetConnection>
</ServiceCallout>

Beispiel 3

Im folgenden Beispiel wird gezeigt, wie ein Callout an Cloud Run aus der ServiceCallout-Richtlinie ausgeführt wird. 

<ServiceCallout name="ServiceCallout-CloudRun">
  <Response>CloudRunResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
      </GoogleIDToken>
    </Authentication>
    <URL>https://cloudrun-hostname.a.run.app/test</URL>
  </HTTPTargetConnection>
</ServiceCallout>

Untergeordnetes Scopes-Element

Gibt die Bereiche an, die im OAuth 2.0-Zugriffstoken enthalten sein sollen. Weitere Informationen finden Sie unter Auth 2.0-Bereiche für Google APIs. Unter diesem Element können Sie ein oder mehrere untergeordnete <Scope>-Elemente hinzufügen.

Standard –
Erforderlich? Erforderlich
Typ String
Übergeordnetes Element <GoogleAccessToken>
Untergeordnete Elemente <Scope>

Untergeordnetes Scope-Element

Gibt einen gültigen Google API-Bereich an. Weitere Informationen finden Sie unter Auth 2.0-Bereiche für Google APIs.

Standard –
Erforderlich? Es ist mindestens ein Wert erforderlich.
Typ String
Übergeordnetes Element <Scopes>
Untergeordnete Elemente Keine.

Untergeordnetes LifetimeInSeconds-Element

Gibt die Lebensdauer des Zugriffstokens in Sekunden an.

Standard 3600
Erforderlich? Optional
Typ Ganzzahl
Übergeordnetes Element <GoogleAccessToken>
Untergeordnete Elemente Keine.

Untergeordnetes GoogleIDToken-Element

Generiert von Google ausgestellte OpenID Connect-Tokens für authentifizierte Aufrufe an Google-Dienste.

Standard –
Erforderlich? Es muss das untergeordnete Element GoogleAccessToken oder GoogleIDToken vorhanden sein.
Typ String
Übergeordnetes Element <Authentication>
Untergeordnete Elemente <Audience>
<IncludeEmail>

Das GoogleIDToken-Element verwendet die folgende Syntax:

Syntax

<ServiceCallout>
...
  <Authentication>
    <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
    </GoogleIDToken>
  </Authentication>
</ServiceCallout>

Beispiel 1

Das folgende Beispiel zeigt das GoogleIDToken-Element:

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>true</IncludeEmail>
  </GoogleIDToken>
</Authentication>

Untergeordnetes Audience-Element

Das Zielobjekt für das generierte Authentifizierungstoken, z. B. die API oder das Konto, auf das das Token Zugriff gewährt.

Wenn der Wert von Audience leer ist oder die Variable ref nicht in einen gültigen Wert aufgelöst wird und useTargetUrl true ist, dann wird die URL des Ziels (ohne Abfrageparameter) als Zielgruppe verwendet. Standardmäßig ist useTargetUrl auf false festgelegt. 

<Audience>explicit-audience-value-here</Audience>

or:

<Audience ref='variable-name-here'/>

or:

<Audience ref='variable-name-here' useTargetUrl='true'/>

or:

<Audience useTargetUrl='true'/>
Standard –
Erforderlich? Erforderlich
Typ String
Übergeordnetes Element <GoogleIDToken>
Untergeordnete Elemente Keine.

Untergeordnetes IncludeEmail-Element

Wenn dafür true festgelegt ist, enthält das generierte Authentifizierungstoken die Anforderungen email und email_verified des Dienstkontos.

Standard false
Erforderlich? Optional
Typ Boolesch
Übergeordnetes Element <GoogleIDToken>
Untergeordnete Elemente Keine.

<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>
Standard –
Presence Erforderlich
Typ String

<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 Optionen für die TLS-Konfiguration 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>
Standard –
Presence Optional
Typ –

<HTTPTargetConnection>/<Properties>-Element

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>
Standard –
Presence Optional
Typ –

<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. Weitere Informationen zum Aufrufen von Zielservern über die ServiceCallout-Richtlinie und mithilfe von Routingregeln finden Sie unter Zielendpunkt-/Server-Callout.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
Standard –
Presence Optional
Typ –

<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>
Standard –
Presence Erforderlich
Typ –

<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>
Standard –
Presence Erforderlich
Typ String

<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>
Standard –
Presence Optional
Typ –

<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>
Standard –
Presence Optional
Typ –

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 Referenz zu Ablaufvariablen.

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.

Variable Beschreibung

Im Folgenden finden Sie ein Beispiel für das Abrufen von ServiceCallout-Anfragen und -Antwortheadern, ähnlich wie Sie Header aus der Hauptanfrage und -antwort erhalten würden.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

Dabei ist calloutResponse der Variablenname für die Antwort im ServiceCallout und myRequest der Variablenname für die Anfrage. Beispiel:

calloutResponse.header.Content-Length

Gibt den Content-Length-Header der ServiceCallout-Antwort zurück.

Bereich: Von der ServiceCallout-Weiterleitung
Typ: String
Berechtigung: Lesen/Schreiben

Ein Nachrichten-Header in der ServiceCallout-Anfrage oder -Antwort. Wenn das API-Proxy-Ziel beispielsweise http://example.com und das ServiceCallout-Ziel http://mocktarget.apigee.net lautet, sind diese Variablen die Header für den Callout an http://mocktarget.apigee.net.
servicecallout.requesturi

Bereich: Von der Weiterleitung der ServiceCallout-Anfrage
Typ: String
Berechtigung: Lesen/Schreiben

Der TargetEndpoint-URI für eine ServiceCallout-Richtlinie. Der URI ist die TargetEndpoint-URL ohne Protokoll- und Domain-Spezifikation.
servicecallout.{policy-name}.target.url

Bereich: Von der Weiterleitung der ServiceCallout-Anfrage
Typ: String
Berechtigung: Lesen/Schreiben

Die Ziel-URL für einen ServiceCallout.

calloutResponse.content

Dabei ist calloutResponse der <Response>-Variablenname in der ServiceCallout-Konfiguration.

Bereich: Von der Weiterleitung der ServiceCallout-Antwort
Typ: String
Berechtigung: Lesen/Schreiben

Der Antworttext von ServiceCallout.
servicecallout.{policy-name}.expectedcn

Bereich: Von der Weiterleitung der ServiceCallout-Anfrage
Typ: String
Berechtigung: Lesen/Schreiben

Der erwartete gemeinsame Name des TargetEndpoint wie in einer ServiceCallout-Richtlinie angegeben. Dies ist nur sinnvoll, wenn der TargetEndpoint auf einen TLS/SSL-Endpunkt verweist.
servicecallout.{policy-name}.failed

Bereich: Von der Weiterleitung der ServiceCallout-Antwort
Typ: String
Berechtigung: Lesen/Schreiben

Boolescher Wert, der angibt, ob die Richtlinie erfolgreich war, "false", oder fehlgeschlagen ist, "true".

Fehler

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die 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.

Fehlercode HTTP-Status Ursache Beheben
steps.servicecallout.ExecutionFailed 500

Dieser Fehler kann in folgenden Fällen auftreten:

  • Die Richtlinie wird aufgefordert, fehlerhafte oder anderweitig eingegebene Eingaben zu verarbeiten.
  • Der Back-End-Zieldienst gibt einen Fehlerstatus zurück (standardmäßig, 4xx oder 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 Die in der Richtlinie angegebene Variable Request gehört nicht zum Typ Message. Wenn es sich beispielsweise um einen String oder einen anderen Nachrichtentyp handelt, wird kein Fehler angezeigt.
steps.servicecallout.RequestVariableNotRequestMessageType 500 Die in der Richtlinie angegebene Variable Request gehört nicht zum Typ RequestMessage. Wenn es sich beispielsweise um einen Antworttyp handelt, wird dieser Fehler angezeigt.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> ist aktiviert, aber useTargetUrl ist auf „false“ gesetzt, und <Audience> wird zum Zeitpunkt des Fehlers weder direkt noch über einen Verweis ein Wert zugewiesen.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 Dieser Fehler kann auftreten, wenn der API-Proxy mit dem Element <Authentication> konfiguriert wurde. Hier einige Gründe dafür:
  • Das mit dem Proxy bereitgestellte Dienstkonto:
    • existiert nicht in Ihrem Projekt
    • wurde deaktiviert
    • (Nur Apigee Hybrid) hat dem Dienstkonto apigee-runtime die Rolle roles/iam.serviceAccountTokenCreator nicht gewährt.
  • Die IAMCredentials API ist im Quellprojekt des Dienstkontos apigee-runtime deaktiviert.
  • Das Element <GoogleAccessToken> wird verwendet und es werden ein oder mehrere ungültige Bereiche angegeben. Suchen Sie zum Beispiel nach Tippfehlern oder leeren Bereichen.

    • Nur für Apigee Hybrid, überprüfen Sie das Log des Laufzeitcontainers und suchen Sie nach GoogleTokenGenerationFailure, um detailliertere Fehlermeldungen zu finden, die bei der Fehlersuche helfen können.

    Bereitstellungsfehler

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

    Fehlername Ursache Beheben
    URLMissing Das <URL>-Element in <HTTPTargetConnection> fehlt oder ist leer.
    ConnectionInfoMissing Dieser Fehler tritt auf, wenn die Richtlinie kein <HTTPTargetConnection>- oder <LocalTargetConnection>-Element enthält.
    InvalidTimeoutValue Dieser Fehler tritt auf, wenn der Wert von <Timeout> negativ oder null ist.
    FAILED_PRECONDITION Dieser Fehler tritt auf, wenn das Dienstkonto fehlt, wenn der Proxy mit dem Tag <Authentication> konfiguriert ist.

    Beispiel: 

    Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
          account identity, but one was not provided with the request.
    PERMISSION_DENIED Dieser Fehler tritt auf, wenn ein Berechtigungsproblem mit dem Dienstkonto besteht und der Proxy mit dem Tag <Authentication> konfiguriert ist. Mögliche Ursachen:
    • Das Dienstkonto ist nicht vorhanden.
    • Das Dienstkonto wurde nicht im selben Google Cloud-Projekt wie die Apigee-Organisation erstellt.
    • Der Bereitsteller hat die Berechtigung iam.serviceAccounts.actAs für das Dienstkonto. Weitere Informationen finden Sie im Hilfeartikel Dienstkontoberechtigungen.

    Fehlervariablen

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

    Variablen Wo Beispiel
    fault.name="fault_name" fault_name ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. servicecallout.SC-GetUserData.failed = true

    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="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

    Weitere Informationen