Referenz zur API-Proxy-Konfiguration

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Als Entwickler, der mit Apigee arbeitet, müssen Sie API-Proxys konfigurieren, die als Proxys für APIs oder Backend-Dienste fungieren. Dieses Dokument enthält eine Referenz aller Konfigurationselemente, die Ihnen beim Erstellen von API-Proxys zur Verfügung stehen.

Wenn Sie erfahren möchten, wie Sie API-Proxys erstellen, sollten Sie mit dem Thema Einfachen API-Proxy erstellen beginnen.

Bearbeiten Sie Ihre API-Proxy-Konfiguration mit einer der folgenden Methoden:

Struktur des Verzeichnisses des API-Proxy-Konfiguration

Nachfolgend ist die Struktur des API-Proxy-Konfigurationsverzeichnisses dargestellt:

Zeigt die Verzeichnisstruktur an, in der "apiproxy" der Stamm ist. Direkt unter dem apiproxy-Verzeichnis finden Sie die Richtlinien, Proxys, Ressourcen und Zielverzeichnisse sowie die Datei "weatherapi.xml".

Eine API-Proxy-Konfiguration besteht aus folgenden Inhalten:

Basiskonfiguration Primäre Konfigurationseinstellungen für einen API-Proxy
ProxyEndpoint Einstellungen für die eingehende HTTP-Verbindung (vom Anfordern von Anwendungen zu Apigee), Anfrage- und Antwortabläufe sowie Richtlinienanhänge.
TargetEndpoint Einstellungen für die ausgehende HTTP-Verbindung (von Apigee zum Back-End-Dienst), Anfrage- und Antwortabläufe sowie Richtlinienanhänge.
Abläufe ProxyEndpoint- und TargetEndpoint-Anfragen und Antwortpipelines, an die Richtlinien angehängt werden können.
Richtlinien XML-formatierte Konfigurationsdateien, die den Apigee-Richtlinienschemas entsprechen.
Ressourcen Skripts, JAR-Dateien und XP-Dateien, auf die von Richtlinien verwiesen wird, um benutzerdefinierte Logik auszuführen

Basiskonfiguration

/apiproxy/weatherapi.xml

Die Basiskonfiguration für einen API-Proxy, der den Namen des API-Proxys definiert. Der Name muss innerhalb einer Organisation eindeutig sein.

Beispielkonfiguration:

<APIProxy name="weatherapi">
</APIProxy>

Elemente der Basiskonfiguration

Name Beschreibung Default Erforderlich?
APIProxy
name Der Name des API-Proxys, der innerhalb einer Organisation eindeutig sein muss. Die Zeichen, die Sie im Namen verwenden dürfen, sind auf folgende Zeichen beschränkt: A-Za-z0-9_- – Ja
revision Die Überarbeitungsnummer der API-Proxykonfiguration. Sie müssen die Revisionsnummer nicht explizit festlegen, da Apigee die aktuelle Überarbeitung des API-Proxys automatisch erfasst. – Nein
ConfigurationVersion Die Version des API-Proxykonfigurationsschemas, dem dieser API-Proxy entspricht. Der einzige unterstützte Wert ist derzeit "majorVersion 4" und "minorVersion 0". Diese Einstellung kann später verwendet werden, um die Weiterentwicklung des API-Proxyformats zu ermöglichen. 4.0 Nein
Description Eine Textbeschreibung des API-Proxys. Wenn die Beschreibung angegeben ist, wird sie in der Apigee-Benutzeroberfläche angezeigt. – Nein
DisplayName Ein nutzerfreundlicher Name, der sich vom Attribut name der API-Proxykonfiguration unterscheiden kann. – Nein
Policies Eine Liste der Richtlinien im Verzeichnis /policies dieses API-Proxys. Normalerweise wird dieses Element nur angezeigt, wenn der API-Proxy mithilfe der Apigee-Benutzeroberfläche erstellt wurde. Dies ist einfach eine Manifest-Einstellung, die Einblick in den Inhalt des API-Proxys bietet. – Nein
ProxyEndpoints Eine Liste der ProxyEndpoints im Verzeichnis /proxies dieses API-Proxys. Normalerweise sehen Sie dieses Element nur, wenn der API-Proxy mit der Apigee-Benutzeroberfläche erstellt wurde. Dies ist einfach eine Manifest-Einstellung, die Einblick in den Inhalt des API-Proxys bietet. – Nein
Resources Eine Liste der Ressourcen (JavaScript, Python, Java, XP) im Verzeichnis /resources dieses API-Proxys. Sie sehen dieses Element normalerweise nur, wenn der API-Proxy mit der Apigee-Benutzeroberfläche erstellt wurde. Dies ist einfach eine Manifest-Einstellung, die Einblick in den Inhalt des API-Proxys bietet. – Nein
Spec Gibt die OpenAPI-Spezifikation an, die dem API-Proxy zugeordnet ist. Der Wert wird auf eine URL oder einen Pfad im Spezifikationspeicher festgelegt.
 – Nein
TargetServers Eine Liste von TargetServern, auf die in einem der TargetEndpoints dieses API-Proxys verwiesen wird. Normalerweise wird dieses Element nur angezeigt, wenn der API-Proxy mit Apigee erstellt wurde. Dies ist einfach eine Manifest-Einstellung, die Einblick in den Inhalt des API-Proxys bietet. – Nein
TargetEndpoints Eine Liste von TargetEndpoints im Verzeichnis /targets dieses API-Proxys. Normalerweise sehen Sie dieses Element nur, wenn der API-Proxy mit der Apigee-Benutzeroberfläche erstellt wurde. Dies ist einfach eine Manifest-Einstellung, die Einblick in den Inhalt des API-Proxys bietet. – Nein

ProxyEndpoint

Die folgende Abbildung zeigt den Ablauf von Anfrage/Antwort:

Zeigt einen Client, der einen HTTP-Dienst aufruft. Die Anfrage durchläuft den Proxyendpunkt und dann den Zielendpunkt, bevor sie vom HTTP-Dienst verarbeitet wird. Die Antwort durchläuft den Zielendpunkt und dann den Proxyendpunkt, bevor sie an den Client zurückgegeben wird.

/apiproxy/proxies/default.xml

Die ProxyEndpoint-Konfiguration definiert die eingehende (Client-bezogene) Schnittstelle für einen API-Proxy. Wenn Sie einen ProxyEndpoint konfigurieren, richten Sie eine Netzwerkkonfiguration ein, die definiert, wie Clientanwendungen (Apps) die Proxy-API aufrufen.

