Einem API-Proxy CORS-Unterstützung hinzufügen

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Mithilfe des Standardmechanismus CORS (Cross-Origin Resource Sharing) können JavaScript XMLHttpRequest-Aufrufe (XHR), die auf einer Webseite ausgeführt werden, mit Ressourcen von Nicht-Origin-Domains interagieren. CORS ist eine häufig implementierte Lösung für die Same-Origin-Richtlinie, die von allen Browsern durchgesetzt wird. Wenn Sie beispielsweise einen XHR-Aufruf an die Twitter-API von einem im Browser ausgeführten JavaScript-Code aus vornehmen, schlägt der Aufruf fehl. Das liegt daran, dass die Domain, mit der die Seite in Ihrem Browser bereitgestellt wird, nicht dieselbe Domain ist wie die von der Twitter API bereitgestellte. CORS bietet eine Lösung für dieses Problem, denn die Server können per Opt-in zustimmen, wenn sie eine ursprungsübergreifende Ressourcenfreigabe bereitstellen möchten.

Typischer Anwendungsfall für CORS

Der folgende JQuery-Code ruft einen fiktiven Zieldienst auf. Bei Ausführung im Kontext eines Browsers (einer Webseite) schlägt der Aufruf aufgrund der Same-Origin-Richtlinie fehl:

<script>
var url = "http://service.example.com";
$(document).ready(function(){
  $("button").click(function(){
    $.ajax({
        type:"GET",
        url:url,
        async:true,
        dataType: "json",
           success: function(json) {
              // Parse the response.
              // Do other things.
           },
           error: function(xhr, status, err) {
              // This is where we end up!
            }
    });
  });
});
</script>

Eine Lösung für dieses Problem besteht darin, einen Apigee API-Proxy zu erstellen, der die Service API auf dem Back-End aufruft. Beachten Sie, dass Apigee zwischen dem Client (in diesem Fall ein Browser) und der Back-End API (dem Dienst) angeordnet ist. Da der API-Proxy auf dem Server und nicht in einem Browser ausgeführt wird, kann er den Dienst erfolgreich aufrufen. Dann müssen Sie nur noch CORS-Header an die TargetEndpoint-Antwort anhängen. Solange der Browser CORS unterstützt, weisen diese Header den Browser darauf hin, dass es in Ordnung ist, seine Same-Origin-Richtlinie für denselben Ursprung zu lockern, sodass der Cross-Origin-API-Aufruf erfolgreich ist.

Sobald der Proxy mit der CORS-Unterstützung erstellt wurde, können Sie die API-Proxy-URL anstelle des Back-End-Dienstes in Ihrem clientseitigen Code aufrufen. Beispiele:

<script>
var url = "http://myorg-test.apigee.net/v1/example";
$(document).ready(function(){
  $("button").click(function(){
    $.ajax({
        type:"GET",
        url:url,
        async:true,
        dataType: "json",
           success: function(json) {
              // Parse the response.
              // Do other things.
           },
           error: function(xhr, status, err) {
              // This time, we do not end up here!
            }
    });
  });
});
</script>

CORS-Richtlinie an den Anfrage-PreFlow des ProxyEndpoint anhängen

CORS-Richtlinie an einen neuen API-Proxy anhängen

Sie können einem API-Proxy CORS-Unterstützung hinzufügen, indem Sie an den API-Proxy eine Richtlinie vom Typ CORS hinzufügen anhängen:

Wenn Sie die Richtlinie erstellen, indem Sie auf der Seite Sicherheit des Assistenten Proxy erstellen das Kästchen CORS-Header hinzufügen anklicken
Durch späteres Hinzufügen über das Dialogfeld Richtlinie hinzufügen

Wenn Sie die CORS-Richtlinie durch Anklicken des Kästchens hinzufügen, wird dem System automatisch eine Richtlinie namens CORS hinzufügen hinzugefügt und dem Anfrage-Preflow TargetEndpoint zugeordnet.

