Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Cosa
La condivisione delle risorse tra origini (CORS) è un meccanismo standard che consente alle chiamate XMLHttpRequest (XHR) di JavaScript eseguite in una pagina web di interagire con le risorse dei domini non di origine. CORS è una soluzione comunemente implementata per il criterio della stessa origine applicato da tutti i browser.
Ad esempio, se effettui una chiamata XHR all'API Twitter dal codice JavaScript in esecuzione nel browser, la chiamata avrà esito negativo. Questo perché il dominio che pubblica la pagina nel tuo browser non è lo stesso del dominio che pubblica l'API Twitter. CORS offre una soluzione a questo problema consentendo ai server di attivarsi se vogliono fornire la condivisione delle risorse tra origini.
Questo criterio CORS consente ai clienti di Apigee di impostare criteri CORS per le API utilizzate dalle applicazioni web.
Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutti gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ogni tipo di ambiente, consulta Tipi di criteri.
Elemento <CORS>
Definisce il criterio CORS.
Valore predefinito | Vedi la scheda Criterio predefinito di seguito |
Obbligatorio? | Obbligatorio |
Tipo | Oggetto complesso |
Elemento principale | N/A |
Elementi secondari |
<AllowCredentials> <AllowHeaders> <AllowMethods> <AllowOrigins> <DisplayName> <ExposeHeaders> <GeneratePreflightResponse> <IgnoreUnresolvedVariables> <MaxAge> |
La sintassi dell'elemento <CORS>
è la seguente:
Sintassi
La sintassi dell'elemento <CORS>
è la seguente:
<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>
Criterio predefinito
L'esempio seguente mostra le impostazioni predefinite quando aggiungi il criterio CORS al tuo flusso nella UI Edge:
<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>
Quando inserisci un nuovo criterio CORS
nella UI di Apigee, il modello contiene stub
per tutte le operazioni possibili. In genere, devi selezionare le operazioni che vuoi eseguire con questo criterio e rimuovere il resto degli elementi secondari. Ad esempio, se vuoi specificare i metodi HTTP autorizzati ad accedere alla risorsa, utilizza l'elemento <AllowMethods>
e rimuovi gli altri elementi secondari dal criterio per renderlo più leggibile.
Questo elemento ha i seguenti attributi comuni a tutti i criteri:
Attributo | Predefinito | Obbligatorio? | Descrizione |
---|---|---|---|
name |
N/A | Obbligatorio |
Il nome interno del criterio. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
continueOnError |
falso | Facoltativo | Imposta su false per restituire un errore in caso di errore del criterio. Questo è un comportamento previsto per
la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un errore nel criterio. Vedi anche:
|
enabled |
true | Facoltativo | Imposta su true per applicare il criterio. Imposta su false per disattivare il
criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso. |
async |
falso | Deprecato | Questo attributo è stato ritirato. |
Ciascuno degli elementi secondari è descritto nelle sezioni seguenti.
Esempi
Sono forniti esempi per tutti gli elementi secondari nelle sezioni seguenti.
Riferimento per l'elemento secondario
Questa sezione descrive gli elementi secondari di <CORS>
.
<AllowCredentials>
Indica se il chiamante può inviare la richiesta effettiva (non la richiesta preliminare) utilizzando le credenziali. Si traduce nell'intestazione Access-Control-Allow-Credentials
.
Valore predefinito | Se non specificato, Access-Control-Allow-Credentials non verrà impostato. |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuna esperienza |
La sintassi dell'elemento <AllowCredentials>
è la seguente:
Sintassi
<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>
Esempio
Questo esempio imposta l'intestazione Access-Control-Allow-Credentials
su false
.
In altre parole, il chiamante non è autorizzato a inviare la richiesta effettiva (non il preflight) utilizzando le credenziali.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowCredentials>false</AllowCredentials> </CORS>
<AllowHeaders>
Elenco di intestazioni HTTP che possono essere utilizzate quando si richiede la risorsa.
Serializzato nell'intestazione Access-Control-Allow-Headers
.
Valore predefinito | Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers |
Obbligatorio? | Facoltativo |
Tipo | Stringa, con modello di messaggio* supportato |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuna esperienza |
* Per saperne di più, consulta Che cos'è un modello di messaggio?
La sintassi dell'elemento <AllowHeaders>
è la seguente:
Sintassi
<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>
Esempio
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>
Elenco dei metodi HTTP autorizzati ad accedere alla risorsa. I contenuti verranno
serializzati nell'intestazione
Access-Control-Allow-Methods
.
Valore predefinito | GET, POST, HEAD, OPTIONS |
Obbligatorio? | Facoltativo |
Tipo | Stringa, con modello di messaggio* supportato |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuna esperienza |
* Per saperne di più, consulta Che cos'è un modello di messaggio?
La sintassi dell'elemento <AllowMethods>
è la seguente:
Sintassi
<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>
Esempio:
Elenco
Questo esempio specifica i metodi HTTP autorizzati ad accedere alla risorsa.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowMethods>GET, PUT, POST, DELETE</AllowMethods> </CORS>
Esempio:
Carattere jolly
Questo esempio specifica che tutti i metodi HTTP sono autorizzati ad accedere alla risorsa.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowMethods>*</AllowMethods> </CORS>
<AllowOrigins>
Un elenco delle origini autorizzate ad accedere alla risorsa. Utilizza un asterisco (*
) per abilitare l'accesso a una risorsa da qualsiasi origine. Altrimenti, fornisci una lista consentita di origini separate da virgole. Se viene trovata una corrispondenza, l'elemento Access-Control-Allow-Origin
in uscita viene impostato sull'origine fornita dal client.
Valore predefinito | N/A |
Obbligatorio? | Obbligatorio |
Tipo | Stringa, con modello di messaggio* supportato |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuna esperienza |
* Per saperne di più, consulta Che cos'è un modello di messaggio?
La sintassi dell'elemento <AllowOrigins>
è la seguente:
Sintassi
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins> </CORS>
Esempio:
URL singolo
Questo esempio specifica un'origine URL singola a cui è consentito accedere alla risorsa.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>https://www.w3.org</AllowOrigins> </CORS>
Esempio:
Più URL
Questo esempio specifica più origini a cui è consentito accedere alla risorsa.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>https://www.w3.org, https://www.apache.org</AllowOrigins> </CORS>
Esempio:
Variabile di contesto
Questo esempio specifica una variabile di contesto che rappresenta una o più origini autorizzate ad accedere alla risorsa.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{origins.list}</AllowOrigins> </CORS>
Esempio:
Variabile di flusso
Questo esempio specifica una variabile di flusso che rappresenta un'origine a cui è consentito accedere alla risorsa.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> </CORS>
Esempio:
Carattere jolly
This example specifies that all origins are allowed to access the resource.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>*</AllowOrigins> </CORS>
<DisplayName>
Use in addition to the name
attribute to label the policy in the
management UI proxy editor with a different, more natural-sounding name.
The <DisplayName>
element is common to all policies.
Default Value | N/A |
Required? | Optional. If you omit <DisplayName> , the value of the
policy's name attribute is used. |
Type | String |
Parent Element | <PolicyElement> |
Child Elements | None |
The <DisplayName>
element uses the following syntax:
Syntax
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
Example
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
The <DisplayName>
element has no attributes or child elements.
<ExposeHeaders>
Un elenco di intestazioni HTTP a cui i browser sono autorizzati ad accedere o un asterisco (*
) per consentire tutte le intestazioni HTTP.
Serializzato nell'intestazione Access-Control-Expose-Headers
.
Valore predefinito | Se non specificato, Access-Control-Expose-Headers non verrà impostato. Le intestazioni non semplici non sono visibili per impostazione predefinita. |
Obbligatorio? | Facoltativo |
Tipo | Stringa, con modello di messaggio* supportato |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuna esperienza |
* Per saperne di più, consulta Che cos'è un modello di messaggio?
La sintassi dell'elemento <ExposeHeaders>
è la seguente:
Sintassi
<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>
Esempio
Questo esempio specifica che i browser sono autorizzati ad accedere a tutte le intestazioni HTTP.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <ExposeHeaders>*</ExposeHeaders> </CORS>
<GeneratePreflightResponse>
Indica se il criterio deve generare e restituire la risposta preflight CORS.
Se false
, non viene inviata alcuna risposta. Vengono invece compilate le seguenti variabili di flusso:
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
Valore predefinito | true |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuna esperienza |
La sintassi dell'elemento <GeneratePreflightResponse>
è la seguente:
Sintassi
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse> <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse> </CORS>
Esempio
Questo esempio specifica che il criterio deve generare e restituire la risposta preflight CORS.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <GeneratePreflightResponse>true</GeneratePreflightResponse> </CORS>
<IgnoreUnresolvedVariables>
Determina se l'elaborazione si interrompe quando viene rilevata una variabile non risolta.
Imposta su true
per ignorare le variabili non risolte e continuare l'elaborazione; altrimenti, false
.
Valore predefinito | true |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuna esperienza |
La sintassi dell'elemento <IgnoreUnresolvedVariables>
è la seguente:
Sintassi
<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>
Esempio
Questo esempio specifica che l'elaborazione continua quando viene rilevata una variabile non risolta.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </CORS>
<MaxAge>
Specifica per quanto tempo i risultati di una richiesta preflight possono essere memorizzati nella cache in secondi.
Il valore -1
completa l'intestazione Access-Control-Max-Age
con il
valore -1
, che disabilita la memorizzazione nella cache e richiede un controllo
OPTIONS
preflight per tutte le chiamate. Questo aspetto è definito nella
specifica
Access-Control-Max-Age
.
Valore predefinito | 1800 |
Obbligatorio? | Facoltativo |
Tipo | Numero intero |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuna esperienza |
La sintassi dell'elemento <MaxAge>
è la seguente:
Sintassi
<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>
Esempio:
Cache
Questo esempio specifica che i risultati di una richiesta preflight possono essere memorizzati nella cache per 3628800
secondi.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <MaxAge>3628800</MaxAge> </CORS>
Esempio:
Nessuna cache
Questo esempio specifica che i risultati di una richiesta preflight non possono essere memorizzati nella cache.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <MaxAge>-1</MaxAge> </CORS>
Note sull'utilizzo
Richieste OPTIONS
Quando una richiesta
OPTIONS
viene ricevuta ed elaborata dal criterio CORS, l'esecuzione del flusso proxy
viene trasferita direttamente al PreFlow della risposta proxy, ignorando completamente i flussi di richiesta e
continua da lì. Non è necessario creare una condizione per ignorare la richiesta OPTIONS nel flusso di richiesta proxy.
Nelle chiamate successive, quando il criterio CORS viene eseguito, se il valore MaxAge
impostato nel criterio non è scaduto, il flusso continua come di consueto. Durante il flusso di risposta finale immediatamente prima di "Risposta inviata al client", un passaggio speciale di esecuzione CORS "CORSResponseOrErrorFlowExecution" imposta le intestazioni della risposta CORS (Access-Control-Allow-Credentials
, Access-Control-Allow-Origin
e
Access-Control-Expose-Headers
) in modo che restituisca una risposta convalidata da CORS.
Codici di errore
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>
Variabili di flusso
Un oggetto CorsFlowInfo
FlowInfo
verrà aggiunto e potrà essere tracciato.
Proprietà | Tipo | Lettura/scrittura | Descrizione | Inizio ambito |
---|---|---|---|---|
cross_origin_resource_sharing.allow.credentials |
Booleano | Lettura/scrittura | Valore ottenuto da <AllowCredentials> |
Richiesta proxy |
cross_origin_resource_sharing.allow.headers |
Stringa | Lettura/scrittura | Valore ottenuto da <AllowHeaders> |
Richiesta proxy |
cross_origin_resource_sharing.allow.methods |
Stringa | Lettura/scrittura | Valore ottenuto da <AllowMethods> |
Richiesta proxy |
cross_origin_resource_sharing.allow.origin |
Stringa | Lettura/scrittura | L'origine della richiesta consentita, vuota se non è nella lista consentita | Richiesta proxy |
cross_origin_resource_sharing.allow.origins.list |
Stringa | Lettura/scrittura | Valore ottenuto da <AllowOrigins> |
Richiesta proxy |
cross_origin_resource_sharing.expose.headers |
Stringa | Lettura/scrittura | Valore ottenuto da <ExposeHeaders> |
Richiesta proxy |
cross_origin_resource_sharing.max.age |
Numero intero | Lettura/scrittura | Valore ottenuto da <MaxAge> |
Richiesta proxy |
cross_origin_resource_sharing.preflight.accepted |
Booleano | Lettura/scrittura | Indica se la richiesta preflight è accettata | Richiesta proxy |
cross_origin_resource_sharing.request.headers |
Stringa | Lettura/scrittura | Il valore dell'intestazione della richiesta Access-Control-Request-Headers |
Richiesta proxy |
cross_origin_resource_sharing.request.method |
Stringa | Lettura/scrittura | Il valore dell'intestazione della richiesta Access-Control-Request-Method |
Richiesta proxy |
cross_origin_resource_sharing.request.origin |
Stringa | Lettura/scrittura | Uguale a request.header.origin |
Richiesta proxy |
cross_origin_resource_sharing.request.type |
Stringa | Lettura/scrittura |
Tipo di richiesta CORS. Valori possibili:
|
Richiesta proxy |