Diese Seite gilt für Apigee und Apigee Hybrid.
Apigee Edge-Dokumentation aufrufen
Was
Mithilfe des Standardmechanismus CORS (Cross-Origin Resource Sharing) können JavaScript-XHR-Aufrufe (XMLHttpRequest), 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.
Mit dieser CORS-Richtlinie können Apigee-Kunden CORS-Richtlinien für APIs festlegen, die von Webanwendungen genutzt werden.
Diese Richtlinie ist eine Standardrichtlinie, die in jeder Umgebung bereitgestellt werden kann. Informationen zu Richtlinientypen und zur Verfügbarkeit bei jedem Umgebungstyp finden Sie unter Richtlinientypen.
Element <CORS>
Definiert die CORS-Richtlinie.
Standardwert | Siehe Standardrichtlinie Tab unten |
Erforderlich? | Erforderlich |
Typ | Komplexes Objekt |
Übergeordnetes Element | – |
Untergeordnete Elemente |
<AllowCredentials> <AllowHeaders> <AllowMethods> <AllowOrigins> <DisplayName> <ExposeHeaders> <GeneratePreflightResponse> <IgnoreUnresolvedVariables> <MaxAge> |
Das <CORS>
-Element verwendet die folgende Syntax:
Syntax
Das Element <CORS>
verwendet die folgende Syntax:
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <DisplayName>DISPLAY_NAME</DisplayName> <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins> <AllowMethods>[GET, PUT, POST, DELETE, ...|*]</AllowMethods> <AllowHeaders>[origin, x-requested-with, accept, content-type, ...]</AllowHeaders> <ExposeHeaders>[X-CUSTOM-HEADER-A, X-CUSTOM-HEADER-B, ... | *]</ExposeHeaders> <MaxAge>[integer|-1]</MaxAge> <AllowCredentials>[false|true]</AllowCredentials> <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse> <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables> </CORS>
Standardrichtlinie
Das folgende Beispiel zeigt die Standardeinstellungen, wenn Sie dem Ablauf in der Edge-UI die CORS-Richtlinie hinzufügen:
<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</AllowHeaders> <ExposeHeaders>*</ExposeHeaders> <MaxAge>3628800</MaxAge> <AllowCredentials>false</AllowCredentials> <GeneratePreflightResponse>true</GeneratePreflightResponse> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </CORS>
Wenn Sie eine neue CORS
-Richtlinie in die Apigee-UI einfügen, enthält die Vorlage Stubs für alle möglichen Vorgänge. Normalerweise wählen Sie aus, welche Vorgänge Sie mit dieser Richtlinie ausführen möchten, und entfernen die restlichen untergeordneten Elemente. Wenn Sie beispielsweise die HTTP-Methoden angeben möchten, die auf die Ressource zugreifen dürfen, verwenden Sie das Element <AllowMethods>
und entfernen Sie die anderen untergeordneten Elemente aus der Richtlinie, um ihre Lesbarkeit zu erhöhen.
Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:
Attribut | Standard | Erforderlich? | Beschreibung |
---|---|---|---|
name |
- | Erforderlich |
Der interne Name der Richtlinie. Der Wert des Attributs Optional können Sie das Element |
continueOnError |
false | Optional | 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. Weitere Informationen:
|
enabled |
wahr | Optional | Setzen Sie den Wert auf true , um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht durchgesetzt, selbst wenn sie mit einem Ablauf verknüpft ist. |
async |
false | Verworfen | Dieses Attribut wurde verworfen. |
Jedes der untergeordneten Elemente wird in den folgenden Abschnitten beschrieben.
Beispiele
In den folgenden Abschnitten finden Sie Beispiele für alle untergeordneten Elemente.
Verweis auf untergeordnetes Element
In diesem Abschnitt werden die untergeordneten Elemente von <CORS>
beschrieben.
<AllowCredentials>
Gibt an, ob der Aufrufer die tatsächliche Anfrage (nicht die Preflight-Anfrage) mit Anmeldedaten senden darf. Wird in den Access-Control-Allow-Credentials
-Header übersetzt.
Standardwert | Wenn nicht angegeben, wird Access-Control-Allow-Credentials nicht festgelegt. |
Erforderlich? | Optional |
Typ | Boolesch |
Übergeordnetes Element |
<CORS>
|
Untergeordnete Elemente | Keine |
Das <AllowCredentials>
-Element verwendet die folgende Syntax:
Syntax
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins> <AllowCredentials>[false|true]</AllowCredentials> </CORS>
Beispiel
This example sets the Access-Control-Allow-Credentials
header to false
.
That is, the caller is not allowed to send the actual request (not the preflight)
using credentials.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowCredentials>false</AllowCredentials> </CORS>
<AllowHeaders>
Liste der HTTP-Header, die beim Anfordern der Ressource verwendet werden können.
Serialisiert im Access-Control-Allow-Headers
-Header.
Standardwert | Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers |
Erforderlich? | Optional |
Typ | String mit Unterstützung für Nachrichtenvorlagen* |
Übergeordnetes Element |
<CORS>
|
Untergeordnete Elemente | Keine |
* Weitere Informationen finden Sie unter Was ist eine Nachrichtenvorlage?
Das Element <AllowHeaders>
verwendet die folgende Syntax:
Syntax
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins> <AllowHeaders>[origin, x-requested-with, accept, content-type, ...]</AllowHeaders> </CORS>
Beispiel
This example specifies the HTTP headers that can be used when requesting the resource.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowHeaders>origin, x-requested-with, accept, content-type</AllowHeaders> </CORS>
<AllowMethods>
Liste der HTTP-Methoden, die auf die Ressource zugreifen dürfen. Der Inhalt wird im Header Access-Control-Allow-Methods
serialisiert.
Standardwert | GET, POST, HEAD, OPTIONS |
Erforderlich? | Optional |
Typ | String mit Unterstützung für Nachrichtenvorlagen* |
Übergeordnetes Element |
<CORS>
|
Untergeordnete Elemente | Keine |
* Weitere Informationen finden Sie unter Was ist eine Nachrichtenvorlage?
Das Element <AllowMethods>
verwendet die folgende Syntax:
Syntax
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins> <AllowMethods>[GET, PUT, POST, DELETE, ...|*]</AllowMethods> </CORS>
Beispiel:
Liste
This example specifies the HTTP methods that are allowed to access the resource.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowMethods>GET, PUT, POST, DELETE</AllowMethods> </CORS>
Beispiel:
Platzhalter
This example specifies that all HTTP methods are allowed to access the resource.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowMethods>*</AllowMethods> </CORS>
<AllowOrigins>
Eine Liste der Ursprünge, die auf die Ressource zugreifen dürfen. Verwenden Sie ein Sternchen (*
), um den Zugriff auf eine Ressource von einem beliebigen Ursprung zu ermöglichen. Geben Sie andernfalls eine Liste mit durch Kommas getrennten Ursprüngen an. Wird eine Übereinstimmung gefunden, wird der ausgehende Access-Control-Allow-Origin
auf den vom Client bereitgestellten Ursprung festgelegt.
Standardwert | – |
Erforderlich? | Erforderlich |
Typ | String mit Unterstützung für Nachrichtenvorlagen* |
Übergeordnetes Element |
<CORS>
|
Untergeordnete Elemente | Keine |
* Weitere Informationen finden Sie unter Was ist eine Nachrichtenvorlage?
Das Element <AllowOrigins>
verwendet die folgende Syntax:
Syntax
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins> </CORS>
Beispiel:
Einzelne URL
This example specifies a single URL origin that is allowed to access the resource.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>https://www.w3.org</AllowOrigins> </CORS>
Beispiel:
Mehrere URLs
This example specifies multiple origins that are allowed to access the resource.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>https://www.w3.org, https://www.apache.org</AllowOrigins> </CORS>
Beispiel:
Kontextvariable
In diesem Beispiel wird eine Kontextvariable angegeben, die einen oder mehrere Ursprünge darstellt, die auf die Ressource zugreifen dürfen.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{origins.list}</AllowOrigins> </CORS>
Beispiel:
Ablaufvariable
This example specifies a flow variable that represents one origin that is allowed to access the resource.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> </CORS>
Beispiel:
Platzhalter
In diesem Beispiel wird angegeben, dass alle Ursprünge auf die Ressource zugreifen dürfen.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>*</AllowOrigins> </CORS>
<DisplayName>
Wird zusätzlich zum Attribut name
verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen, natürlicher klingenden Namen zu versehen.
Das Element <DisplayName>
ist für alle Richtlinien gleich.
Standardwert | – |
Erforderlich? | Optional. Wenn Sie <DisplayName> weglassen, wird der Wert des Attributs name der Richtlinie verwendet. |
Typ | String |
Übergeordnetes Element | <PolicyElement> |
Untergeordnete Elemente | Keine |
Das <DisplayName>
-Element verwendet die folgende Syntax:
Syntax
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
Beispiel
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
Das <DisplayName>
-Element hat keine Attribute oder untergeordneten Elemente.
<ExposeHeaders>
Eine Liste der HTTP-Header, auf die der Browser zugreifen darf, oder ein Sternchen (*
), um alle HTTP-Header zuzulassen.
Serialisiert im Access-Control-Expose-Headers
-Header.
Standardwert | Wenn nicht angegeben, wird Access-Control-Expose-Headers nicht festgelegt. Nicht einfache Header werden nicht standardmäßig verfügbar gemacht. |
Erforderlich? | Optional |
Typ | String mit Unterstützung für Nachrichtenvorlagen* |
Übergeordnetes Element |
<CORS>
|
Untergeordnete Elemente | Keine |
* Weitere Informationen finden Sie unter Was ist eine Nachrichtenvorlage?
Das Element <ExposeHeaders>
verwendet die folgende Syntax:
Syntax
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins> <ExposeHeaders>[X-CUSTOM-HEADER-A, X-CUSTOM-HEADER-B, ... | *]</ExposeHeaders> </CORS>
Beispiel
This example specifies that the browsers are allowed to access all HTTP headers.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <ExposeHeaders>*</ExposeHeaders> </CORS>
<GeneratePreflightResponse>
Geben Sie an, ob die Richtlinie die CORS-Preflight-Antwort generieren und zurückgeben soll.
Bei false
wird keine Antwort gesendet. Stattdessen werden die folgenden Ablaufvariablen ausgefüllt:
cross_origin_resource_sharing.allow.credentials
cross_origin_resource_sharing.allow.headers
cross_origin_resource_sharing.allow.methods
cross_origin_resource_sharing.allow.origin
cross_origin_resource_sharing.allow.origins.list
cross_origin_resource_sharing.expose.headers
cross_origin_resource_sharing.max.age
cross_origin_resource_sharing.preflight.accepted
cross_origin_resource_sharing.request.headers
cross_origin_resource_sharing.request.method
cross_origin_resource_sharing.request.origin
cross_origin_resource_sharing.request.type
Standardwert | true |
Erforderlich? | Optional |
Typ | Boolesch |
Übergeordnetes Element |
<CORS>
|
Untergeordnete Elemente | Keine |
Das <GeneratePreflightResponse>
-Element verwendet die folgende Syntax:
Syntax
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse> <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse> </CORS>
Beispiel
In diesem Beispiel wird angegeben, dass die Richtlinie die CORS-Preflight-Antwort generieren und zurückgeben soll.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <GeneratePreflightResponse>true</GeneratePreflightResponse> </CORS>
<IgnoreUnresolvedVariables>
Bestimmt, ob die Verarbeitung beendet wird, wenn eine nicht aufgelöste Variable erkannt wird.
Auf true
festlegen, um nicht aufgelöste Variablen zu ignorieren und die Verarbeitung fortzusetzen. Andernfalls false
.
Standardwert | true |
Erforderlich? | Optional |
Typ | Boolesch |
Übergeordnetes Element |
<CORS>
|
Untergeordnete Elemente | Keine |
Das <IgnoreUnresolvedVariables>
-Element verwendet die folgende Syntax:
Syntax
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins> <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables> </CORS>
Beispiel
This example specifies that processing continues when an unresolved variable is encountered.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </CORS>
<MaxAge>
Gibt an, wie lange die Ergebnisse einer Preflight-Anfrage in Sekunden im Cache gespeichert werden können.
Der Wert von -1
füllt den Access-Control-Max-Age
-Header mit dem Wert von -1
aus, wodurch das Caching deaktiviert wird. Hierfür ist eine Preflight-OPTIONS
-Prüfung für alle Aufrufe erforderlich. Dies ist in der Spezifikation von
Access-Control-Max-Age
definiert.
Standardwert | 1800 |
Erforderlich? | Optional |
Typ | Ganzzahl |
Übergeordnetes Element |
<CORS>
|
Untergeordnete Elemente | Keine |
Das <MaxAge>
-Element verwendet die folgende Syntax:
Syntax
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins> <MaxAge>[integer|-1]</MaxAge> </CORS>
Beispiel:
Cache
In diesem Beispiel wird angegeben, dass die Ergebnisse einer Preflight-Anfrage für 3628800
Sekunden im Cache gespeichert werden können.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <MaxAge>3628800</MaxAge> </CORS>
Beispiel:
Kein Cache
This example specifies that the results of a preflight request cannot be cached.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <MaxAge>-1</MaxAge> </CORS>
Verwendungshinweise
OPTIONS
-Anfragen
Wenn eine
OPTIONS
-Anfrage von der CORS-Richtlinie empfangen und verarbeitet wird, wird die Proxy-Ablaufausführung direkt an den Proxy Response PreFlow übertragen und die Anfrageabläufe vollständig übersprungen und von dort aus ausgeführt. Sie müssen keine Bedingung erstellen, um die OPTIONS-Anfrage im Proxy-Anfrageablauf zu ignorieren.
Wenn die nachfolgende CORS-Richtlinie ausgeführt wird und der in der Richtlinie festgelegte Wert für MaxAge
nicht abgelaufen ist, wird der Ablauf wie gewohnt fortgesetzt. Während des endgültigen Antwortflusses vor "Antwort an den Client gesendet" legt ein spezieller CORS-Ausführungsschritt "CORSResponseOrErrorFlowExecution" CORS-Antwortheader fest (Access-Control-Allow-Credentials
,Access-Control-Allow-Origin
undAccess-Control-Expose-Headers
), um eine CORS-validierte Antwort zurückzugeben.
Fehlercodes
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
Fault code | HTTP status | Cause |
---|---|---|
steps.cors.UnresolvedVariable |
500 |
This error occurs if a variable specified in the CORS policy is either:
or |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause |
---|---|
InvalidMaxAge |
MaxAge is not number |
MissingAllowOrigins |
AllowOrigins is not specified |
InvalidHTTPMethods |
One of the methods in AllowMethods is not valid |
AllowHeadersSizeTooLarge |
The string size in AllowHeaders is too large. |
ExposeHeadersSizeTooLarge |
The string size in ExposeHeaders is too large. |
Fault variables
These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.
Variables | Where | Example |
---|---|---|
fault.name = "FAULT_NAME" |
FAULT_NAME is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "UnresolveVariable" |
cors.POLICY_NAME.failed |
POLICY_NAME is the user-specified name of the policy that threw the fault. | cors.AddCORS.failed = true |
Example error response
{ "fault":{ "detail":{ "errorcode":"steps.cors.UnresolvedVariable" }, "faultstring":"CORS[AddCORS]: unable to resolve variable wrong.var" } }
Example fault rule
<FaultRule name="Add CORS Fault"> <Step> <Name>Add-CORSCustomUnresolvedVariableErrorResponse</Name> <Condition>(fault.name Matches "UnresolvedVariable") </Condition> </Step> <Condition>(cors.Add-CORS.failed = true) </Condition> </FaultRule>
Ablaufvariablen
Ein CorsFlowInfo
-FlowInfo
-Objekt wird hinzugefügt und steht für Tracing zur Verfügung.
Attribut | Typ | Lesen/Schreiben | Beschreibung | Bereich beginnt |
---|---|---|---|---|
cross_origin_resource_sharing.allow.credentials |
Boolesch | Lesen/Schreiben | Wert aus <AllowCredentials> |
Proxyanfrage |
cross_origin_resource_sharing.allow.headers |
String | Lesen/Schreiben | Wert aus <AllowHeaders> |
Proxyanfrage |
cross_origin_resource_sharing.allow.methods |
String | Lesen/Schreiben | Wert aus <AllowMethods> |
Proxyanfrage |
cross_origin_resource_sharing.allow.origin |
String | Lesen/Schreiben | Der zulässige Anfrageursprung; leer, wenn er nicht in der Zulassungsliste enthalten ist | Proxyanfrage |
cross_origin_resource_sharing.allow.origins.list |
String | Lesen/Schreiben | Wert aus <AllowOrigins> |
Proxyanfrage |
cross_origin_resource_sharing.expose.headers |
String | Lesen/Schreiben | Wert aus <ExposeHeaders> |
Proxyanfrage |
cross_origin_resource_sharing.max.age |
Ganzzahl | Lesen/Schreiben | Wert aus <MaxAge> |
Proxyanfrage |
cross_origin_resource_sharing.preflight.accepted |
Boolesch | Lesen/Schreiben | Gibt an, ob die Preflight-Anfrage akzeptiert wird | Proxyanfrage |
cross_origin_resource_sharing.request.headers |
String | Lesen/Schreiben | Der Wert des Access-Control-Request-Headers -Headers der Anfrage |
Proxyanfrage |
cross_origin_resource_sharing.request.method |
String | Lesen/Schreiben | Der Wert des Access-Control-Request-Method -Headers der Anfrage |
Proxyanfrage |
cross_origin_resource_sharing.request.origin |
String | Lesen/Schreiben | Identisch mit request.header.origin |
Proxyanfrage |
cross_origin_resource_sharing.request.type |
String | Lesen/Schreiben |
Typ der CORS-Anfrage. Mögliche Werte:
|
Proxyanfrage |