Esta página se aplica a Apigee y Apigee hybrid.
Consulta la documentación de
Apigee Edge.
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 el 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 esta opción si quieren ofrecer el uso compartido de recursos entre dominios.
Un caso práctico de CORS es la función Probar esta API de SmartDocs del portal para desarrolladores. Para obtener información, consulta Configurar un proxy de API para que admita el panel Probar esta API.
La 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 el llamante tiene permiso para enviar la solicitud real (no la de comprobación previa) usando
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 establece el encabezado Access-Control-Allow-Credentials como false.
Es decir, el emisor no tiene permiso para enviar la solicitud real (no la solicitud preliminar) usando 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 ¿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 ¿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
此示例指定允许访问资源的 HTTP 方法。
<CORS continueOnError="false" enabled="true" name="add-cors">
<AllowOrigins>{request.header.origin}</AllowOrigins>
<AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
</CORS>Ejemplo:
Comodín
此示例指定允许所有 HTTP 方法访问资源。
<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 habilitar 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, la Access-Control-Allow-Origin saliente se define como el 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 ¿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
此示例指定允许访问资源的单个网址源。
<CORS continueOnError="false" enabled="true"< name="add-cors"> < AllowOrigins&<gt;https://www.w3.org/AllowOrigins> /CORS>
Ejemplo:
Varias URLs
此示例指定允许访问资源的多个来源。
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>https://www.w3.org, https://www.apache.org</AllowOrigins> </CORS>
Ejemplo:
Variable de contexto
此示例指定一个上下文变量,该变量表示允许访问资源的一个或多个来源。
<CORS continueOnError="false" enabled="true" name="add-cors">
<AllowOrigins>{origins.list}</AllowOrigins>
</CORS>Ejemplo:
Variable de flujo
This example specifies a flow variable that represents one origin that is allowed to access the resource.
<CORS continueOnError="false" enabled="true" name="add-cors">
<AllowOrigins>{request.header.origin}</AllowOrigins>
</CORS>Ejemplo:
Comodín
此示例指定允许所有来源访问资源。
<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 ¿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.credentialscross_origin_resource_sharing.allow.headerscross_origin_resource_sharing.allow.methodscross_origin_resource_sharing.allow.origincross_origin_resource_sharing.allow.origins.listcross_origin_resource_sharing.expose.headerscross_origin_resource_sharing.max.agecross_origin_resource_sharing.preflight.acceptedcross_origin_resource_sharing.request.headerscross_origin_resource_sharing.request.methodcross_origin_resource_sharing.request.origincross_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
此示例指定政策应生成并返回 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.
Se define como 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 especificación
Access-Control-Max-Age.
| 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 de solicitud preliminar 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é
此示例指定无法缓存预检请求的结果。
<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
本部分介绍当此政策触发错误时返回的故障代码和错误消息,以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时,请务必了解此信息。如需了解详情,请参阅您需要了解的有关政策错误的信息和处理故障。
运行时错误
政策执行时可能会发生这些错误。
| 故障代码 | HTTP 状态 | 原因 |
|---|---|---|
steps.cors.UnresolvedVariable |
500 |
如果 CORS 政策中指定的变量为以下任一情况,就会出现此错误:
或 |
部署错误
在您部署包含此政策的代理时,可能会发生这些错误。
| 错误名称 | 原因 |
|---|---|
InvalidMaxAge |
MaxAge 不是数字 |
MissingAllowOrigins |
未指定 AllowOrigins |
InvalidHTTPMethods |
AllowMethods 中的某个方法无效 |
AllowHeadersSizeTooLarge |
AllowHeaders 中的字符串大小过大。 |
ExposeHeadersSizeTooLarge |
ExposeHeaders 中的字符串大小过大。 |
故障变量
当此政策在运行时触发错误时,将设置这些变量。如需了解详情,请参阅您需要了解的有关政策错误的信息。
| 变量 | 其中 | 示例 |
|---|---|---|
fault.name = "FAULT_NAME" |
FAULT_NAME 是故障名称,如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 | fault.name Matches "UnresolveVariable" |
cors.POLICY_NAME.failed |
POLICY_NAME 是抛出故障的政策的用户指定名称。 | cors.AddCORS.failed = true |
错误响应示例
{ "fault":{ "detail":{ "errorcode":"steps.cors.UnresolvedVariable" }, "faultstring":"CORS[AddCORS]: unable to resolve variable wrong.var" } }
故障规则示例
<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 previa. | 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 |