Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza documentazione di Apigee Edge.
Cosa
Condivisione delle risorse tra origini (CORS) è un modello meccanismo che consente alle chiamate JavaScript XMLHttpRequest (XHR) eseguite in una pagina web di interagire con risorse di domini non di origine. CORS è una soluzione comunemente implementata per criterio della stessa origine applicata da tutti i browser.
Ad esempio, se effettui una chiamata XHR all'API Twitter da codice JavaScript in esecuzione nel tuo browser, la chiamata non andrà a buon fine. Questo perché il dominio che pubblica la pagina nel tuo browser non è è uguale al dominio che gestisce l'API Twitter. CORS fornisce una soluzione a questo problema consentendo ai server di eseguire l'attivazione se vogliono fornire la condivisione delle risorse tra origini.
Questo criterio CORS consente ai clienti Apigee di impostare criteri CORS per le API utilizzate dal web diverse applicazioni.
Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutte gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ciascun tipo di ambiente, consulta Tipi di criteri.
<CORS>
elemento
Definisce il criterio CORS.
Valore predefinito | Consulta la scheda Criterio predefinito di seguito |
Obbligatorio? | Obbligatorio |
Tipo | Oggetto complesso |
Elemento principale | N/D |
Elementi secondari |
<AllowCredentials> <AllowHeaders> <AllowMethods> <AllowOrigins> <DisplayName> <ExposeHeaders> <GeneratePreflightResponse> <IgnoreUnresolvedVariables> <MaxAge> |
L'elemento <CORS>
utilizza la seguente sintassi:
Sintassi
L'elemento <CORS>
utilizza la seguente sintassi:
<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 di 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 si inserisce un nuovo criterio CORS
nella UI di Apigee, il modello contiene stub
per tutte le operazioni possibili. In genere, devi selezionare le operazioni con cui eseguire
questo criterio e rimuovere gli altri elementi secondari. Ad esempio, se vuoi specificare
i metodi HTTP autorizzati ad accedere alla risorsa, utilizza l'elemento <AllowMethods>
e rimuovere 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. |
Nelle sezioni che seguono viene descritto ogni elemento secondario.
Esempi
Nelle sezioni seguenti vengono forniti esempi per tutti gli elementi secondari.
Riferimento elemento secondario
In questa sezione vengono descritti gli elementi secondari di <CORS>
.
<AllowCredentials>
Indica se il chiamante può inviare la richiesta effettiva (non la richiesta preliminare) utilizzando
e credenziali. 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 | Nessuno |
L'elemento <AllowCredentials>
utilizza la seguente sintassi:
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
In questo esempio l'intestazione Access-Control-Allow-Credentials
viene impostata su false
.
Ciò significa che 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.
Hai serializzato nel
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 supporto modello di messaggio* |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuno |
* Per ulteriori informazioni, vedi Che cos'è un modello di messaggio?
L'elemento <AllowHeaders>
utilizza la seguente sintassi:
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
Questo esempio specifica le intestazioni HTTP che possono essere utilizzate quando si richiede la risorsa.
<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 di metodi HTTP autorizzati ad accedere alla risorsa. I contenuti saranno
serie nel
Access-Control-Allow-Methods
.
Valore predefinito | GET, POST, HEAD, OPTIONS |
Obbligatorio? | Facoltativo |
Tipo | Stringa, con supporto modello di messaggio* |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuno |
* Per ulteriori informazioni, vedi Che cos'è un modello di messaggio?
L'elemento <AllowMethods>
utilizza la seguente sintassi:
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 possono accedere alla risorsa.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowMethods>*</AllowMethods> </CORS>
<AllowOrigins>
Un elenco di origini autorizzate ad accedere alla risorsa. Utilizza un asterisco (*
)
per abilitare l'accesso a una risorsa da qualsiasi origine. In caso contrario, fornisci una lista consentita
di origini separate da virgole. Se viene trovata una corrispondenza, lo stato
Access-Control-Allow-Origin
è impostata sull'origine fornita dal client.
Valore predefinito | N/D |
Obbligatorio? | Obbligatorio |
Tipo | Stringa, con supporto modello di messaggio* |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuno |
* Per ulteriori informazioni, vedi Che cos'è un modello di messaggio?
L'elemento <AllowOrigins>
utilizza la seguente sintassi:
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 una singola origine URL 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 autorizzate ad 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 autorizzati ad accedere alla risorsa.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{origins.list}</AllowOrigins> </CORS>
Esempio:
Variabile di flusso
Questo esempio specifica un di flusso che rappresenta un'origine autorizzata ad accedere alla risorsa.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> </CORS>
Esempio:
Carattere jolly
Questo esempio specifica che tutte le origini possono accedere alla risorsa.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>*</AllowOrigins> </CORS>
<DisplayName>
Da utilizzare in aggiunta all'attributo name
per etichettare il criterio in
editor proxy UI di gestione con un nome diverso e più naturale.
L'elemento <DisplayName>
è comune a tutti i criteri.
Valore predefinito | N/D |
Obbligatorio? | Facoltativo. Se ometti <DisplayName> , il valore del valore
viene utilizzato l'attributo name del criterio. |
Tipo | Stringa |
Elemento principale | <PolicyElement> |
Elementi secondari | Nessuno |
L'elemento <DisplayName>
utilizza la seguente sintassi:
Sintassi
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
Esempio
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
L'elemento <DisplayName>
non ha attributi o elementi secondari.
<ExposeHeaders>
Un elenco di intestazioni HTTP a cui i browser sono autorizzati ad accedere o un asterisco (*
)
per consentire tutte le intestazioni HTTP.
Serializzato nel
Access-Control-Expose-Headers
.
Valore predefinito | Se non specificato, Access-Control-Expose-Headers non verrà impostato. Le intestazioni non semplici non sono esposte per impostazione predefinita. |
Obbligatorio? | Facoltativo |
Tipo | Stringa, con supporto modello di messaggio* |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuno |
* Per ulteriori informazioni, vedi Che cos'è un modello di messaggio?
L'elemento <ExposeHeaders>
utilizza la seguente sintassi:
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 possono 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 | Nessuno |
L'elemento <GeneratePreflightResponse>
utilizza la seguente sintassi:
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 il file CORS risposta preflight.
<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 | Nessuno |
L'elemento <IgnoreUnresolvedVariables>
utilizza la seguente sintassi:
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
compila l'intestazione Access-Control-Max-Age
con un
valore di -1
, che disabilita la memorizzazione nella cache, richiedendo un preflight
.
OPTIONS
controlla tutte le chiamate. Questo è definito nel
Specifiche
Access-Control-Max-Age
.
Valore predefinito | 1800 |
Obbligatorio? | Facoltativo |
Tipo | Numero intero |
Elemento principale |
<CORS>
|
Elementi secondari | Nessuno |
L'elemento <MaxAge>
utilizza la seguente sintassi:
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
La richiesta OPTIONS
viene ricevuta ed elaborata dal criterio CORS, esecuzione del flusso del proxy
vengono trasferiti direttamente al PreFlow della risposta proxy, saltando del tutto i flussi di richieste e
continua l'esecuzione da lì. Non è necessario creare una condizione per ignorare le opzioni OPTIONS
richiesta nel flusso delle richieste proxy.
Nelle chiamate successive, quando viene eseguito il criterio CORS, se il valore MaxAge
impostato nel criterio non è stato eseguito
scaduto, il flusso continua normalmente. Durante il flusso di risposta finale, appena prima di "Risposta inviata a
"Cliente" un passaggio speciale di esecuzione CORS "CORSResponseOrErrorFlowExecution" imposta la risposta CORS
(Access-Control-Allow-Credentials
, Access-Control-Allow-Origin
e
Access-Control-Expose-Headers
) per restituire una risposta convalidata da CORS.
Codici di errore
Questa sezione descrive i codici e i messaggi di errore restituiti, nonché le variabili di errore. impostate da Apigee quando questo criterio attiva un errore. È importante conoscere queste informazioni se stai sviluppando regole di errore per gestire gli errori. Per saperne di più, vedi Informazioni importanti sugli errori relativi alle norme . Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi quando il criterio viene eseguito.
Codice di errore | Stato HTTP | Causa |
---|---|---|
steps.cors.UnresolvedVariable |
500 |
Questo errore si verifica se una variabile specificata nel criterio CORS è:
o |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome errore | Causa |
---|---|
InvalidMaxAge |
MaxAge non è un numero |
MissingAllowOrigins |
AllowOrigins non è specificato |
InvalidHTTPMethods |
Uno dei metodi in AllowMethods non è valido |
AllowHeadersSizeTooLarge |
La dimensione della stringa in AllowHeaders è troppo grande. |
ExposeHeadersSizeTooLarge |
La dimensione della stringa in ExposeHeaders è troppo grande. |
Variabili di errore
Queste variabili vengono impostate quando il criterio attiva un errore in fase di runtime. Per ulteriori informazioni, vedi Informazioni importanti sugli errori relativi alle norme.
di Gemini Advanced.Variabili | Dove | Esempio |
---|---|---|
fault.name = "FAULT_NAME" |
FAULT_NAME è il nome dell'errore, come elencato in Tabella Errori di runtime qui sopra. Il nome dell'errore è l'ultima parte del codice di errore. | fault.name Matches "UnresolveVariable" |
cors.POLICY_NAME.failed |
POLICY_NAME è il nome specificato dall'utente del criterio che ha generato l'errore. | cors.AddCORS.failed = true |
Esempio di risposta di errore
{ "fault":{ "detail":{ "errorcode":"steps.cors.UnresolvedVariable" }, "faultstring":"CORS[AddCORS]: unable to resolve variable wrong.var" } }
Esempio di regola di errore
<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
Verrà aggiunto un oggetto CorsFlowInfo
FlowInfo
che sarà disponibile
da tracciare.
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 è stata 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 |