Die folgende ProxyEndpoint-Konfiguration würde unter /apiproxy/proxies gespeichert werden:

<ProxyEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPProxyConnection>
    <BasePath>/weather</BasePath>
    <Properties/>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Folgende Konfigurationselemente sind in einem einfachen ProxyEndpoint erforderlich:

Elemente der ProxyEndpoint-Konfiguration

Name Beschreibung Default Erforderlich?
ProxyEndpoint
name Der Name des ProxyEndpoints. Muss innerhalb der API-Proxykonfiguration eindeutig sein, wenn (in seltenen Fällen) mehrere ProxyEndpoints definiert sind. Die Zeichen, die Sie im Namen verwenden dürfen, sind auf folgende Zeichen beschränkt: A-Za-z0-9._\-$ % – Ja
PreFlow Definiert die Richtlinien im PreFlow-Ablauf einer Anfrage oder Antwort. – Ja
Flows
Definiert die Richtlinien in den bedingten Abläufen einer Anfrage oder Antwort.
 – Ja
PostFlow
Definiert die Richtlinien im PostFlow-Ablauf einer Anfrage oder Antwort.
 – Ja
HTTPProxyConnection Definiert die mit dem API-Proxy verknüpfte Netzwerkadresse und den URI-Pfad.
BasePath

Ein erforderlicher String, der den von Apigee verwendeten URI-Pfad eindeutig identifiziert, um eingehende Nachrichten an den richtigen API-Proxy weiterzuleiten.