Die Richtlinie CORS hinzufügen fügt die entsprechenden Header der Antwort hinzu. Im Prinzip teilen die Header dem Browser mit, mit welchen Ursprüngen er seine Ressourcen teilt, welche Methoden er akzeptiert und so weiter. Weitere Informationen zu diesen CORS-Headern finden Sie in der W3C-Empfehlung zum Cross-Origin Resource Sharing.

Sie sollten die Richtlinie so ändern:

Fügen Sie dem Header Access-Control-Allow-Headers die Header content-type und authorization hinzu, wie im folgenden Code-Snippet dargestellt. Dies ist erforderlich, um die Basisauthentifizierung oder OAuth2 zu unterstützen.
Für die OAuth2-Authentifizierung müssen Sie gegebenenfalls Maßnahmen ergreifen, um das nicht-RFC-konforme Verhalten zu korrigieren.

<CORS continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <AllowOrigins>{request.header.origin}</AllowOrigins>
    <AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
    <AllowHeaders>origin, x-requested-with, accept, content-type, authorization</AllowHeaders>
    <ExposeHeaders>*</ExposeHeaders>
    <MaxAge>3628800</MaxAge>
    <AllowCredentials>false</AllowCredentials>
    <GeneratePreflightResponse>true</GeneratePreflightResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

CORS-Headern zu einem vorhandenen Proxy hinzufügen

Neuer Proxy-Editor

So fügen Sie die CORS-Richtlinie einem vorhandenen API-Proxy hinzu:

Wenn Sie die Apigee-UI in der Cloud Console verwenden: Wählen Sie Proxy-Entwicklung > API-Proxys aus.

Wenn Sie die klassischeApigee-UI verwenden: Wählen Sie Entwickeln > API-Proxys aus und im Bereich Proxys wählen Sie die Umgebung für den Proxy aus.
Wählen Sie den API-Proxy aus, dem Sie die CORS-Richtlinie hinzufügen möchten.
Klicken Sie im Editor für den neuen API-Proxy auf den Tab Entwickeln.
Klicken Sie im linken Bereich in der Zeile Richtlinien auf die Schaltfläche +.
Klicken Sie im Dialogfeld Richtlinie erstellen in das Feld Richtlinientyp wählen, scrollen Sie nach unten zu Sicherheit und wählen Sie CORS.
Geben Sie die Details der Richtlinie ein und klicken Sie auf Erstellen.
Klicken Sie im linken Bereich unter PreFlow auf PreFlow.
Klicken Sie auf die Schaltfläche + neben PreFlow im Request-Bereich unten rechts im visuellen Editor:
Wählen Sie im Dialogfeld Richtlinienschritt hinzufügen die Richtlinie CORS.
Klicken Sie auf Hinzufügen, um die Richtlinie anzuhängen.

Klassischer Proxy-Editor

So fügen Sie die CORS-Richtlinie einem vorhandenen API-Proxy hinzu:

Melden Sie sich bei der Apigee-UI an.
Wählen Sie in der linken Navigationsleiste Develop > API Proxies aus.

Jetzt testen

Entwickeln

Schaltfläche Jetzt testen

Wenn Sie die neue Version des Proxy-Editors zum ersten Mal verwenden, wird oben in der Ansicht Entwickeln das folgende Banner angezeigt:

Schaltfläche "Jetzt testen"

Klicken Sie auf die Schaltfläche Jetzt testen, um die neue Entwickeln-Ansicht aufzurufen.

Die Entwickeln-Ansicht wird unten angezeigt.

Ansicht "Entwickeln" im Proxy-Editor

Wählen Sie den API-Proxy aus, dem Sie die CORS-Richtlinie hinzufügen möchten.
Klicken Sie im Editor für den neuen API-Proxy auf den Tab Entwickeln:

Klicken Sie im linken Navigationsbereich unter PreFlow auf PreFlow.
Klicken Sie auf die Schaltfläche +Schritt für das Anfrage-PreFlow. Dadurch wird eine kategorisierte Liste aller Richtlinien angezeigt, die Sie erstellen können.
Wählen Sie in der Kategorie CORS die Option CORS aus.
Geben Sie einen Namen wie Add CORS ein und klicken Sie dann auf Hinzufügen.

CORS-Preflight-Anfragen verarbeiten

