Bedingungen mit Ablaufvariablen

Als Nächstes verwenden wir den regulären Ausdruck „[abc]“ für „Gruppierungen“. Er entspricht dem Zeichen „a“, „b“ oder „c“.

<Condition>(proxy.pathsuffix JavaRegex "/[cbr]at")</Condition>

API-Aufruf:

GET http://artomatic-test.apigee.net/matchtest/cat

Wird die Richtlinie ausgeführt? Ja. Wir verwenden hier reguläre Ausdrücke und der Ausdruck „[cbr]“ entspricht einem „c“, „b“ oder „r“. Diese Aufrufe sind auch Übereinstimmungen:

GET http://artomatic-test.apigee.net/matchtest/bat

GET http://artomatic-test.apigee.net/matchtest/rat

Dies ist jedoch keine Übereinstimmung:

GET http://artomatic-test.apigee.net/matchtest/mat

Frage: Berücksichtigt der JavaRegex-Operator die Groß-/Kleinschreibung?

Ja. Angenommen, Sie haben eine Bedingung wie diese:

<Condition>(proxy.pathsuffix JavaRegex "/ca?t")</Condition>

API-Aufruf:

GET http://artomatic-test.apigee.net/matchtest/cat

Wird die Richtlinie ausgeführt? Ja, der Regex stimmt mit null oder einem der vorhergehenden Zeichen überein, also „a“.

API-Aufruf:

GET http://artomatic-test.apigee.net/matchtest/cAt

Frage: Wird die Richtlinie ausgeführt?

Nein, weil das großgeschriebene „A“ nicht mit dem kleingeschriebenen „a“ übereinstimmt.

MatchesPath

Der Operator MatchesPath kann auch so angegeben werden: „~/”. Sieht etwas wie die Operatoren Matches (~) und JavaRegex (~~) aus. MatchesPath ist jedoch völlig anders.

Beachten Sie, dass dieser Operator einen Pfad als eine Zusammensetzung aus verschiedenen Teilen betrachtet. Wenn der Pfad also /animals/cats/wild lautet, können Sie sich den Pfad als eine Zusammensetzung aus den Teilen „/animals“, „/cats“ und „/wild“ vorstellen.

Mit dem Operator MatchesPath können Sie zwei Platzhalterschreibweisen verwenden: ein einzelnes Sternchen (*) und ein doppeltes Sternchen (**). Das einzelne Sternchen entspricht einem Pfadelement. Das doppelte Sternchen entspricht einem oder mehreren Pfadelementen.

