Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da Apigee Edge.
O quê
O compartilhamento de recursos entre origens (CORS, na sigla em inglês) é um mecanismo padrão que permite que chamadas JavaScript XMLHttpRequest (XHR) executadas em uma página da Web interajam com recursos de domínios que não são de origem. O CORS é uma solução comumente implementada na política de mesma origem que é aplicada por todos os navegadores.
Por exemplo, se você fizer uma chamada XHR para a API Twitter a partir do código JavaScript em execução no seu navegador, a chamada falhará. Isso ocorre porque o domínio que veicula a página para o navegador não é o mesmo que usa a API Twitter. O CORS oferece uma solução para esse problema permitindo que os servidores optem por permitir o compartilhamento de recursos entre origens.
Essa política de CORS permite que os clientes da Apigee definam políticas de CORS para APIs consumidas por aplicativos da Web.
Esta é uma política padrão e pode ser implantada em qualquer tipo de ambiente. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.
Elemento <CORS>
Define a política de CORS.
Valor padrão | Consulte a guia Política padrão a seguir |
Obrigatório? | Obrigatório |
Tipo | Objeto complexo |
Elemento pai | N/A |
Elemento filho |
<AllowCredentials> <AllowHeaders> <AllowMethods> <AllowOrigins> <DisplayName> <ExposeHeaders> <GeneratePreflightResponse> <IgnoreUnresolvedVariables> <MaxAge> |
O elemento <CORS>
usa a seguinte sintaxe:
Sintaxe
O elemento <CORS>
usa a seguinte sintaxe:
<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_padrão
O exemplo a seguir mostra as configurações padrão quando você adiciona a política de CORS ao fluxo na IU do 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 você insere uma nova política CORS
na IU do Apigee, o modelo contém stubs para todas
as operações possíveis. Normalmente, você seleciona quais operações quer executar com essa política
e remove o restante dos elementos filhos. Por exemplo, se você quiser especificar os métodos HTTP com permissão para acessar o recurso, use o elemento <AllowMethods>
e remova os outros elementos filhos da política para torná-la mais seja legível.
Este elemento tem os seguintes atributos comuns a todas as políticas:
Atributo | Padrão | Obrigatório? | Descrição |
---|---|---|---|
name |
N/A | Valor |
O nome interno da política. O valor do atributo Opcionalmente, use o elemento |
continueOnError |
falso | Opcional | Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para
a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política
falhar. Consulte também:
|
enabled |
true | Opcional | Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo. |
async |
falso | Obsoleto | Esse atributo está obsoleto. |
Cada um desses elementos filhos é descrito nas seções a seguir.
Exemplos
Veja exemplos para todos os elementos filhos nas seções a seguir.
Referência a elementos filhos
Esta seção descreve os elementos filhos de <CORS>
.
<AllowCredentials>
Indica se o autor da chamada tem permissão para enviar a solicitação real (não a simulação) usando credenciais. Traduz para o cabeçalho Access-Control-Allow-Credentials
.
Valor padrão | Se não for especificado, Access-Control-Allow-Credentials não será definido. |
Obrigatório? | Opcional |
Tipo | Booleano |
Elemento pai |
<CORS>
|
Elemento filho | Nenhum |
O elemento <AllowCredentials>
usa a seguinte sintaxe:
Sintaxe
<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>
Exemplo
Neste exemplo, definimos o cabeçalho Access-Control-Allow-Credentials
como false
.
Ou seja, o autor da chamada não tem permissão para enviar a solicitação real (não a simulação) usando credenciais.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowCredentials>false</AllowCredentials> </CORS>
<AllowHeaders>
Lista de cabeçalhos HTTP que podem ser usados ao solicitar o recurso.
Serializada para o cabeçalho Access-Control-Allow-Headers
.
Valor padrão | Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers |
Obrigatório? | Opcional |
Tipo | String, compatível com modelo de mensagem* |
Elemento pai |
<CORS>
|
Elemento filho | Nenhum |
* Para mais informações, consulte O que é um modelo de mensagem?
O elemento <AllowHeaders>
usa a seguinte sintaxe:
Sintaxe
<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>
Exemplo
Este exemplo especifica os cabeçalhos HTTP que podem ser usados ao solicitar o 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 com permissão para acessar o recurso. O conteúdo será
serializado no
cabeçalho Access-Control-Allow-Methods
.
Valor padrão | GET, POST, HEAD, OPTIONS |
Obrigatório? | Opcional |
Tipo | String, compatível com modelo de mensagem* |
Elemento pai |
<CORS>
|
Elemento filho | Nenhum |
* Para mais informações, consulte O que é um modelo de mensagem?
O elemento <AllowMethods>
usa a seguinte sintaxe:
Sintaxe
<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>
Exemplo:
lista
Neste exemplo, são especificados os métodos HTTP que têm permissão para acessar o recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowMethods>GET, PUT, POST, DELETE</AllowMethods> </CORS>
Exemplo:
caractere curinga
Este exemplo especifica que todos os métodos HTTP têm permissão para acessar o recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <AllowMethods>*</AllowMethods> </CORS>
<AllowOrigins>
Uma lista de origens que têm permissão para acessar o recurso. Use um asterisco (*
) para ativar o acesso a um recurso de qualquer origem. Caso contrário, forneça uma lista de permissões de origens separadas por vírgulas. Se uma correspondência for encontrada, o Access-Control-Allow-Origin
de saída será definido como a origem fornecida pelo cliente.
Valor padrão | N/A |
Obrigatório? | Obrigatório |
Tipo | String, compatível com modelo de mensagem* |
Elemento pai |
<CORS>
|
Elemento filho | Nenhum |
* Para mais informações, consulte O que é um modelo de mensagem?
O elemento <AllowOrigins>
usa a seguinte sintaxe:
Sintaxe
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins> </CORS>
Exemplo:
URL único
Este exemplo especifica uma única origem de URL que pode acessar o recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>https://www.w3.org</AllowOrigins> </CORS>
Exemplo:
vários URLs
Neste exemplo, são especificadas várias origens que têm permissão para acessar o recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>https://www.w3.org, https://www.apache.org</AllowOrigins> </CORS>
Exemplo:
variável de contexto
Neste exemplo, especificamos uma variável de contexto que representa uma ou mais origens com permissão para acessar o recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{origins.list}</AllowOrigins> </CORS>
Exemplo:
variável de fluxo
Neste exemplo, especificamos uma variável de fluxo que representa uma origem com permissão para acessar o recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> </CORS>
Exemplo:
caractere curinga
Este exemplo especifica que todas as origens têm permissão para acessar o recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>*</AllowOrigins> </CORS>
<DisplayName>
Use além do atributo name
para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.
O elemento <DisplayName>
é comum a todas as políticas.
Valor padrão | N/A |
Obrigatório? | Opcional. Se você omitir <DisplayName> , o valor do atributo name da política será usado |
Tipo | String |
Elemento pai | <PolicyElement> |
Elemento filho | Nenhum |
O elemento <DisplayName>
usa a seguinte sintaxe:
Sintaxe
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
Exemplo
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
O elemento <DisplayName>
não tem atributos ou elementos filhos.
<ExposeHeaders>
Uma lista de cabeçalhos HTTP que os navegadores podem acessar ou um asterisco (*
)
para permitir todos os cabeçalhos HTTP.
Serializada no
cabeçalho Access-Control-Expose-Headers
.
Valor padrão | Se não for especificado, Access-Control-Expose-Headers não será definido. Cabeçalhos não simples não são expostos por padrão. |
Obrigatório? | Opcional |
Tipo | String, compatível com modelo de mensagem* |
Elemento pai |
<CORS>
|
Elemento filho | Nenhum |
* Para mais informações, consulte O que é um modelo de mensagem?
O elemento <ExposeHeaders>
usa a seguinte sintaxe:
Sintaxe
<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>
Exemplo
Este exemplo especifica que os navegadores podem acessar todos os cabeçalhos HTTP.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <ExposeHeaders>*</ExposeHeaders> </CORS>
<GeneratePreflightResponse>
Indique se a política precisa gerar e retornar a resposta de simulação do CORS.
Se false
, nenhuma resposta será enviada. Em vez disso, as seguintes variáveis de fluxo são preenchidas:
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 padrão | true |
Obrigatório? | Opcional |
Tipo | Booleano |
Elemento pai |
<CORS>
|
Elemento filho | Nenhum |
O elemento <GeneratePreflightResponse>
usa a seguinte sintaxe:
Sintaxe
<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME"> <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse> <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse> </CORS>
Exemplo
Este exemplo especifica que a política precisa gerar e retornar a resposta de simulação do CORS.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <GeneratePreflightResponse>true</GeneratePreflightResponse> </CORS>
<IgnoreUnresolvedVariables>
Determina se o processamento é interrompido quando uma variável não resolvida é encontrada.
Defina como true
para ignorar variáveis não resolvidas e continuar o processamento. Caso contrário, false
.
Valor padrão | true |
Obrigatório? | Opcional |
Tipo | Booleano |
Elemento pai |
<CORS>
|
Elemento filho | Nenhum |
O elemento <IgnoreUnresolvedVariables>
usa a seguinte sintaxe:
Sintaxe
<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>
Exemplo
Este exemplo especifica que o processamento continua quando uma variável não resolvida é encontrada.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </CORS>
<MaxAge>
Especifica por quanto tempo os resultados de uma solicitação de simulação podem ser armazenados em cache em segundos.
Um valor de -1
preenche o cabeçalho Access-Control-Max-Age
com um valor de -1
, o que desativa o armazenamento em cache, exigindo uma simulação
OPTIONS
verificar todas as chamadas. Isso é definido na especificação
Access-Control-Max-Age
.
Valor padrão | 1800 |
Obrigatório? | Opcional |
Tipo | Número inteiro |
Elemento pai |
<CORS>
|
Elemento filho | Nenhum |
O elemento <MaxAge>
usa a seguinte sintaxe:
Sintaxe
<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>
Exemplo:
Cache
Este exemplo especifica que os resultados de uma solicitação de simulação
podem ser armazenados em cache por 3628800
segundos.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <MaxAge>3628800</MaxAge> </CORS>
Exemplo:
Sem cache
Este exemplo especifica que os resultados de uma solicitação de simulação não podem ser armazenados em cache.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <MaxAge>-1</MaxAge> </CORS>
Observações sobre uso
Solicitações OPTIONS
Quando uma solicitação OPTIONS
é recebida e processada pela política de CORS, a execução do fluxo do proxy é transferida diretamente para o pré-fluxo de resposta do proxy, ignorando completamente os fluxos de solicitação e continua a partir daí. Não é necessário criar uma condição para ignorar a solicitação OPTIONS no fluxo de solicitações do proxy.
Nas chamadas subsequentes, quando a política de CORS for executada, se o MaxAge
definido na política não tiver expirado, o fluxo continuará normalmente. Durante o fluxo de resposta final, logo antes de "Resposta enviada ao cliente", uma etapa especial de execução do CORS "CORSResponseOrErrorFlowExecution" define os cabeçalhos de resposta do CORS (Access-Control-Allow-Credentials
, Access-Control-Allow-Origin
e Access-Control-Expose-Headers
) para retornar uma resposta validada pelo CORS.
Códigos de erro
Nesta seção, descrevemos os códigos de falha e as mensagens de erro retornadas e as variáveis com falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.
Erros de execução
Esses erros podem ocorrer quando a política é executada.
Código de falha | Status HTTP | Causa |
---|---|---|
steps.cors.UnresolvedVariable |
500 |
Esse erro ocorrerá se uma variável especificada na política CORS:
ou |
Erros na implantação
Esses erros podem ocorrer quando você implanta um proxy que contém esta política.
Nome do erro | Causa |
---|---|
InvalidMaxAge |
MaxAge não é um número |
MissingAllowOrigins |
AllowOrigins não especificado |
InvalidHTTPMethods |
Um dos métodos em AllowMethods não é válido |
AllowHeadersSizeTooLarge |
O tamanho da string em AllowHeaders é muito grande. |
ExposeHeadersSizeTooLarge |
O tamanho da string em ExposeHeaders é muito grande. |
Variáveis de falha
Essas variáveis são definidas quando essa política aciona um erro no ambiente de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.
Variáveis | Onde | Exemplo |
---|---|---|
fault.name = "FAULT_NAME" |
FAULT_NAME é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha. | fault.name Matches "UnresolveVariable" |
cors.POLICY_NAME.failed |
POLICY_NAME é o nome da política especificada pelo usuário que gerou a falha. | cors.AddCORS.failed = true |
Exemplo de resposta de erro
{ "fault":{ "detail":{ "errorcode":"steps.cors.UnresolvedVariable" }, "faultstring":"CORS[AddCORS]: unable to resolve variable wrong.var" } }
Exemplo de regra de falha
<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>
Variáveis de fluxo
Um objeto CorsFlowInfo
FlowInfo
será adicionado e ficará disponível para rastreamento.
Propriedade | Tipo | Leitura/gravação | Descrição | O escopo começa |
---|---|---|---|---|
cross_origin_resource_sharing.allow.credentials |
Booleano | Leitura/gravação | Valor de <AllowCredentials> |
Solicitação de proxy |
cross_origin_resource_sharing.allow.headers |
String | Leitura/gravação | Valor de <AllowHeaders> |
Solicitação de proxy |
cross_origin_resource_sharing.allow.methods |
String | Leitura/gravação | Valor de <AllowMethods> |
Solicitação de proxy |
cross_origin_resource_sharing.allow.origin |
String | Leitura/gravação | A origem da solicitação permitida, vazia se não estiver na lista de permissões | Solicitação de proxy |
cross_origin_resource_sharing.allow.origins.list |
String | Leitura/gravação | Valor de <AllowOrigins> |
Solicitação de proxy |
cross_origin_resource_sharing.expose.headers |
String | Leitura/gravação | Valor de <ExposeHeaders> |
Solicitação de proxy |
cross_origin_resource_sharing.max.age |
Número inteiro | Leitura/gravação | Valor de <MaxAge> |
Solicitação de proxy |
cross_origin_resource_sharing.preflight.accepted |
Booleano | Leitura/gravação | Indica se a solicitação de simulação é aceita. | Solicitação de proxy |
cross_origin_resource_sharing.request.headers |
String | Leitura/gravação | O valor do cabeçalho Access-Control-Request-Headers da solicitação |
Solicitação de proxy |
cross_origin_resource_sharing.request.method |
String | Leitura/gravação | O valor do cabeçalho Access-Control-Request-Method da solicitação |
Solicitação de proxy |
cross_origin_resource_sharing.request.origin |
String | Leitura/gravação | O mesmo que request.header.origin |
Solicitação de proxy |
cross_origin_resource_sharing.request.type |
String | Leitura/gravação |
Tipo de solicitação de CORS. Valores possíveis:
|
Solicitação de proxy |