CORS Preflight bezieht sich auf das Senden einer Anfrage an einen Server, um zu kontrollieren, ob CORS unterstützt wird. Typische Preflight-Antworten sind z. B., von welchen Quellen der Server CORS-Anfragen akzeptiert, eine Liste von HTTP-Methoden, die für CORS-Anfragen unterstützt werden, Header, die als Teil der Ressourcenanfrage verwendet werden können, die maximale Zeit, für die eine Preflight-Antwort im Cache gespeichert wird und mehr. Wenn der Dienst keine CORS-Unterstützung anzeigt oder keine Cross-Origin-Anfragen vom Ursprung des Kunden annehmen möchte, wird die Cross-Origin-Richtlinie des Browsers erzwungen und alle domainübergreifenden Anfragen vom Client, mit Ressourcen auf diesem Server zu interagieren, werden fehlschlagen.

In der Regel werden CORS-Preflight-Anfragen mit der HTTP-OPTIONEN-Methode gestellt. Wenn ein Server, der CORS unterstützt, eine OPTIONS-Anfrage erhält, gibt er eine Reihe von CORS-Headern an den Client zurück, die die Ebene der CORS-Unterstützung angeben. Aufgrund dieses Handshakes weiß der Client, was er von der Nicht-Ursprungsdomain anfordern darf.

Weitere Informationen zum Preflight finden Sie in der W3C-Empfehlung zum Cross-Origin Resource Sharing. Darüber hinaus gibt es zahlreiche Blogs und Artikel zu CORS, auf die Sie zurückgreifen können.

Apigee enthält von Haus aus keine CORS-Preflight-Lösung, aber es ist möglich, sie zu implementieren, wie in diesem Abschnitt beschrieben. Das Ziel für den Proxy besteht darin, eine OPTIONS-Anfrage in einem bedingten Ablauf auszuwerten. Der Proxy kann dann eine entsprechende Antwort an den Client senden.

Sehen wir uns einen Beispielablauf an und erläutern die Teile, die die Preflight-Anfrage verarbeiten:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
    <Description/>
    <Flows>
        <Flow name="OptionsPreFlight">
            <Request>
                <Step>
                    <Name>add-cors</Name>
                </Step>
            </Request>
            <Response/>
        <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
        </Flow>
    </Flows>

    <PreFlow name="PreFlow">
        <Request/>
        <Response/>

    </PreFlow>
    <HTTPProxyConnection>
        <BasePath>/v1/cnc</BasePath>
        <VirtualHost>default</VirtualHost>
        <VirtualHost>secure</VirtualHost>
    </HTTPProxyConnection>
    <RouteRule name="NoRoute">
        <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
    </RouteRule>
    <RouteRule name="default">
        <TargetEndpoint>default</TargetEndpoint>
   </RouteRule>
   <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
</ProxyEndpoint>

Dieser ProxyEndpoint besteht aus folgenden Hauptkomponenten:

Eine an ein NULL-Ziel gerichtete RouteRule wird mit einer Bedingung für die OPTIONS-Anfrage erstellt. Beachten Sie, dass kein TargetEndpoint angegeben wird. Wenn die OPTIONS-Anfrage empfangen wird und die Anfrageheader „Origin“ und „Access-Control-Request-Method“ nicht NULL sind, gibt der Proxy sofort die CORS-Header in einer Antwort an den Client zurück (unter Umgehung des tatsächlichen Standard-Back-End-Ziels). Weitere Informationen zu Flussbedingungen und RouteRule finden Sie unter Bedingungen mit Flussvariablen.
```
<RouteRule name="NoRoute">
    <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
</RouteRule>
```

Ein Ablauf "OptionsPreFlight" wird erstellt, der dem Ablauf eine Richtlinie "CORS hinzufügen" mit den CORS-Headern hinzufügt, wenn eine "OPTIONS"-Anfrage empfangen wird und die Anfrage-Header "Origin" und "Access-Control-Request-Method" nicht null sind.

 <Flow name="OptionsPreFlight">
            <Request>
                <Step>
                    <Name>add-cors</Name>
                </Step>
            </Request>
            <Response/>
        <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
 </Flow>