Sehen wir uns ein Beispiel an. In diesem Beispiel testen wir die Variable proxy.pathsuffix, eine integrierte Variable in Edge, die das Pfadsuffix der Anfrage speichert. Sie können jedoch den Wert einer beliebigen Ablaufvariable testen, die einen String enthält.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/*")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Frage: Welches Proxypfad-Suffix verursacht die Ausführung von SomePolicy?

API-Aufruf:

GET http://artomatic-test.apigee.net/matchtest/animals

Frage: Wird die Richtlinie ausgeführt?

Nein, weil für die Bedingung ein weiteres Pfadelement nach „/animals“ erforderlich ist, das durch „/*“ angegeben wird.

API-Aufruf:

GET http://artomatic-test.apigee.net/matchtest/animals/

Wird die Richtlinie ausgeführt? Ja, der Pfad enthält ein weiteres Pfadelement (der Teil nach „/animals/“), ist aber leer.

API-Aufruf:

GET http://artomatic-test.apigee.net/matchtest/animals/cats

Wird die Richtlinie ausgeführt? Ja, weil der Pfad eindeutig ein Element („/cats“) enthält nach „/animals“

API-Aufruf:

GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild

Frage: Wird die Richtlinie ausgeführt?

Nein, weil das einzelne Sternchen nur mit einem Pfadelement übereinstimmt und diese API mehrere Elemente nach „/animals“ enthält.

Verwenden wir jetzt das doppelte Sternchen:

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/**")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Frage: Welches Proxypfad-Suffix verursacht die Ausführung von SomePolicy?

API-Aufruf:

GET http://artomatic-test.apigee.net/matchtest/animals

Wird die Richtlinie ausgeführt? Nein, weil für die Bedingung mindestens ein nachfolgendes Pfadelement erforderlich ist angegeben durch "/**".

API-Aufruf:

GET http://artomatic-test.apigee.net/matchtest/animals/

Wird die Richtlinie ausgeführt?

Ja, der Pfad enthält ein weiteres Pfadelement (der Teil nach „/animals/“), ist aber leer.

API-Aufruf:

GET http://artomatic-test.apigee.net/matchtest/animals/cats

Wird die Richtlinie ausgeführt?

Ja, weil der Pfad mindestens ein Element enthält, das nach „/animals“ kommt.

API-Aufruf:

GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild

Wird die Richtlinie ausgeführt?

Ja, weil der Pfad mehr als ein Element hinter „/animals“ enthält.

Sternchen kombinieren

Sie können Kombinationen aus einem einzelnen Sternchen (*) und doppelten Sternchen (**) verwenden, um den Pfadabgleich zu verfeinern.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/*/wild/**")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

API-Aufruf:

Alle folgenden API-Aufrufe liefern eine Übereinstimmung:

GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild/

und

GET http://artomatic-test.apigee.net/matchtest/animals/dogs/wild/austrailian

und

GET http://artomatic-test.apigee.net/matchtest/animals/birds/wild/american/finches

API-Ressourcen

RESTful-Dienste sind Sammlungen von API-Ressourcen. Eine API-Ressource ist ein URI-Pfadfragment, das eine Entität identifiziert, auf die Entwickler durch Aufrufen Ihrer API zugreifen können. Wenn Ihr Dienst beispielsweise Wetterberichte und Wettervorhersagen bereitstellt, kann Ihr Backend-Dienst zwei API-Ressourcen definieren:

• http://mygreatweatherforecast.com/reports
• http://mygreatweatherforecast.com/forecasts

Wenn Sie einen API-Proxy erstellen (wie unter Ersten API-Proxy erstellen gezeigt), müssen Sie zumindest eine Alias-Basis-URL erstellen, die Ihrem Backend-Dienst zugeordnet ist. Beispiele:

An dieser Stelle können Sie mit beiden URLs API-Aufrufe an Ihr Backend senden. Wenn Sie jedoch die API-Proxy-URL verwenden, wird es interessant.

Zusätzlich zu den API-Analysen, die Edge beim Verwenden des API-Proxys zu erfassen beginnt, können Proxys Sie können auch bedingte Datenflüsse definieren, die den Ressourcen in Ihrem Back-End zugeordnet sind. Im Wesentlichen: „Wenn ein GET-Aufruf an die /reports-Ressource eingeht, sollte Edge eine Aktion ausführen.“

In der folgenden Abbildung ist der Verhaltensunterschied zwischen zwei URLs zu sehen, die letztendlich auf dasselbe Backend zugreifen. Eine ist die Ressourcen-URL ohne Proxy, die andere ein Edge-API-Proxy mit einem bedingten Fluss zur selben Back-End-Ressource. Weitere Informationen zu bedingten Abläufen finden Sie weiter unten.

So werden API-Proxys zu bestimmten Backend-Ressourcen zugeordnet

Wenn eine API-Proxy-URL der Basis-URL des Backend-Dienstes (beim Erstellen des Proxys) zugeordnet ist, können Sie bedingte Abläufe bestimmten Ressourcen zuordnen, wie z. B. die bereits erwähnten Ressourcen /reports und /forecasts.

Angenommen, Sie möchten, dass Edge /reportsetwas unternimmt/forecasts, wenn Aufrufe an die Ressource /reports oder /forecasts erfolgen. Zu diesem Zeitpunkt wird Edge noch nicht mitgeteilt, und auf Aufrufe an diese Ressourcen warten sollte. Dazu verwenden Sie Bedingungen. In Ihrem Edge API-Proxy können Sie bedingte Datenflüsse für /reports und /forecasts. Zu Konzeptzwecken veranschaulicht die folgende API-Proxy-XML, wie diese Bedingungen aussehen könnten.

<Flows>
    <Flow name="reports">
        <Description/>
        <Request/>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
    </Flow>
    <Flow name="forecasts">
        <Description/>
        <Request/>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/forecasts") and (request.verb = "GET")</Condition>
    </Flow>
</Flows>

Diese Bedingungen geben vor: „Wenn eine GET-Anfrage mit /reports und /forecasts in der URL eingeht, führt Edge das aus, was Sie als API-Entwickler über die Richtlinien vorgeben, die Sie mit diesen Abläufen verknüpfen“.

Hier sehen Sie ein Beispiel dafür, wie Sie Edge mitteilen, was zu tun ist, wenn eine Bedingung erfüllt ist. Wenn in der folgenden API-Proxy-XML eine GET-Anfrage an https://yourorg-test.apigee.net/mygreatweatherforecast/reports gesendet wird, führt Edge in der Antwort die Richtlinie „XML-zu-JSON-1“ aus.

<Flows>
    <Flow name="reports">
        <Description/>
        <Request/>
        <Response>
            <Step>
                <Name>XML-to-JSON-1</Name>
            </Step>
        </Response>
        <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
</Flow>

Zusätzlich zu diesen optionalen bedingten Abläufen enthält jeder API-Proxy auch zwei Standardabläufe: einen <PreFlow>, der vor den bedingten Abläufen ausgeführt wird, und einen <PostFlow>, der nach den bedingten Abläufen ausgeführt wird. Diese sind nützlich, um Richtlinien auszuführen, wenn ein beliebiger Aufruf an einen API-Proxy erfolgt. Wenn Sie beispielsweise den API-Schlüssel einer Anwendung bei jedem Aufruf prüfen möchten, können Sie unabhängig vom Zugriff auf die Backend-Ressource eine Richtlinie zum Prüfen des API-Schlüssels im <PreFlow> bereitstellen. Weitere Informationen zu Abläufen finden Sie unter Abläufe konfigurieren.

Bedingte Abläufe für Backend-Ressourcen erstellen

Das Definieren bedingter Abläufe für Backend-Ressourcen in einem API-Proxy ist optional. Mit diesen bedingten Abläufen haben Sie jedoch die Möglichkeit, differenzierte Verwaltungs- und Monitoringaufgaben auszuführen.

Sie haben folgende Möglichkeiten:

• Verwaltungsaufgaben an die Semantik Ihres API-Modells anpassen
• Richtlinien und skriptbasiertes Verhalten auf einzelne Ressourcenpfade (URIs) anwenden
• Detaillierte Messwerte für Analytics-Dienste erfassen

Stellen Sie sich beispielsweise vor, Sie müssen verschiedene Arten von Logik auf Ihr Back-End anwenden. /developers zu /apps-Ressourcen.

Fügen Sie dazu Ihrem API-Proxy zwei bedingte Abläufe hinzu: /developers und /apps.

Klicken Sie in der Ansicht „Develop“ des API-Proxy-Editors auf + neben „default“ unter „Proxy Endpoints“.

In diesem Fenster geben Sie die folgenden Schlüsselkonfigurationen ein:

• Flow name: Developers
• Condition Type: Path
• Path: /developers

Die Bedingung wird ausgelöst (und Richtlinien werden ausgeführt), wenn ein Aufruf mit /developers am Ende des URI an den Proxy gesendet wird.

Fügen Sie nun einen bedingten Ablauf für /apps hinzu. Nehmen Sie an, dass die Bedingung sowohl für den URI als auch für das POST-Verb in einer Anfrage ausgelöst werden soll. Die Konfiguration umfasst Folgendes:

• Flow Name: Apps
• Condition Type: Path and Verb
• Pfad: /apps
• Verb:: POST

Die Bedingung wird ausgelöst (und Richtlinien werden ausgeführt), wenn ein Aufruf mit /apps am Ende des URI und einem POST-Verb an den Proxy gesendet wird.

Im Navigationsbereich werden neue Abläufe für Apps und Developers angezeigt.

Wählen Sie einen der Abläufe aus, um die Konfiguration des bedingten Ablaufs in der Codeansicht des API-Proxy-Editors aufzurufen:

<Flow name="Apps">
    <Description>Developer apps registered in Developer Services</Description>
    <Request/>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/apps") and (request.verb = "POST")</Condition>
</Flow>

API-Ressourcen sind einfach nur bedingte Abläufe, die den URI-Pfad der eingehenden Anfrage auswerten. Die Variable „proxy.pathsuffix“ gibt den URI der Anfrage an, der dem in der ProxyEndpoint-Konfiguration konfigurierten BasePath entspricht.

Jede von Ihnen definierte API-Ressource wird durch einen bedingten Ablauf im API-Proxy implementiert. (Siehe Abläufe konfigurieren)

Nachdem Sie den API-Proxy in der Testumgebung bereitgestellt haben, führt die folgende Abfrage

http://{org_name}-test.apigee.net/{proxy_path}/apps

dazu, dass die Bedingung zu „true“ ausgewertet und dieser Ablauf zusammen mit allen zugehörigen Richtlinien ausgeführt wird.

Die folgende Beispielbedingung verwendet einen regulären Java-Ausdruck, um Aufrufe für die Ressource /apps mit oder ohne abschließendem Schrägstrich (/apps oder /apps/**) zu erkennen:

<Condition>(proxy.pathsuffix JavaRegex "/apps(/?)") and (request.verb = "POST")</Condition>

Weitere Informationen zu diesem Bedingungstyp finden Sie unter How to match regardless ... in der Apigee-Community.

Hierarchische URIs modellieren

In einigen Fällen stehen hierarchische API-Ressourcen zur Verfügung. Beispielsweise bietet die Developer Services API eine Methode zum Auflisten aller Anwendungen, die zu einem Entwickler gehören. Der URI-Pfad lautet:

/developers/{developer_email}/apps

Möglicherweise gibt es Ressourcen, bei denen für jede Entität in einer Sammlung eine eindeutige ID generiert wird, die manchmal so annotiert wird:

/genus/:id/species

Dieser Pfad wird gleichermaßen auf die folgenden beiden URIs angewendet:

/genus/18904/species
/genus/17908/species

Um diese Struktur in einer API-Ressource darzustellen, können Sie Platzhalter verwenden. Beispiel:

/developers/*/apps

