Criterio CORS

Questa pagina si applica ad Apigee e Apigee hybrid.

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 dal codice JavaScript in esecuzione nel 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 dalle applicazioni web.

Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ciascun tipo di ambiente, consulta Tipi di criteri.

Elemento <CORS>

Definisce il criterio CORS.

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>

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

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Ciascuno degli elementi secondari è descritto nelle sezioni che seguono.

Esempi

Nelle sezioni seguenti vengono forniti esempi per tutti gli elementi secondari.

Riferimento all'elemento secondario

In questa sezione vengono descritti gli elementi secondari di <CORS>.

<AllowCredentials>

Indica se l'utente che chiama è autorizzato a inviare la richiesta effettiva (non il preflight) utilizzando le credenziali. Traduce nell'intestazione Access-Control-Allow-Credentials.

L'elemento <AllowCredentials> utilizza 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>
      

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

* Per ulteriori informazioni, vedi Che cos'è un modello di messaggio?

L'elemento <AllowHeaders> utilizza 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>

<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 saranno serie nel Access-Control-Allow-Methods.

* Per ulteriori informazioni, consulta Che cos'è un modello di messaggio?

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

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

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
</CORS>

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowMethods>*</AllowMethods>
</CORS>

<AllowOrigins>

Un elenco di origini che possono 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.

* Per ulteriori informazioni, consulta Che cos'è un modello di messaggio?

L'elemento <AllowOrigins> utilizza 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>

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>https://www.w3.org</AllowOrigins>
</CORS>

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>https://www.w3.org, https://www.apache.org</AllowOrigins>
</CORS>

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{origins.list}</AllowOrigins>
</CORS>

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
</CORS>

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

<DisplayName>

Da utilizzare insieme 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.

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

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

<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. Serializzati nell'intestazione Access-Control-Expose-Headers.

* Per ulteriori informazioni, vedi Che cos'è un modello di messaggio?

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

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

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

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

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
</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.

L'elemento <IgnoreUnresolvedVariables> utilizza 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>

<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. Un valore -1 compila l'intestazione Access-Control-Max-Age con un valore -1, che disattiva la memorizzazione nella cache, richiedendo un controllo preliminare OPTIONS per tutte le chiamate. Questo valore è definito nella specifica Access-Control-Max-Age.

L'elemento <MaxAge> utilizza 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>

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <MaxAge>3628800</MaxAge>
</CORS>

<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 di risposta del proxy, ignorando completamente i flussi di richiesta e proseguendo l'esecuzione da lì. Non è necessario creare una condizione per ignorare la richiesta OPTIONS nel flusso di 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 di esecuzione CORS speciale "CORSResponseOrErrorFlowExecution" imposta le intestazioni della 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 di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Che cosa devi sapere sugli errori relativi alle norme e Gestione dei guasti.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Variabili di errore

Queste variabili vengono impostate quando il criterio attiva un errore in fase di runtime. Per ulteriori informazioni, consulta Cosa devi sapere sugli errori relativi alle norme.

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.