Der BasePath ist ein URI-Fragment (z. B. /weather), das an die Basis-URL eines API-Proxys angehängt wird (z. B. http://apifactory-test.apigee.net). BasePath muss innerhalb einer Umgebung eindeutig sein. Die Eindeutigkeit wird überprüft, wenn ein API-Proxy generiert oder importiert wird.

Platzhalter in Basispfaden verwenden

Sie können in den API-Proxy-Basispfaden einen oder mehrere "*" verwenden. Mit dem Basispfad /team/*/members können Clients beispielsweise https://[host]/team/blue/members und https://[host]/team/green/members aufrufen, ohne neue API-Proxys für die Unterstützung neuer Teams erstellen zu müssen. Beachten Sie, dass /**/ nicht unterstützt wird.

Wichtig: Apigee unterstützt NICHT die Verwendung eines Platzhalters "*"* als erstes Element eines Basispfads. Dies wird beispielsweise NICHT unterstützt: /*/search. Wenn der Basispfad mit einem "*" beginnt, kann dies zu unerwarteten Fehlern führen. Dies liegt an der Art und Weise, wie Apigee gültige Pfade identifiziert.

 / Ja
Properties Eine Reihe optionaler HTTP-Konfigurationseinstellungen kann als Attribute einer <ProxyEndpoint> definiert werden.

Verwenden Sie das Attribut request.queryparams.ignore.content.type.charset, damit der Proxy bei der Verarbeitung der Anfrage-URL den Parameter charset des Content-Type-Headers ignoriert. Zum Beispiel: 


<Property name= \
"request.queryparams.ignore.content.type.charset">true</>

Die folgende Tabelle zeigt die Beispielausgabe für die jeweilige Einstellung des Attributs charset und das Vorhandensein des Parameters charset des Headers Content-Type.

Attributeinstellung Headerwert Beispielausgabe
charset=false Parameter charset wurde nicht festgelegt john.doe+test@gmail.com
charset=false charset=utf-8 john.doe test@gmail.com
charset=true und kein charset-Parameter im Header Parameter charset wurde nicht festgelegt john.doe+test@gmail.com
charset=true Parameter charset=utf-8 wurde festgelegt john.doe+test@gmail.com
– Nein
FaultRules
Definiert, wie der ProxyEndpoint auf einen Fehler reagiert. Eine Fehlerregel gibt zwei Elemente an:
  • Eine Bedingung, die den Fehler angibt, der auf Grundlage der vordefinierten Kategorie, Unterkategorie oder Name des Fehlers verarbeitet werden soll
  • Eine oder mehrere Richtlinien, die das Verhalten der Fehlerregel für die entsprechende Bedingung definieren

Siehe Umgang mit Fehlern.

 – Nein
DefaultFaultRule

Behandelt alle Fehler (System, Transport, Messaging oder Richtlinie), die nicht explizit von einer anderen Fehlerregel behandelt werden.

Siehe Umgang mit Fehlern.

 – Nein
RouteRule Definiert das Ziel eingehender Anfragenachrichten nach der Verarbeitung durch die ProxyEndpoint-Anfragepipeline. Normalerweise verweist die RouteRule auf einen benannten TargetEndpoint, einen IntegrationEndpoint oder eine URL.
Name Erforderliches Attribut mit einem Namen für die RouteRule. Die Zeichen, die Sie im Namen verwenden dürfen, sind auf folgende Zeichen beschränkt: A-Za-z0-9._\-$ % Beispielsweise ist Cat2 %_ ein gültiger Name. – Ja
Condition Eine optionale Bedingung, die zur dynamischen Weiterleitung zur Laufzeit verwendet wird. Bedingte Routingregeln sind beispielsweise nützlich, um ein inhaltsbasiertes Routing zu aktivieren, um die Back-End-Versionierung zu unterstützen. – Nein
TargetEndpoint

Ein optionaler String, der eine benannte TargetEndpoint-Konfiguration identifiziert. Ein benannter TargetEndpoint ist ein beliebiger TargetEndpoint, der im selben API-Proxy im Verzeichnis /targets definiert ist.

Wenn Sie einen TargetEndpoint benennen, geben Sie an, wohin Anfragenachrichten nach der Verarbeitung durch die ProxyEndpoint-Anforderungspipeline weitergeleitet werden sollen. Dies ist eine optionale Einstellung.

Ein ProxyEndpoint kann eine URL direkt aufrufen. Zum Beispiel kann eine JavaScript- oder Java-Ressource, die in der Rolle eines HTTP-Clients arbeitet, die grundlegende Duft eines TargetEndpoint ausführen, bei dem Anfragen an einen Back-End-Dienst weitergeleitet werden.

 – Nein
URL Ein optionaler String, der eine vom ProxyEndpoint aufgerufene ausgehende Netzwerkadresse definiert und alle TargetEndpoint-Konfigurationen umgeht, die möglicherweise unter /targets gespeichert sind – Nein

So konfigurieren Sie RouteRules

Ein benannter TargetEndpoint bezieht sich auf eine Konfigurationsdatei unter /apiproxy/targets, an die RouteRule eine Anfrage nach der Verarbeitung durch den ProxyEndpoint weiterleitet.

Die folgende RouteRule bezieht sich beispielsweise auf die Konfiguration /apiproxy/targets/myTarget.xml:

<RouteRule name="default">
  <TargetEndpoint>myTarget</TargetEndpoint>
</RouteRule>

Direkter URL-Aufruf

Ein ProxyEndpoint kann auch direkt einen Back-End-Dienst aufrufen. Bei dem direkten URL-Aufruf werden alle benannten TargetEndpoints-Konfigurationen unter /apiproxy/targets umgangen. Aus diesem Grund ist TargetEndpoint eine optionale API-Proxykonfiguration, obwohl in der Praxis kein direkter Aufruf vom ProxyEndpoint empfohlen wird.

Die folgende RouteRule führt beispielsweise einen HTTP-Aufruf an http://api.mycompany.com/v2 aus.

<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

Bedingte Routen

RouteRules können für die Unterstützung von dynamischem Routing zur Laufzeit verkettet werden. Eingehende Anfragen können an benannte TargetEndpoint-Konfigurationen, direkt an URLs oder eine Kombination aus beidem weitergeleitet werden, basierend auf HTTP-Headern, Nachrichteninhalten, Suchparametern oder Kontextinformationen wie Tageszeit, Gebietsschema usw.

Bedingte Routenregeln funktionieren wie andere bedingte Anweisungen in Apigee. Siehe Bedingungsreferenz und Ablaufvariablenreferenz.

Die folgende RouteRule-Kombination wertet beispielsweise zuerst die eingehende Anfrage aus, um den Wert eines HTTP-Headers zu prüfen. Wenn der HTTP-Header routeTo den Wert TargetEndpoint1 hat, wird die Anfrage an den TargetEndpoint mit dem Namen TargetEndpoint1 weitergeleitet. Ist dies nicht der Fall, wird die eingehende Anfrage an http://api.mycompany.com/v2 weitergeleitet.

<RouteRule name="MyRoute">
  <Condition>request.header.routeTo = "TargetEndpoint1"</Condition>
  <TargetEndpoint>TargetEndpoint1</TargetEndpoint>
</RouteRule>
<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

Nullrouten

Eine Null-RouteRule kann so definiert werden, dass sie Supportszenarien unterstützt, in denen die Anfragenachricht nicht an den TargetEndpoint weitergeleitet werden muss. Dies ist nützlich, wenn der ProxyEndpoint die gesamte erforderliche Verarbeitung ausführt, z. B. JavaScript verwendet, um einen externen Dienst aufzurufen, oder um Daten aus einem Lookup zum Apigee Schlüssel/Wert-Speicher abzurufen.

Im Folgenden wird beispielsweise eine Nullroute definiert:

<RouteRule name="GoNowhere"/>

Bedingte Nullrouten können nützlich sein. Im folgenden Beispiel wird eine Nullroute konfiguriert, die ausgeführt wird, wenn ein HTTP-Header request.header.X-DoNothing einen anderen Wert als null hat.

<RouteRule name="DoNothingOnDemand">
  <Condition>request.header.X-DoNothing != null</Condition>
</RouteRule>

Denken Sie daran, dass die Routingregeln verkettet werden können. Eine bedingte Nullroute wäre also normalerweise eine Komponente eines Satzes von Routingregeln, die für ein bedingtes Routing geeignet sind.

Eine praktische Verwendung einer bedingten Nullroute würde das Caching unterstützen. Mithilfe des Werts der Variablen, der durch die Cache-Richtlinie festgelegt wird, können Sie einen API-Proxy so konfigurieren, dass die Nullroute ausgeführt wird, wenn ein Eintrag aus dem Cache bereitgestellt wird.

<RouteRule name="DoNothingUnlessTheCacheIsStale">
  <Condition>lookupcache.LookupCache-1.cachehit is true</Condition>
</RouteRule>

TargetEndpoint

Zeigt einen Client, der einen HTTP-Dienst aufruft. Die Anfrage durchläuft den Proxyendpunkt und dann den Zielendpunkt, bevor sie vom HTTP-Dienst verarbeitet wird. Die Antwort durchläuft den Zielendpunkt und dann den Proxyendpunkt, bevor sie an den Client zurückgegeben wird.

Ein TargetEndpoint ist die ausgehende Entsprechung eines ProxyEndpoints. Ein TargetEndpoint fungiert als Client an einen Backend-Dienst oder eine API. Sie sendet Anfragen und empfängt Antworten.

Ein API-Proxy benötigt keine TargetEndpoints. ProxyEndpoints können so konfiguriert werden, dass URLs direkt aufgerufen werden. Ein API-Proxy ohne TargetEndpoints enthält in der Regel einen ProxyEndpoint, der entweder einen Back-End-Dienst direkt aufruft oder einen Dienst konfiguriert, der Java oder JavaScript verwendet.

TargetEndpoint-Konfiguration

/targets/default.xml

Der TargetEndpoint definiert die ausgehende Verbindung von Apigee zu einem anderen Dienst oder einer anderen Ressource.

Hier ein Beispiel für eine TargetEndpoint-Konfiguration:

<TargetEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <SSLInfo/>
    <Authentication/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

Elemente der TargetEndpoint-Konfiguration

Ein TargetEndpoint kann ein Ziel auf eine der folgenden Arten aufrufen:

  • HTTPTargetConnection für HTTP- oder HTTPS-Aufrufe
  • LocalTargetConnection für die lokale Proxy-zu-Proxy-Verkettung

Konfigurieren Sie nur eines davon in einem TargetEndpoint.

Name Beschreibung Default Erforderlich?
TargetEndpoint
name Der Name des TargetEndpoint, der innerhalb der API-Proxykonfiguration eindeutig sein muss. Der Name des TargetEndPoint wird in der ProxyEndpoint RouteRule verwendet, um Anfragen für die ausgehende Verarbeitung zu leiten. Die Zeichen, die Sie im Namen verwenden dürfen, sind auf folgende Zeichen beschränkt: A-Za-z0-9._\-$ % – Ja
PreFlow Definiert die Richtlinien im PreFlow-Ablauf einer Anfrage oder Antwort. – Ja
Flows
Definiert die Richtlinien in den bedingten Abläufen einer Anfrage oder Antwort.
 – Ja
PostFlow
Definiert die Richtlinien im PostFlow-Ablauf einer Anfrage oder Antwort.
 – Ja
HTTPTargetConnection

Gibt mit den untergeordneten Elementen eine Backend-Ressourcen an, die über HTTP erreicht wird.

Wenn Sie HTTPTargetConnection verwenden, sollten Sie keine anderen Arten von Zielverbindungen (ScriptTarget oder LocalTargetConnection) konfigurieren.

Mit dem untergeordneten <Authentication>-Element können authentifizierte Aufrufe an Google-Dienste oder an benutzerdefinierte Dienste, die in bestimmten Google Cloud-Produkten ausgeführt werden, wie z. B. Cloud Functions und Cloud Run, ausgeführt werden. Die Verwendung des <Authentication>-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. Weitere Informationen finden Sie unter Verwendung des <Authentication>-Elements.
URL Definiert die Netzwerkadresse des Back-End-Dienstes, an den der TargetEndpoint Anfragenachrichten weiterleitet. – Nein
LoadBalancer

Definiert eine oder mehrere benannte TargetServer-Konfigurationen. Benannte TargetServer-Konfigurationen können für das Load-Balancing verwendet werden, um zwei oder mehr Endpunktkonfigurationsverbindungen zu definieren.

Sie können TargetServers auch verwenden, um API-Proxykonfigurationen aus konkreten Back-End-Dienst-Endpunkt-URLs zu entkoppeln.

 – Nein
Properties Eine Reihe optionaler HTTP-Konfigurationseinstellungen kann als Attribute einer <TargetEndpoint> definiert werden. – Nein
SSLInfo Definieren Sie optional TLS/SSL-Einstellungen für einen TargetEndpoint, um die TLS/SSL-Verbindung zwischen dem API-Proxy und dem Zieldienst zu steuern. Siehe TLS/SSL TargetEndpoint-Konfiguration. – Nein
LocalTargetConnection Mit ihren untergeordneten Elementen wird die Ressource angegeben, die lokal erreicht werden soll, um Netzwerkeigenschaften wie Load-Balancing und Nachrichtenprozessoren zu umgehen.

Zum Angeben der Zielressource fügen Sie entweder das untergeordnete APIProxy-Element (mit dem ProxyEndpoint-Element) oder das untergeordnete Element Pfad hinzu.

Weitere Informationen finden Sie unter API-Proxys zusammenhalten.

Wenn Sie LocalTargetConnection verwenden, konfigurieren Sie keine anderen Arten von Zielverbindungen (HTTPTargetConnection oder ScriptTarget).
APIProxy Gibt den Namen eines API-Proxys an, der als Ziel für Anfragen verwendet werden soll. Der Zielproxy muss sich in derselben Organisation und Umgebung befinden wie der Proxy, der Anfragen sendet. Das bietet eine Alternative zum Pfadelement. – Nein
ProxyEndpoint Wird mit APIProxy verwendet, um den Namen des ProxyEndpoint des Zielproxys anzugeben. – Nein
Path Gibt den Endpunktpfad eines API-Proxys an, der als Ziel für Anfragen verwendet werden soll. Der Zielproxy muss sich in derselben Organisation und Umgebung befinden wie der Proxy, der Anfragen sendet. Dies ist eine Alternative zur Verwendung von APIProxy. – Nein
FaultRules
Definiert, wie der TargetEndpoint auf einen Fehler reagiert. Eine Fehlerregel gibt zwei Elemente an:
  • Eine Bedingung, die den Fehler angibt, der auf Grundlage der vordefinierten Kategorie, Unterkategorie oder Name des Fehlers verarbeitet werden soll
  • Eine oder mehrere Richtlinien, die das Verhalten der Fehlerregel für die entsprechende Bedingung definieren

Siehe Umgang mit Fehlern.

 – Nein
DefaultFaultRule

Behandelt alle Fehler (System, Transport, Messaging oder Richtlinie), die nicht explizit von einer anderen FaultRule behandelt werden.

Siehe Umgang mit Fehlern.

 – Nein

Verwendung des <Authentication>-Elements

Die Verwendung des <Authentication>-Elements in <TargetEndpoint> ist identisch mit der Nutzung des <Authentication>-Elements in der ServiceCallout-Richtlinie. Sowohl für <TargetEndpoint> als auch für ServiceCallout ist <Authentication> ein Unterelement von <HttpTargetConnection>. Weitere Informationen finden Sie unter Authentifizierungselement in der ServiceCallout-Richtlinienreferenz.

Fehlerreferenz für das <Authentication>-Element

Wenn Sie das <Authentication>-Element verwenden, finden Sie mögliche Fehlermeldungen und Tipps zur Fehlerbehebung bei Bereitstellungs- und Laufzeitfehlern im Abschnitt Fehler der Dokumentation zu ServiceCallout.

Beispiele für das <Authentication>-Element

Im folgenden Beispiel wird gezeigt, wie ein in Cloud Run bereitgestellter Dienst als Ziel mithilfe des Authentication-Elements aufgerufen wird, um ein OpenID Connect-Token zu generieren, das zur Authentifizierung des Aufrufs erforderlich ist: 

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
      <Properties/>
      <URL>https://cloudrun-hostname.a.run.app/test</URL>
      <Authentication>
          <GoogleIDToken>
             <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
          </GoogleIDToken>
     </Authentication>
  </HTTPTargetConnection>
</TargetEndpoint>

Das folgende Beispiel zeigt, wie ein TargetService aufgerufen wird, der mit dem Authentication-Element auf Cloud Run verweist, um ein OpenID Connect-Token zu generieren, das zur Authentifizierung des Aufrufs erforderlich ist. Das Element HeaderName fügt das generierte Inhabertoken einem Header namens X-Serverless-Authorization hinzu, der an das Zielsystem gesendet wird. Der Authorization-Header, falls vorhanden, bleibt unverändert und wird auch in der Anfrage gesendet. 

<TargetEndpoint name="TargetEndpoint-1">
   <HTTPTargetConnection>
     <Authentication>
        <HeaderName>X-Serverless-Authorization</HeaderName>
        <GoogleIDToken>
            <Audience ref="flow.variable.audience">https://cloudrun-hostname.a.run.app</Audience>
        </GoogleIDToken>
     </Authentication>
      <LoadBalancer>
         <Server name="cloud-run-target" />
      </LoadBalancer>
   </HTTPTargetConnection>
</TargetEndpoint>

Das nächste Beispiel zeigt, wie ein TargetService aufgerufen wird, der auf den Secret Manager-Dienst von Google verweist. In diesem Beispiel ist das GoogleAccessToken-Element so konfiguriert, dass ein Google-Authentifizierungstoken generiert wird, um die Zielanfrage zu authentifizieren: 

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

Das folgende Beispiel zeigt, wie Sie die Zielgruppe des GoogleIDToken automatisch festlegen. Wenn useTargetUrl true ist und die referenzierte Variable nicht in eine gültige Variable aufgelöst wird, wird die URL des Ziels (ohne Abfrageparameter) als Zielgruppe verwendet. Angenommen, der Anfragepfad lautet /foobar und die TargetServer-URL ist https://xyz.com. In diesem Fall wird die Zielgruppe des GoogleIDToken automatisch auf https://xyz.com/foobar festgelegt. 

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience ref='myvariable' useTargetUrl="true"/>
      </GoogleIDToken>
    </Authentication>
    <LoadBalancer>
      <Server name="TS" />
    </LoadBalancer>
  </HTTPTargetConnection>
</TargetEndpoint>

TLS/SSL-TargetEndpoint-Konfiguration

TargetEndpoints müssen häufig HTTPS-Verbindungen mit heterogenen Back-End-Infrastruktur verwalten. Aus diesem Grund werden verschiedene TLS/SSL-Konfigurationseinstellungen unterstützt.

Elemente der TLS/SSL-TargetEndpoint-Konfiguration

Name Beschreibung Default Erforderlich?
SSLInfo
Enabled Gibt an, ob TLS/SSL für den Endpunkt aktiviert ist. Der Standardwert ist true, wenn <URL> das HTTPS-Protokoll angibt, und false, wenn <URL> HTTP angibt. true, wenn <URL> HTTPS angibt Nein
Enforce

Erzwingt eine strenge SSL-Verbindung zwischen Apigee und dem Ziel-Backend.

Wenn dieser Wert auf true gesetzt ist, schlagen Verbindungen bei Zielen mit ungültigen Zertifikaten, abgelaufenen Zertifikaten, selbst signierten Zertifikaten, Zertifikaten mit nicht übereinstimmenden Hostnamen sowie Zertifikaten mit einer nicht vertrauenswürdigen Stammzertifizierungsstelle fehl. Der Fehlercode 4xx oder 5xx wird zurückgegeben.

Wenn nicht festgelegt oder auf false festgelegt, hängt das Ergebnis von Verbindungen zu Ziel-Back-Ends mit problematischen Zertifikaten von der Einstellung von <IgnoreValidationErrors> ab (siehe unten). Eine Erfolgsantwort (2xx) kann unter bestimmten Bedingungen auftreten, wenn <IgnoreValidationErrors> auf true festgelegt ist.

 false Nein
TrustStore Einen Schlüsselspeicher mit vertrauenswürdigen Serverzertifikaten. – Nein
ClientAuthEnabled Eine Einstellung, die die ausgehende Clientauthentifizierung aktiviert (2 Wege von TLS/SSL) false Nein
KeyStore Einen Schlüsselspeicher, der private Schlüssel für die ausgehende Clientauthentifizierung verwendet – Ja (wenn ClientAuthEnabled "true") ist
KeyAlias Der Schlüsselalias des privaten Schlüssels, der für die ausgehende Clientauthentifizierung verwendet wird – Ja (wenn ClientAuthEnabled "true") ist
IgnoreValidationErrors

Gibt an, ob Validierungsfehler ignoriert werden. Wenn das Backend-System SNI nutzt und ein Zertifikat mit einem Subjekt-DN (Subject Distinguished Name) zurückgibt, der nicht mit dem Hostnamen übereinstimmt, kann der Fehler nicht ignoriert werden und die Verbindung schlägt fehl.

Hinweis: Wenn <Enforce> auf true gesetzt ist, wird der Wert von <IgnoreValidationErrors> ignoriert.

 false Nein
Ciphers

Unterstützte Chiffren für ausgehende TLS/SSL. Wenn keine Chiffren angegeben sind, sind alle für die JVM verfügbaren Chiffren erlaubt.

Fügen Sie die folgenden Elemente hinzu, um die Chiffren einzuschränken:


<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>
– Nein
Protocols

Unterstützte Protokolle für ausgehendes TLS/SSL. Wenn keine Protokolle angegeben sind, sind alle für die JVM verfügbaren Protokolle zulässig.

Wenn Sie Protokolle einschränken möchten, geben Sie sie explizit an. So lassen Sie beispielsweise nur TLS v1.2 oder TLS v1.3 zu:


<Protocols>
 <Protocol>TLSv1.2</Protocol>
 <Protocol>TLSv1.3</Protocol>
</Protocols>
– Nein

Beispiel für TargetEndpoint mit aktivierter ausgehender Client-Authentifizierung

<TargetEndpoint name="default">
  <HttpTargetConnection>
        <URL>https://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
  </HttpTargetConnection>
</TargetEndpoint>

Eine ausführliche Anleitung finden Sie unter Optionen zum Konfigurieren von TLS.

Ablaufvariablen zum dynamischen Festlegen von TLS/SSL-Werten verwenden

Sie können auch TLS/SSL-Details dynamisch festlegen, um flexible Laufzeitanforderungen zu unterstützen. Wenn Ihr Proxy zum Beispiel mit zwei möglichen Zielen verbunden ist (ein Testziel und ein Produktionsziel), können Sie dafür sorgen, dass Ihr API-Proxy programmatisch ermittelt, welche Umgebung aufgerufen wird, und Verweise dynamisch auf den entsprechenden Schlüsselspeicher und Truststore festlegen. Im Apigee-Community-Artikel Dynamic SSLInfo for TargetEndpoint mit Variablenreferenz wird dieses Szenario ausführlicher beschrieben und enthält bereitstellbare API-Proxy-Beispiele.

Im folgenden Beispiel wird gezeigt, wie das Tag <SSLInfo> in einer TargetEndpoint-Konfiguration festgelegt wird. Die Werte können zur Laufzeit bereitgestellt werden, beispielsweise über die Richtlinien "Java-Callout", "JavaScript" oder "Assign Message". Verwenden Sie die Nachrichtenvariablen, die die Werte enthalten, die Sie festlegen möchten.

Variablen sind nur in folgenden Elementen zulässig.

. 
<SSLInfo>
    <Enabled>{myvars.ssl.enabled}</Enabled>
    <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
    <KeyStore>{myvars.ssl.keystore}</KeyStore>
    <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
    <TrustStore>{myvars.ssl.trustStore}</TrustStore>
</SSLInfo>

Referenzen verwenden, um TLS/SSL-Werte dynamisch festzulegen

Wenn Sie einen TargetEndpoint mit HTTPS konfigurieren, müssen Sie den Fall berücksichtigen, wenn das TLS/SSL-Zertifikat abläuft, oder bei einer Änderung der Systemkonfiguration das Zertifikat aktualisieren.

Weitere Informationen finden Sie unter Abgelaufene Zertifikate verarbeiten.

Sie können den TargetEndpoint jedoch optional so konfigurieren, dass er einen Verweis auf den Keystore oder Truststore verwendet. Der Vorteil einer Referenz besteht darin, dass Sie die Referenz aktualisieren können, um auf einen anderen Keystore oder Truststore zu verweisen, um das TLS/SSL-Zertifikat zu aktualisieren, ohne die Nachrichtenprozessoren neu starten zu müssen.

Im Folgenden sehen Sie ein Beispiel für einen TargetEndpoint, der einen Verweis auf den Schlüsselspeicher verwendet:

<SSLInfo>
  <Enabled>true</Enabled>
  <ClientAuthEnabled>false</ClientAuthEnabled>
  <KeyStore>ref://keystoreref</KeyStore>
  <KeyAlias>myKeyAlias</KeyAlias>
</SSLInfo>

Verwenden Sie den folgenden POST API-Aufruf, um die Referenz namens keystoreref zu erstellen:

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>'

Dabei ist $TOKEN auf Ihr OAuth 2.0-Zugriffstoken festgelegt, wie unter OAuth 2.0-Zugriffstoken abrufen beschrieben. Informationen zu den in diesem Beispiel verwendeten curl-Optionen finden Sie unter curl verwenden. Eine Beschreibung der verwendeten Umgebungsvariablen finden Sie unter Umgebungsvariablen für Apigee API-Anfragen festlegen.

Die Referenz gibt den Namen des Schlüsselspeichers und seinen Typ an.

Verwenden Sie den folgenden GET API-Aufruf, um die Referenz aufzurufen:

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

Dabei ist $TOKEN auf Ihr OAuth 2.0-Zugriffstoken festgelegt. Weitere Informationen hierzu finden Sie unter OAuth 2.0-Zugriffstoken abrufen. Informationen zu den in diesem Beispiel verwendeten curl-Optionen finden Sie unter curl verwenden. Eine Beschreibung der verwendeten Umgebungsvariablen finden Sie unter Umgebungsvariablen für Apigee API-Anfragen festlegen.

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

Dabei ist $TOKEN auf Ihr OAuth 2.0-Zugriffstoken festgelegt. Weitere Informationen hierzu finden Sie unter OAuth 2.0-Zugriffstoken abrufen. Informationen zu den in diesem Beispiel verwendeten curl-Optionen finden Sie unter curl verwenden. Eine Beschreibung der verwendeten Umgebungsvariablen finden Sie unter Umgebungsvariablen für Apigee API-Anfragen festlegen.

Verwenden Sie den folgenden PUT-Aufruf, um später die Referenz so zu ändern, dass sie auf einen anderen Schlüsselspeicher verweist, damit der Alias denselben Namen hat:

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'

Dabei ist $TOKEN auf Ihr OAuth 2.0-Zugriffstoken festgelegt. Weitere Informationen hierzu finden Sie unter OAuth 2.0-Zugriffstoken abrufen. Informationen zu den in diesem Beispiel verwendeten curl-Optionen finden Sie unter curl verwenden. Eine Beschreibung der verwendeten Umgebungsvariablen finden Sie unter Umgebungsvariablen für Apigee API-Anfragen festlegen.

TargetEndpoint mit Ziel-Load-Balancing

TargetEndpoints unterstützt Load-Balancing über mehrere benannte TargetServer mit drei Load-Balancing-Algorithmen.

Eine ausführliche Anleitung finden Sie unter Load-Balancing für Backend-Server.

IntegrationEndpoint

Ein IntegrationEndpoint ist ein TargetEndpoint, der speziell Apigee-Integrationen ausführt. Wenn Sie einen IntegrationEndpoint konfiguriert haben, sendet Apigee das request-Objekt zur Ausführung an die integrierte Platform von Apigee. Neben dem Konfigurieren des IntegrationEndpoint müssen Sie zum Ausführen Ihrer Integration auch die SetIntegrationRequest-Richtlinie in Ihren Proxy-Ablauf einfügen.

Sie können die Integration so konfigurieren, dass sie entweder synchron oder asynchron ausgeführt wird. Legen Sie dazu das Element <AsyncExecution> in der IntegrationEndpoint-Konfiguration fest. Weitere Informationen finden Sie unter Synchrone und asynchrone Ausführung. Nach dem Ausführen der Integration speichert Apigee die Antwort in der Antwortnachricht.

IntegrationEndpoint konfigurieren

Wenn Sie einen Integrationsendpunkt als TargetEndpoint konfigurieren möchten, fügen Sie das Integrationselement zu Ihrer ProxyEndpoint-Deklaration hinzu. Hier ein Beispiel für eine ProxyEndpoint-Deklaration:

<ProxyEndpoint name="default">
    <Description/>
    <FaultRules/>
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>my-set-integration-request-policy</Name>
            </Step>
        </Request>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow"/>
    <HTTPProxyConnection>
        <BasePath>/integration-endpoint-test</BasePath>
        <Properties/>
    </HTTPProxyConnection>
    <RouteRule name="default">
        <IntegrationEndpoint>my-int-endpoint</IntegrationEndpoint>
    </RouteRule>
</ProxyEndpoint>

In der ProxyEndpoint-Beispieldeklaration führt Apigee die folgenden Aufgaben aus:

  1. Führt im PreFlow die Richtlinie namens my-set-integration-request-policy aus, die das Integrationsanfrageobjekt und die Integrationsablaufvariablen festlegt.
  2. Verwendet my-int-endpoint als Zielendpunkt, wie in RouteRule angegeben.
  3. Liest das von my-set-integration-request-policy erstellte Integrationsanfrageobjekt.
  4. Sendet die Anfrage an die Integration-Plattform von Apigee. Dazu werden das Anfrageobjekt und die Ablaufvariablen verwendet, die durch die SetIntegrationRequest-Richtlinie festgelegt werden.
  5. Speichert die Antwort der Integration in der Antwortnachricht.

Die XML-Datei mit der Deklaration <IntegrationEndpoint> ist im Verzeichnis APIGEE_BUNDLE_DIRECTORY/apiproxy/integration-endpoints/ verfügbar. Wenn Sie Ihren API-Proxy mit der Option Develop > API Proxies > CREATE NEW > Integration target erstellen, speichert Apigee die Deklaration in der Datei /apiproxy/integration-endpoints/default.xml. Wenn Sie den XML-Code der Integrationsendpunkte über die UI erstellen, können Sie einen benutzerdefinierten Namen für die XML-Datei angeben.

Das folgende Beispiel zeigt die Deklaration des <IntegrationEndpoint>-Elements in der XML-Datei:

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>false</AsyncExecution>
</IntegrationEndpoint>

Elemente der IntegrationEndpoint-Konfiguration

Name Beschreibung Default Erforderlich?
IntegrationEndpoint
name Der Name des IntegrationEndpoint. Die Zeichen, die Sie im Namen verwenden können, sind auf folgende Zeichen beschränkt: A-Za-z0-9._\-$ % – Ja
AsyncExecution Ein boolescher Wert, mit dem angegeben wird, ob die Integration im synchronen oder asynchronen Modus ausgeführt werden soll. Weitere Informationen finden Sie unter Synchrone und asynchrone Ausführung. falsch Nein

Synchrone und asynchrone Ausführung

Sie können die Integration so konfigurieren, dass sie entweder im synchronen oder im asynchronen Modus ausgeführt wird. Informationen zum Unterschied zwischen synchronen und asynchronen Ausführungsmodi finden Sie unter <AsyncExecution>.

Verwenden Sie das Element <AsyncExecution> in </IntegrationEndpoint>, um die synchrone oder asynchrone Ausführung anzugeben. Wenn <AsyncExecution> auf true festgelegt ist, wird die Integration asynchron ausgeführt. Wenn Sie false festlegen, wird die Integration synchron ausgeführt.

Im folgenden Beispiel wird AsyncExecution auf true festgelegt:

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>true</AsyncExecution>
</IntegrationEndpoint>

Richtlinien

Das Verzeichnis /policies in einem API-Proxy enthält alle Richtlinien, die an Abläufe im API-Proxy angehängt werden können.

Elemente der Richtlinienkonfiguration

Name Beschreibung Default Erforderlich?
Policy
name

Der interne Name der Richtlinie. Folgende Zeichen sind im Namen zulässig: A-Za-z0-9._\-$ %. Die Apigee-Benutzeroberfläche erzwingt jedoch zusätzliche Einschränkungen wie das Entfernen von nicht alphanumerischen Zeichen.

Optional können Sie mithilfe des Elements <DisplayName> die Richtlinie im Proxy-UI-Editor von Apigee mit einem anderen Natural Language-Namen mit Labels versehen.

 – Ja
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 Nein
continueOnError

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

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

 false Nein
async

Wenn dieser Wert auf true gesetzt ist, wird die Richtlinienausführung auf einen anderen Thread übertragen, sodass der Hauptthread weitere Anfragen verarbeiten kann. Wenn die Offline-Verarbeitung abgeschlossen ist, wird der Hauptthread zurückgegeben und die Verarbeitung des Nachrichtenablaufs abgeschlossen. In einigen Fällen verbessert die Einstellung von asynchron auf true die API-Proxy-Leistung. Eine übermäßige Verwendung kann jedoch die Leistung beeinträchtigen, wenn zu viele Thread-Switches erzeugt wird.

Informationen zur Verwendung des asynchronen Verhaltens in API-Proxys finden Sie unter JavaScript-Objektmodell.

 false Nein

Richtlinienbindung

Die folgende Abbildung zeigt die Ausführungssequenz der API-Proxys:

zeigt einen Client, der einen HTTP-Dienst aufruft. Die Anfrage geht an den ProxyEndpoint und TargetEndpoint, die jeweils Schritte enthalten, die Richtlinien auslösen. Nachdem der HTTP-Dienst die Antwort zurückgegeben hat, wird die Antwort vom TargetEndpoint verarbeitet. Anschließend wird das ProxyEndoping zurückgegeben, bevor an den Client zurückgegeben wird. Wie bei der Anfrage wird die Antwort von Richtlinien in Schritten verarbeitet.

Wie oben gezeigt:

Richtlinien werden als Verarbeitungsschritte an Abläufe angehängt. Mit dem Namen der Richtlinie wird auf die Richtlinie verwiesen, die als Verarbeitungsschritt erzwungen werden soll. Richtlinienanhänge haben folgendes Format:

<Step><Name>MyPolicy</Name></Step>

Richtlinien werden in der Reihenfolge erzwungen, in der sie einem Ablauf zugeordnet sind. Beispiel:

<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>

Elemente der Konfiguration der Richtlinienanhänge

Name Beschreibung Default Erforderlich?
Step
Name Der Name der Richtlinie, die von dieser Schrittdefinition ausgeführt werden soll. – Ja
Condition Eine bedingte Anweisung, die bestimmt, ob die Richtlinie erzwungen wird. Wenn eine Richtlinie mit einer Bedingung verknüpft ist, wird die Richtlinie nur ausgeführt, wenn die Anweisung der Bedingung als "true" ausgewertet wird. – Nein

Abläufe

ProxyEndpoint und TargetEndpoint definieren eine Pipeline für die Verarbeitung von Anfragen und Antworten. Eine Verarbeitungspipeline besteht aus einem Anfrageablauf und einem Antwortablauf. Jeder Anfrage- und Antwortablauf ist in einen PreFlow, einen oder mehrere optionale bedingte oder benannte Abläufe, und einen PostFlow unterteilt.

  • PreFlow: Wird immer ausgeführt. Wird vor allen bedingten Abläufen ausgeführt.
  • PostFlow: Wird immer ausgeführt. Wird nach allen bedingten Abläufen ausgeführt.

Darüber hinaus können Sie dem ProxyEndpoint einen PostClientFlow hinzufügen, der ausgeführt wird, nachdem die Antwort an die anfragende Client-App zurückgegeben wurde. Nur die MessageLogging-Richtlinie kann an diesen Ablauf angehängt werden. PostClientFlow reduziert die Latenz des API-Proxys und stellt Informationen für Logging zur Verfügung, die erst berechnet werden, wenn die Antwort an den Client zurückgegeben wurde, z. B. client.sent.start.timestamp und client.sent.end.timestamp. Der Ablauf wird hauptsächlich für die Messung des Zeitintervalls zwischen dem Start- und Endzeitstempel der Antwortnachricht verwendet.

Hier ein Beispiel für einen PostClientFlow mit angehängter Nachrichten-Logging-Richtlinie:

...
  <PostFlow name="PostFlow">
      <Request/>
      <Response/>
  </PostFlow>
  <PostClientFlow>
      <Request/>
      <Response>
          <Step>
              <Name>Message-Logging-1</Name>
          </Step>
      </Response>
  </PostClientFlow>
  ...

Die API-Proxy-Verarbeitungspipeline führt Flows in der folgenden Sequenz aus:

Anfrage-Pipeline:

  1. Proxyanfrage-PreFlow
  2. Proxyanfrage für bedingte Abläufe (optional)
  3. Proxyanfrage PostFlow
  4. Zielanfrage PreFlow
  5. Zielanfrage für bedingte Abläufe (optional)
  6. Zielanfrage PostFlow

Antwort-Pipeline:

  1. Zielantwort PreFlow
  2. Zielantwort für bedingte Abläufe (optional)
  3. Zielantwort PostFlow
  4. Proxyantwort PreFlow
  5. Proxyantwort für bedingte Abläufe (optional)
  6. Proxyantwort PostFlow
  7. PostClientFlow-Antwort (optional)

Nur Abläufe mit Richtlinienanhängen müssen in ProxyEndpoint- oder TargetEndpoint-Konfigurationen konfiguriert werden. PreFlow und PostFlow müssen nur in einer ProxyEndpoint- oder TargetEndpoint-Konfiguration angegeben werden, wenn eine Richtlinie während der PreFlow- oder PostFlow-Verarbeitung erzwungen werden muss.

Im Gegensatz zu bedingten Abläufen ist die Reihenfolge von PreFlow- und PostFlow-Elementen nicht wichtig. Der API-Proxy wird immer an der entsprechenden Stelle in der Pipeline ausgeführt, unabhängig davon, wo sie in der Endpunktkonfiguration angezeigt werden.

Bedingte Abläufe

ProxyEndpoints und TargetEndpoints unterstützen eine unbegrenzte Anzahl bedingter Abläufe (auch benannte Abläufe genannt).

Der API-Proxy testet die im bedingten Ablauf angegebene Bedingung. Wenn die Bedingung erfüllt wird, werden die Verarbeitungsschritte im bedingten Ablauf vom API-Proxy ausgeführt. Wird die Bedingung nicht erfüllt, werden die Verarbeitungsschritte im bedingten Ablauf umgangen. Bedingte Abläufe werden in der im API-Proxy definierten Reihenfolge ausgewertet und der erste, dessen Bedingung erfüllt ist, wird ausgeführt.

Durch die Definition bedingter Abläufe können Sie die Verarbeitungsschritte in einem API-Proxy basierend auf Folgendem anwenden:

  • Anfrage-URI
  • HTTP-Verb (GET/PUT/POST/DELETE)
  • Wert eines Abfrageparameters, Headers und Formularparameters
  • Viele andere Arten von Bedingungen

Der folgende bedingte Ablauf gibt beispielsweise an, dass er nur ausgeführt wird, wenn der Anfrageressourcenpfad /accesstoken ist. Jede eingehende Anfrage mit dem Pfad /accesstoken führt dazu, dass dieser Ablauf zusammen mit allen Richtlinien ausgeführt wird, die an den Ablauf angehängt sind. Wenn der Anfragepfad nicht das Suffix /accesstoken enthält, wird der Ablauf nicht ausgeführt (obwohl ein anderer bedingter Ablauf möglich ist).

<Flows>
  <Flow name="TokenEndpoint">
    <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
    <Request>
      <Step>
        <Name>GenerateAccessToken</Name>
      </Step>
    </Request>
  </Flow>
</Flows>

Elemente der Ablaufkonfiguration

Name Beschreibung Default Erforderlich?
Flow Eine Anfrage oder eine Antwortverarbeitungspipeline, die von einem ProxyEndpoint oder TargetEndpoint definiert wird
Name Der eindeutige Name des Ablaufs. – Ja
Condition Eine bedingte Anweisung, die eine oder mehrere Variablen auswertet, die als true oder false ausgewertet werden. Alle Abläufe mit Ausnahme der vordefinierten PreFlow- und PostFlow-Typen müssen eine Bedingung für ihre Ausführung definieren. – Ja
Request Die mit der Verarbeitung von Anfragenachrichten verknüpfte Pipeline – Nein
Response Die Pipeline, die mit der Verarbeitung von Antwortnachrichten verknüpft ist – Nein

Schrittverarbeitung

Die sequenzielle Reihenfolge bedingter Abläufe wird von Apigee erzwungen. Bedingte Abläufe werden von oben nach unten ausgeführt. Der erste bedingte Ablauf, dessen Bedingung true erfüllt, wird ausgeführt und nur ein bedingter Ablauf wird ausgeführt.

Beispiel: In der folgenden Ablaufkonfiguration führt jede eingehende Anfrage, die nicht das Pfadsuffix /first oder /second enthält, ThirdFlow aus. Dabei wird die Richtlinie Return404 ausgeführt.

<Flows>
  <Flow name="FirstFlow">
    <Condition>proxy.pathsuffix MatchesPath "/first"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="SecondFlow">
    <Condition>proxy.pathsuffix MatchesPath "/second"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
      <Step><Name>SecondPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="ThirdFlow">
    <Request>
      <Step><Name>Return404</Name></Step>
    </Request>
  </Flow>
</Flows>

Ressourcen

"Ressourcen" (Ressourcendateien zur Verwendung in API-Proxys) sind Skripts, Code und XSL-Transformationen, die Abläufen mithilfe von Richtlinien hinzugefügt werden können. Diese werden im Abschnitt Scripts des API-Proxy-Editors in der Apigee-Benutzeroberfläche angezeigt.

Informationen zu den unterstützten Ressourcentypen finden Sie unter Ressourcen verwalten.

Ressourcen können in einem API-Proxy, in einer Umgebung oder in einer Organisation gespeichert werden. In jedem Fall wird in einer Richtlinie mit dem Namen auf eine Ressource verwiesen. Zur Auflösung des Namens bewegt sich Apigee von der API-Proxy in die Umgebung und zur Organisationsebene.

Eine auf Organisationsebene gespeicherte Ressource kann über Richtlinien in jeder Umgebung referenziert werden. Eine auf der Umgebungsebene gespeicherte Ressource kann von den Richtlinien in dieser Umgebung referenziert werden. Eine auf API-Proxyebene gespeicherte Ressource kann nur von Richtlinien in diesem API-Proxy referenziert werden.