Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de
Apigee Edge.
Qué
El uso compartido de recursos entre dominios (CORS) es un mecanismo estándar que permite que las llamadas XMLHttpRequest (XHR) de JavaScript ejecutadas en una página web interactúen con recursos de dominios que no son de origen. CORS es una solución que se implementa habitualmente para la política de coincidencia de origen que aplican todos los navegadores.
Por ejemplo, si haces una llamada XHR a la API de Twitter desde un código JavaScript que se ejecuta en tu navegador, la llamada fallará. Esto se debe a que el dominio que sirve la página a tu navegador no es el mismo que el que sirve la API de Twitter. CORS ofrece una solución a este problema, ya que permite que los servidores habiliten el uso compartido de recursos entre dominios.
Esta política de CORS permite a los clientes de Apigee definir políticas de CORS para las APIs que consumen las aplicaciones web.
Esta política es una política estándar y se puede implementar en cualquier tipo de entorno. Para obtener información sobre los tipos de políticas y la disponibilidad de cada tipo de entorno, consulta Tipos de políticas.
Elemento <CORS>
Define la política de CORS.
Valor predeterminado | Consulta la pestaña Política predeterminada que aparece más abajo. |
¿Es obligatorio? | Obligatorio |
Tipo | Objeto complejo |
Elemento principal | N/A |
Elementos secundarios |
<AllowCredentials> <AllowHeaders> <AllowMethods> <AllowOrigins> <DisplayName> <ExposeHeaders> <GeneratePreflightResponse> <IgnoreUnresolvedVariables> <MaxAge> |
El elemento <CORS>
utiliza la siguiente sintaxis:
Sintaxis
El elemento <CORS>
utiliza la siguiente sintaxis:
<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>
Política predeterminada
En el siguiente ejemplo se muestran los ajustes predeterminados al añadir la política de CORS a tu flujo en la interfaz de 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>
Cuando insertas una nueva política CORS
en la interfaz de Apigee, la plantilla contiene stubs
para todas las operaciones posibles. Normalmente, se seleccionan las operaciones que se quieren realizar con esta política y se eliminan el resto de los elementos secundarios. Por ejemplo, si quiere especificar los métodos HTTP permitidos para acceder al recurso, utilice el elemento <AllowMethods>
y quite los demás elementos secundarios de la política para que sea más legible.
Este elemento tiene los siguientes atributos, que son comunes a todas las políticas:
Atributo | Predeterminado | ¿Es obligatorio? | Descripción |
---|---|---|---|
name |
N/A | Obligatorio |
El nombre interno de la política. El valor del atributo Opcionalmente, usa el elemento |
continueOnError |
falso | Opcional | Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también:
|
enabled |
true | Opcional | Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo. |
async |
falso | Obsoleto | Este atributo está obsoleto. |
Cada uno de los elementos secundarios se describe en las secciones siguientes.
Ejemplos
En las secciones siguientes se proporcionan ejemplos de todos los elementos secundarios.
Referencia de elemento secundario
En esta sección se describen los elementos secundarios de <CORS>
.
<AllowCredentials>
Indica si la persona que llama tiene permiso para enviar la solicitud real (no la de comprobación previa) mediante
credenciales. Se traduce al encabezado Access-Control-Allow-Credentials
.
Valor predeterminado | Si no se especifica, no se definirá Access-Control-Allow-Credentials . |
¿Es obligatorio? | Opcional |
Tipo | Booleano |
Elemento principal |
<CORS>
|
Elementos secundarios | Ninguno |
El elemento <AllowCredentials>
utiliza la siguiente sintaxis:
Sintaxis
<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>
Ejemplo
En este ejemplo, se asigna el valor false
al encabezado Access-Control-Allow-Credentials
.
Es decir, el llamante no puede enviar la solicitud real (no la de comprobación previa) con credenciales.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowCredentials>false</AllowCredentials> </CORS>
<AllowHeaders>
Lista de encabezados HTTP que se pueden usar al solicitar el recurso.
Serializado en el encabezado Access-Control-Allow-Headers
.
Valor predeterminado | Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers |
¿Es obligatorio? | Opcional |
Tipo | Cadena con compatibilidad con plantillas de mensajes* |
Elemento principal |
<CORS>
|
Elementos secundarios | Ninguno |
* Para obtener más información, consulta el artículo ¿Qué es una plantilla de mensaje?
El elemento <AllowHeaders>
utiliza la siguiente sintaxis:
Sintaxis
<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>
Ejemplo
En este ejemplo, se especifican los encabezados HTTP que se pueden usar cuando se solicita el recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowHeaders>origin, x-requested-with, accept, content-type</AllowHeaders> </CORS>
<AllowMethods>
Lista de métodos HTTP permitidos para acceder al recurso. El contenido se
serializará en el
encabezado Access-Control-Allow-Methods
.
Valor predeterminado | GET, POST, HEAD, OPTIONS |
¿Es obligatorio? | Opcional |
Tipo | Cadena, con compatibilidad con plantillas de mensajes* |
Elemento principal |
<CORS>
|
Elementos secundarios | Ninguno |
* Para obtener más información, consulta el artículo ¿Qué es una plantilla de mensaje?
El elemento <AllowMethods>
utiliza la siguiente sintaxis:
Sintaxis
<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>
Ejemplo:
Lista
En este ejemplo, se especifican los métodos HTTP que pueden acceder al recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowMethods>GET, PUT, POST, DELETE</AllowMethods> </CORS>
Ejemplo:
comodín
En este ejemplo, se especifica que todos los métodos HTTP pueden acceder al recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowMethods>*</AllowMethods> </CORS>
<AllowOrigins>
Lista de orígenes que tienen permiso para acceder al recurso. Usa un asterisco (*
) para permitir el acceso a un recurso desde cualquier origen. De lo contrario, proporcione una lista de permitidos
de orígenes separados por comas. Si se encuentra una coincidencia, el valor de salida Access-Control-Allow-Origin
se asigna al origen proporcionado por el cliente.
Valor predeterminado | N/A |
¿Es obligatorio? | Obligatorio |
Tipo | Cadena, con compatibilidad con plantillas de mensajes* |
Elemento principal |
<CORS>
|
Elementos secundarios | Ninguno |
* Para obtener más información, consulta el artículo ¿Qué es una plantilla de mensaje?
El elemento <AllowOrigins>
utiliza la siguiente sintaxis:
Sintaxis
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins> </CORS>
Ejemplo:
URL único
En este ejemplo se especifica un único origen de URL que tiene permiso para acceder al recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>https://www.w3.org</AllowOrigins> </CORS>
Ejemplo:
Varias URLs
En este ejemplo se especifican varios orígenes que tienen permiso para acceder al recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>https://www.w3.org, https://www.apache.org</AllowOrigins> </CORS>
Ejemplo:
Variable de contexto
En este ejemplo, se especifica una variable de contexto que representa uno o más orígenes que pueden acceder al recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{origins.list}</AllowOrigins> </CORS>
Ejemplo:
Variable de flujo
En este ejemplo se especifica una variable de flujo que representa un origen que tiene permiso para acceder al recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> </CORS>
Ejemplo:
comodín
En este ejemplo, se especifica que todos los orígenes pueden acceder al recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>*</AllowOrigins> </CORS>
<DisplayName>
Se usa junto con el atributo name
para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente que suene más natural.
El elemento <DisplayName>
es común a todas las políticas.
Valor predeterminado | N/A |
¿Es obligatorio? | Opcional. Si omite <DisplayName> , se usará el valor del atributo name de la política. |
Tipo | Cadena |
Elemento principal | <PolicyElement> |
Elementos secundarios | Ninguno |
El elemento <DisplayName>
utiliza la siguiente sintaxis:
Sintaxis
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
Ejemplo
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
El elemento <DisplayName>
no tiene atributos ni elementos secundarios.
<ExposeHeaders>
Lista de encabezados HTTP a los que pueden acceder los navegadores o un asterisco (*
) para permitir todos los encabezados HTTP.
Serializado en el encabezado
Access-Control-Expose-Headers
.
Valor predeterminado | Si no se especifica, no se definirá Access-Control-Expose-Headers . Los encabezados no simples no se exponen de forma predeterminada. |
¿Es obligatorio? | Opcional |
Tipo | Cadena, con compatibilidad con plantillas de mensajes* |
Elemento principal |
<CORS>
|
Elementos secundarios | Ninguno |
* Para obtener más información, consulta el artículo ¿Qué es una plantilla de mensaje?
El elemento <ExposeHeaders>
utiliza la siguiente sintaxis:
Sintaxis
<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>
Ejemplo
En este ejemplo se especifica que los navegadores pueden acceder a todos los encabezados HTTP.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <ExposeHeaders>*</ExposeHeaders> </CORS>
<GeneratePreflightResponse>
Indica si la política debe generar y devolver la respuesta de solicitud preparatoria CORS.
Si false
, no se envía ninguna respuesta. En su lugar, se rellenan las siguientes variables de flujo:
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
Valor predeterminado | true |
¿Es obligatorio? | Opcional |
Tipo | Booleano |
Elemento principal |
<CORS>
|
Elementos secundarios | Ninguno |
El elemento <GeneratePreflightResponse>
utiliza la siguiente sintaxis:
Sintaxis
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse> <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse> </CORS>
Ejemplo
En este ejemplo, se especifica que la política debe generar y mostrar la respuesta de solicitud preliminar de CORS.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <GeneratePreflightResponse>true</GeneratePreflightResponse> </CORS>
<IgnoreUnresolvedVariables>
Determina si el procesamiento se detiene cuando se encuentra una variable sin resolver.
true
para ignorar las variables sin resolver y continuar con el procesamiento;
de lo contrario, false
.
Valor predeterminado | true |
¿Es obligatorio? | Opcional |
Tipo | Booleano |
Elemento principal |
<CORS>
|
Elementos secundarios | Ninguno |
El elemento <IgnoreUnresolvedVariables>
utiliza la siguiente sintaxis:
Sintaxis
<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>
Ejemplo
En este ejemplo se especifica que el procesamiento continúa cuando se encuentra una variable sin resolver.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </CORS>
<MaxAge>
Especifica durante cuánto tiempo se pueden almacenar en caché los resultados de una solicitud de comprobación previa en segundos.
Si se asigna el valor -1
al encabezado Access-Control-Max-Age
, se inhabilita el almacenamiento en caché, por lo que se requiere una comprobación previa
OPTIONS
para todas las llamadas.-1
Esto se define en la
Access-Control-Max-Age
especificación.
Valor predeterminado | 1800 |
¿Es obligatorio? | Opcional |
Tipo | Entero |
Elemento principal |
<CORS>
|
Elementos secundarios | Ninguno |
El elemento <MaxAge>
utiliza la siguiente sintaxis:
Sintaxis
<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>
Ejemplo:
Caché
En este ejemplo se especifica que los resultados de una solicitud preflight se pueden almacenar en caché durante 3628800
segundos.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <MaxAge>3628800</MaxAge> </CORS>
Ejemplo:
Sin caché
En este ejemplo, se especifica que los resultados de una solicitud de solicitud preliminar no se pueden almacenar en caché.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <MaxAge>-1</MaxAge> </CORS>
Notas de uso
Solicitudes de OPTIONS
Cuando la política de CORS recibe y procesa una solicitud
OPTIONS
, la ejecución del flujo del proxy se transfiere directamente al PreFlow de respuesta del proxy, se omiten por completo los flujos de solicitud y la ejecución continúa desde ahí. No es necesario crear una condición para ignorar la solicitud OPTIONS
en el flujo de solicitudes de proxy.
En las llamadas posteriores, cuando se ejecute la política de CORS, si el MaxAge
definido en la política no ha caducado, el flujo continuará con normalidad. Durante el flujo de respuesta final, justo antes de "Respuesta enviada al cliente", un paso de ejecución de CORS especial ("CORSResponseOrErrorFlowExecution") define los encabezados de respuesta de CORS (Access-Control-Allow-Credentials
, Access-Control-Allow-Origin
y Access-Control-Expose-Headers
) para devolver una respuesta validada por CORS.
Códigos de error
En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Soluciona fallas.
Errores de entorno de ejecución
Estos errores pueden producirse cuando se ejecuta la política.
Código de falla | Estado de HTTP | Causa |
---|---|---|
steps.cors.UnresolvedVariable |
500 |
Este error se produce si una variable especificada en la política CORS es una de las siguientes:
o |
Errores en la implementación
Estos errores pueden generarse cuando implementas un proxy que contiene esta política.
Nombre del error | Causa |
---|---|
InvalidMaxAge |
MaxAge no es un número |
MissingAllowOrigins |
AllowOrigins no se especificó |
InvalidHTTPMethods |
Uno de los métodos de AllowMethods no es válido |
AllowHeadersSizeTooLarge |
El tamaño de la string en AllowHeaders es demasiado grande. |
ExposeHeadersSizeTooLarge |
El tamaño de la string en ExposeHeaders es demasiado grande. |
Variables con fallas
Estas variables se configuran cuando esta política activa un error en el entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.
Variables | Donde | Ejemplo |
---|---|---|
fault.name = "FAULT_NAME" |
FAULT_NAME es el nombre de la falla, como se indica en la tabla Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. | fault.name Matches "UnresolveVariable" |
cors.POLICY_NAME.failed |
POLICY_NAME es el nombre especificado por el usuario de la política que generó la falla. | cors.AddCORS.failed = true |
Ejemplo de respuesta de error
{ "fault":{ "detail":{ "errorcode":"steps.cors.UnresolvedVariable" }, "faultstring":"CORS[AddCORS]: unable to resolve variable wrong.var" } }
Ejemplo de regla de falla
<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>
Variables de flujo
Se añadirá un objeto CorsFlowInfo
FlowInfo
y estará disponible para el seguimiento.
Propiedad | Tipo | Lectura y escritura | Descripción | Comienza el ámbito |
---|---|---|---|---|
cross_origin_resource_sharing.allow.credentials |
Booleano | Lectura y escritura | Valor de <AllowCredentials> |
Solicitud de proxy |
cross_origin_resource_sharing.allow.headers |
Cadena | Lectura y escritura | Valor de <AllowHeaders> |
Solicitud de proxy |
cross_origin_resource_sharing.allow.methods |
Cadena | Lectura y escritura | Valor de <AllowMethods> |
Solicitud de proxy |
cross_origin_resource_sharing.allow.origin |
Cadena | Lectura y escritura | El origen de la solicitud que se permite. Si no está en la lista de permitidos, estará vacío. | Solicitud de proxy |
cross_origin_resource_sharing.allow.origins.list |
Cadena | Lectura y escritura | Valor de <AllowOrigins> |
Solicitud de proxy |
cross_origin_resource_sharing.expose.headers |
Cadena | Lectura y escritura | Valor de <ExposeHeaders> |
Solicitud de proxy |
cross_origin_resource_sharing.max.age |
Entero | Lectura y escritura | Valor de <MaxAge> |
Solicitud de proxy |
cross_origin_resource_sharing.preflight.accepted |
Booleano | Lectura y escritura | Indica si se acepta la solicitud de comprobación preliminar. | Solicitud de proxy |
cross_origin_resource_sharing.request.headers |
Cadena | Lectura y escritura | Valor del encabezado Access-Control-Request-Headers de la solicitud |
Solicitud de proxy |
cross_origin_resource_sharing.request.method |
Cadena | Lectura y escritura | Valor del encabezado Access-Control-Request-Method de la solicitud |
Solicitud de proxy |
cross_origin_resource_sharing.request.origin |
Cadena | Lectura y escritura | Igual que request.header.origin |
Solicitud de proxy |
cross_origin_resource_sharing.request.type |
Cadena | Lectura y escritura |
Tipo de solicitud CORS. Posibles valores:
|
Solicitud de proxy |