/developers/*example.com/apps

/genus/*/species

löst diese hierarchischen URIs als entsprechende API-Ressourcen auf.

/developers/**

Diese API-Ressource löst die folgenden URI-Pfade auf:

/developers/{developer_email}/apps
/developers/{developer_email}/keys
/developers/{developer_email}/apps/{app_id}/keys

So sieht die Bedingung für den bedingten Ablauf in der API-Proxy-Definition aus:

<Condition>(proxy.pathsuffix MatchesPath "/developers/**") and (request.verb = "POST")</Condition>

Weitere Beispiele

Mit einer Routingregel verknüpfte Bedingung

<RouteRule name="default">
 <!--this routing executes if the header indicates that this is an XML call. If true, the call is routed to the endpoint XMLTargetEndpoint-->
  <Condition>request.header.content-type = "text/xml"</Condition>
  <TargetEndpoint>XmlTargetEndpoint</TargetEndpoint>
</RouteRule>

Mit einer Richtlinie verknüpfte Bedingung

<Step>
<!--the policy MaintenancePolicy only executes if the response status code is exactly 503-->
  <Condition>response.status.code = 503</Condition>
  <Name>MaintenancePolicy</Name>
</Step>

Bedingter Ablauf

<!-- this entire flow is executed only if the request verb is a GET-->
<Flow name="GetRequests">
  <Condition>request.verb="GET"</Condition>
  <Request>
    <Step>
<!-- this policy only executes if request path includes a term like statues-->
<Condition>request.path ~ "/statuses/**"</Condition>
      <Name>StatusesRequestPolicy</Name>
    </Step>
  </Request>
  <Response>
    <Step>
<!-- this condition has multiple expressions. The policy executes if the response code status is exactly 503 or 400-->
<Condition>(response.status.code = 503) or (response.status.code = 400)</Condition>
      <Name>MaintenancePolicy</Name>
    </Step>
  </Response>
</Flow>

Beispieloperatoren in Bedingungen

Beispiele für Operatoren zum Erstellen von Bedingungen:

• request.header.content-type = "text/xml"
• request.header.content-length < 4096 && request.verb = "PUT"
• response.status.code = 404 || response.status.code = 500
• request.uri MatchesPath "/*/statuses/**"
• request.queryparam.q0 NotEquals 10

Praktisches Beispiel: „/“ am Ende eines Pfads ignorieren

Edge-Entwickler möchten in der Regel beide Pfadsuffixe verarbeiten: „/cat“ und „/cat/“. Dies liegt daran, dass manche Nutzer oder Clients Ihre API mit dem zusätzlichen Schrägstrich am Ende des Pfads aufrufen und Sie in der Lage sein müssen, dies in Ihren bedingten Anweisungen zu berücksichtigen. Dieser Anwendungsfall wurde in der Apigee-Community diskutiert.

Sie können dies auch ohne Regex erreichen. Gehen Sie dazu so vor:

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>((proxy.pathsuffix = "/cat") OR (proxy.pathsuffix = "/cat/")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Das ist eine gute Option. Sie ist gut verständlich und lesbar.

Sie können dies auch mit Regex erreichen. Gehen Sie dazu so vor. Die Klammern können zum Gruppieren des regulären Ausdrucks der Anweisung verwendet werden, sind aber nicht erforderlich.

<Condition>(proxy.pathsuffix JavaRegex "/cat(/?)"</Condition>

API-Aufrufe:

GET http://artomatic-test.apigee.net/matchtest/cat
or
GET http://artomatic-test.apigee.net/matchtest/cat/

Wird die Richtlinie ausgeführt? Ja. Beachten Sie, dass in einem regulären Ausdruck der "?" bedeutet: entspricht null oder einem der vorangehenden Zeichen. Daher sind sowohl „/cat“ und "/cat/" sind Übereinstimmungen.

API-Aufruf:

GET http://artomatic-test.apigee.net/matchtest/cat/spotted

Wird die Richtlinie ausgeführt? Nein. Der reguläre Ausdruck entspricht null oder nur einem Vorkommen des vorherigen Zeichens und nichts anderes ist zulässig.

Beliebige Strings mit JavaRegex abgleichen

In allen Beispielen in diesem Thema wird gezeigt, wie Sie eine der integrierten Flussvariablen abgleichen können: proxy.pathsuffix. Es ist gut zu wissen, dass Sie den Musterabgleich für jeden beliebigen String oder jede Variable machen können, unabhängig davon, ob es sich um eine integrierte Ablaufvariable wie proxy.pathsuffix handelt.

Wenn Sie beispielsweise eine Bedingung haben, mit der beliebige Strings getestet werden, z. B. ein String, der in einer Backend-Nutzlast zurückgegeben wird, oder ein String, der von einer Authentifizierungsserversuche zurückgegeben wird, können Sie übereinstimmende Operatoren zum Testen verwenden. Wenn Sie JavaRegex verwenden, wird der reguläre Ausdruck mit dem gesamten Substring verglichen. Wenn der Betreff „abc” lautet und der reguläre Ausdruck „[a-z]” ist, gibt es keine Übereinstimmung, da „[a-z]” genau mit einem alphanumerischen Zeichen übereinstimmt. Der Ausdruck „[a-z]+” funktioniert ebenso wie „[a-z]*” und „[a-z]{3}”.

Sehen wir uns ein konkretes Beispiel an. Angenommen, der Authentifizierungsserver gibt eine Liste von Rollen als kommagetrennten String zurück: „editor, author, guest”.

Um das Vorhandensein der editor-Rolle zu testen, funktioniert diese Konstruktion nicht, da „editor“ nur ein Teil des gesamten Strings ist.

<Condition>returned_roles ~~ "editor"</Condition>

Diese Konstruktion funktioniert jedoch:

<Condition>returned_roles ~~ ".*\beditor\b.*")</Condition>

Sie funktioniert, da sie Worttrennungen und andere Teile des Strings mit dem Präfix „.*“ und dem Suffix berücksichtigt.

In diesem Beispiel können Sie auch mit dem Matches-Operator nach „editor“ suchen:

<Condition>returned_roles ~~ "*editor*")</Condition>

Wenn Sie hingegen eine höhere Genauigkeit benötigen, ist JavaRegex häufig die bessere Wahl.

Doppelte Anführungszeichen in JavaRegex-Ausdrücken maskieren

 -H 'content-type:multipart/related; type="application/xop+xml"'

request.header.Content-Type ~~ "(multipart\/related)(; *type="application\/xop\+xml\")"

request.header.Content-Type ~~ "(multipart\/related)(; *type=\u0022application\/xop\+xml\u0022)"