Criterio CORS

Questa pagina si applica a Apigee e Apigee ibrido.

Visualizza la documentazione di Apigee Edge.

icona norme

Cosa

La condivisione delle risorse tra origini (CORS) è un meccanismo standard che consente alle chiamate JavaScript XMLHttpRequest (XHR) eseguite in una pagina web di interagire con le risorse di 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 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 pubblica l'API Twitter. CORS offre 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 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à di 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/A
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 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 da eseguire con 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 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 name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Facoltativamente, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
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 il preflight) utilizzando le 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 Nessuna

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

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 supporto modello di messaggio*
Elemento principale <CORS>
Elementi secondari Nessuna

* Per maggiori 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

Esempio di CORS allowOrigins

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 verranno serie nell'intestazione Access-Control-Allow-Methods.

Valore predefinito GET, POST, HEAD, OPTIONS
Obbligatorio? Facoltativo
Tipo Stringa, con supporto modello di messaggio*
Elemento principale <CORS>
Elementi secondari Nessuna

* Per maggiori 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 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 di origini autorizzate ad accedere alla risorsa. Utilizza un asterisco (*) per abilitare l'accesso a una risorsa da qualsiasi origine. In caso contrario, fornisci un elenco di origini consentite di origini separate da virgole. Se viene trovata una corrispondenza, il Access-Control-Allow-Origin in uscita viene impostato sull'origine fornita dal client.

Valore predefinito N/A
Obbligatorio? Obbligatorio
Tipo Stringa, con supporto modello di messaggio*
Elemento principale <CORS>
Elementi secondari Nessuna

* Per maggiori 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 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

Questo esempio specifica che tutte le origini possono accedere alla risorsa. 

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>*</AllowOrigins>
</CORS>

<DisplayName>

Utilizzalo in aggiunta all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso e più naturale.

L'elemento <DisplayName> è comune a tutti i criteri.

Valore predefinito N/A
Obbligatorio? Facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio.
Tipo Stringa
Elemento principale <PolicyElement>
Elementi secondari Nessuna esperienza

La sintassi dell'elemento <DisplayName> è la seguente:

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 possono 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 esposte per impostazione predefinita.
Obbligatorio? Facoltativo
Tipo Stringa, con supporto modello di messaggio*
Elemento principale <CORS>
Elementi secondari Nessuna

* Per maggiori 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 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

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 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 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

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 il valore -1, che disabilita la memorizzazione nella cache e richiede un controllo OPTIONS preflight per tutte le chiamate. Questo è definito nella specifica di Access-Control-Max-Age.

Valore predefinito 1800
Obbligatorio? Facoltativo
Tipo Integer
Elemento principale <CORS>
Elementi secondari Nessuna

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 una richiesta OPTIONS viene ricevuta ed elaborata dal criterio CORS, l'esecuzione del flusso proxy viene trasferita direttamente al PreFlow della risposta proxy, saltando completamente il flusso di richieste e continuando da lì. Non è necessario creare una condizione per ignorare la richiesta OPTIONS nel flusso delle richieste proxy.

Nelle chiamate successive, quando viene eseguito il criterio CORS, se il valore MaxAge impostato nel criterio non è scaduto, il flusso continua normalmente. Durante il flusso di risposta finale appena prima di "Risposta inviata al client", un passaggio speciale di esecuzione CORS "CORSResponseOrErrorFlowExecution" imposta le intestazioni delle risposte 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 e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per la gestione degli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e 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 è:
  • Fuori ambito (non disponibile nel flusso specifico in cui viene eseguito il criterio)

    • o

  • Non può essere risolto (non è definito)

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 indicati 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 questo criterio attiva un errore in fase di runtime. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

Variabili Dove Esempio
fault.name = "FAULT_NAME" FAULT_NAME è il nome dell'errore, come indicato nella tabella Errori di runtime riportata 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 per 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 String Lettura/scrittura Valore ottenuto da <AllowHeaders> Richiesta proxy
cross_origin_resource_sharing.allow.methods String Lettura/scrittura Valore ottenuto da <AllowMethods> Richiesta proxy
cross_origin_resource_sharing.allow.origin String Lettura/scrittura L'origine della richiesta consentita, vuota se non è nella lista consentita Richiesta proxy
cross_origin_resource_sharing.allow.origins.list String Lettura/scrittura Valore ottenuto da <AllowOrigins> Richiesta proxy
cross_origin_resource_sharing.expose.headers String Lettura/scrittura Valore ottenuto da <ExposeHeaders> Richiesta proxy
cross_origin_resource_sharing.max.age Integer 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 String Lettura/scrittura Il valore dell'intestazione della richiesta Access-Control-Request-Headers Richiesta proxy
cross_origin_resource_sharing.request.method String Lettura/scrittura Il valore dell'intestazione della richiesta Access-Control-Request-Method Richiesta proxy
cross_origin_resource_sharing.request.origin String Lettura/scrittura Uguale a request.header.origin Richiesta proxy
cross_origin_resource_sharing.request.type String Lettura/scrittura

Tipo di richiesta CORS. Valori possibili:

  • ATTUALE: una richiesta che non sia una richiesta preflight
  • PRE_FLIGHT: una richiesta preflight
 Richiesta proxy