Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Ver documentação do
Apigee Edge.
A partilha de recursos de origem cruzada (CORS) é um mecanismo padrão que permite que as chamadas JavaScript XMLHttpRequest (XHR) executadas numa página Web interajam com recursos de domínios não originais. A CORS é uma solução implementada frequentemente para a política de mesma origem aplicada por todos os navegadores.
Por exemplo, se fizer uma chamada XHR à API Twitter a partir de código JavaScript executado no seu navegador, a chamada falha. Isto deve-se ao facto de o domínio que publica a página no seu navegador não ser o mesmo que o domínio que publica a API Twitter. O CORS oferece uma solução para este problema ao permitir que os servidores optem por partilhar recursos de origem cruzada.
Um exemplo de utilização da CORS é a funcionalidade Experimentar esta API do SmartDocs do portal do programador. Para mais informações, consulte o artigo Configurar o proxy de API para suportar o painel Experimentar esta API.
A política CORS permite que os clientes do Apigee definam políticas CORS para APIs consumidas por aplicações Web.
Esta política é uma política padrão e pode ser implementada em qualquer tipo de ambiente. Para obter informações sobre os tipos de políticas e a disponibilidade com cada tipo de ambiente, consulte Tipos de políticas.
<CORS> elemento
Define a política de CORS.
| Valor predefinido | Consulte o separador Política predefinida abaixo |
| Obrigatório? | Obrigatória |
| Tipo | Objeto complexo |
| Elemento principal | N/A |
| Elementos subordinados |
<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 predefinida
O exemplo seguinte mostra as predefinições quando adiciona a política CORS ao seu 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 insere uma nova política CORS na IU do Apigee, o modelo contém stubs
para todas as operações possíveis. Normalmente, seleciona as operações que quer realizar com esta política e remove os restantes elementos secundários. Por exemplo, se quiser especificar os métodos HTTP permitidos para aceder ao recurso, use o elemento <AllowMethods> e remova os outros elementos subordinados da política para a tornar mais legível.
Este elemento tem os seguintes atributos comuns a todas as políticas:
| Atributo | Predefinição | Obrigatório? | Descrição |
|---|---|---|---|
name |
N/A | Obrigatório |
O nome interno da política. O valor do atributo Opcionalmente, use o elemento |
continueOnError |
falso | Opcional | Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também:
|
enabled |
verdadeiro | Opcional | Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça anexada a um fluxo. |
async |
falso | Descontinuado | Este atributo foi descontinuado. |
Cada um dos elementos secundários é descrito nas secções que se seguem.
Exemplos
São fornecidos exemplos para todos os elementos secundários nas secções seguintes.
Referência de elemento secundário
Esta secção descreve os elementos subordinados de <CORS>.
<AllowCredentials>
Indica se o autor da chamada tem autorização para enviar o pedido real (não o preflight) através de credenciais. Traduz-se no cabeçalho Access-Control-Allow-Credentials.
| Valor predefinido | Se não for especificado, Access-Control-Allow-Credentials não é definido. |
| Obrigatório? | Opcional |
| Tipo | Booleano |
| Elemento principal |
<CORS>
|
| Elementos subordinados | 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
Este exemplo define o cabeçalho Access-Control-Allow-Credentials como false.
Ou seja, o autor da chamada não tem autorização para enviar o pedido real (não o pedido prévio)
com 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 quando pede o recurso.
Serializado para o cabeçalho Access-Control-Allow-Headers.
| Valor predefinido | Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers |
| Obrigatório? | Opcional |
| Tipo | String, com suporte de modelo de mensagem* |
| Elemento principal |
<CORS>
|
| Elementos subordinados | 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
This example specifies the HTTP headers that can be used when requesting the resource.
<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 aceder ao recurso. O conteúdo vai ser
serializado no cabeçalho
Access-Control-Allow-Methods.
| Valor predefinido | GET, POST, HEAD, OPTIONS |
| Obrigatório? | Opcional |
| Tipo | String, com suporte de modelo de mensagem* |
| Elemento principal |
<CORS>
|
| Elementos subordinados | 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
Este exemplo especifica os métodos HTTP que têm autorização para aceder ao recurso.
<CORS continueOnError="false" enabled="true" name="add-cors">
<AllowOrigins>{request.header.origin}</AllowOrigins>
<AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
</CORS>Exemplo:
Wildcard
Este exemplo especifica que todos os métodos HTTP têm autorização para aceder ao 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 autorização para aceder ao recurso. Use um asterisco (*)
para permitir o acesso a um recurso a partir de qualquer origem. Caso contrário, forneça uma lista de autorizações
de origens separadas por vírgulas. Se for encontrada uma correspondência, o Access-Control-Allow-Origin de saída é definido como a origem fornecida pelo cliente.
| Valor predefinido | N/A |
| Obrigatório? | Obrigatória |
| Tipo | String, com suporte de modelo de mensagem* |
| Elemento principal |
<CORS>
|
| Elementos subordinados | 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 tem autorização para aceder ao recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>https://www.w3.org</AllowOrigins> </CORS>
Exemplo:
vários URLs
Este exemplo especifica várias origens que têm autorização para aceder ao 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
Este exemplo especifica uma variável de contexto que representa uma ou mais origens que têm permissão para aceder ao recurso.
<CORS continueOnError="false" enabled="true" name="add-cors">
<AllowOrigins>{origins.list}</AllowOrigins>
</CORS>Exemplo:
Variável de fluxo
Este exemplo especifica uma variável de fluxo que representa uma origem com autorização para aceder ao recurso.
<CORS continueOnError="false" enabled="true" name="add-cors">
<AllowOrigins>{request.header.origin}</AllowOrigins>
</CORS>Exemplo:
Wildcard
Este exemplo especifica que todas as origens têm autorização para aceder ao recurso.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>*</AllowOrigins> </CORS>
<DisplayName>
Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente e mais natural.
O elemento <DisplayName> é comum a todas as políticas.
| Valor predefinido | N/A |
| Obrigatório? | Opcional. Se omitir <DisplayName>, é usado o valor do atributo name da política. |
| Tipo | String |
| Elemento principal | <PolicyElement> |
| Elementos subordinados | 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 nem elementos subordinados.
<ExposeHeaders>
Uma lista de cabeçalhos HTTP aos quais os navegadores têm autorização para aceder ou um asterisco (*)
para permitir todos os cabeçalhos HTTP.
Serializado no cabeçalho Access-Control-Expose-Headers.
| Valor predefinido | Se não for especificado, Access-Control-Expose-Headers não é definido. Os cabeçalhos não simples não são expostos por predefinição. |
| Obrigatório? | Opcional |
| Tipo | String, com suporte de modelo de mensagem* |
| Elemento principal |
<CORS>
|
| Elementos subordinados | 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 aceder a 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 deve gerar e devolver a resposta de verificação prévia de CORS.
Se false, não é enviada nenhuma resposta. Em vez disso, são preenchidas as seguintes variáveis de fluxo:
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 predefinido | true |
| Obrigatório? | Opcional |
| Tipo | Booleano |
| Elemento principal |
<CORS>
|
| Elementos subordinados | 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 deve gerar e devolver a resposta de verificação prévia de 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 é encontrada uma variável não resolvida.
Definido como true para ignorar as variáveis não resolvidas e continuar o processamento;
caso contrário, false.
| Valor predefinido | true |
| Obrigatório? | Opcional |
| Tipo | Booleano |
| Elemento principal |
<CORS>
|
| Elementos subordinados | 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 é encontrada uma variável não resolvida.
<CORS continueOnError="false" enabled="true" name="add-cors">
<AllowOrigins>{request.header.origin}</AllowOrigins>
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS><MaxAge>
Especifica durante quanto tempo os resultados de um pedido de pré-voo podem ser colocados em cache em segundos.
Um valor de -1 preenche o cabeçalho Access-Control-Max-Age com um valor de -1, que desativa o armazenamento em cache, o que requer uma verificação
OPTIONS prévia para todas as chamadas. Isto é definido na
Access-Control-Max-Age especificação.
| Valor predefinido | 1800 |
| Obrigatório? | Opcional |
| Tipo | Número inteiro |
| Elemento principal |
<CORS>
|
| Elementos subordinados | 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 um pedido de pré-voo podem ser colocados em cache durante 3628800 segundos.
<CORS continueOnError="false" enabled="true" name="add-cors">
<AllowOrigins>{request.header.origin}</AllowOrigins>
<MaxAge>3628800</MaxAge>
</CORS>Exemplo:
No cache
Este exemplo especifica que os resultados de um pedido de verificação prévia não podem ser colocados em cache.
<CORS continueOnError="false" enabled="true" name="add-cors">
<AllowOrigins>{request.header.origin}</AllowOrigins>
<MaxAge>-1</MaxAge>
</CORS>Notas de utilização
OPTIONS pedidos
Quando um pedido
OPTIONS é recebido e processado pela política de CORS, a execução do fluxo de proxy
é transferida diretamente para o PreFlow de resposta do proxy, ignorando completamente os fluxos de pedidos e
continua a execução a partir daí. Não é necessário criar uma condição para ignorar o pedido OPTIONS no fluxo de pedidos proxy.
Nas chamadas subsequentes, quando a política CORS é executada, se o MaxAge definido na política não tiver expirado, o fluxo continua normalmente. Durante o fluxo de resposta final, imediatamente antes de "Resposta enviada ao cliente", um passo de execução de CORS especial "CORSResponseOrErrorFlowExecution" define os cabeçalhos de resposta de CORS (Access-Control-Allow-Credentials, Access-Control-Allow-Origin e Access-Control-Expose-Headers) para devolver uma resposta validada por CORS.
Códigos de erro
Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se estiver a desenvolver regras de falhas para processar falhas. Para saber mais, consulte os artigos O que precisa de saber sobre erros de políticas e Processar falhas.
Erros de tempo de execução
Estes erros podem ocorrer quando a política é executada.
| Código de falha | Estado de HTTP | Causa |
|---|---|---|
steps.cors.UnresolvedVariable |
500 |
Este erro ocorre se uma variável especificada na política de CORS for:
ou |
Erros de implementação
Estes erros podem ocorrer quando implementa um proxy que contém esta política.
| Nome do erro | Causa |
|---|---|
InvalidMaxAge |
MaxAge não é um número |
MissingAllowOrigins |
AllowOrigins não está especificado |
InvalidHTTPMethods |
Um dos métodos em AllowMethods não é válido |
AllowHeadersSizeTooLarge |
O tamanho da string em AllowHeaders é demasiado grande. |
ExposeHeadersSizeTooLarge |
O tamanho da string em ExposeHeaders é demasiado grande. |
Variáveis de falha
Estas variáveis são definidas quando esta política aciona um erro no tempo de execução. Para mais informações, consulte O que precisa de saber sobre os erros de políticas.
| Variáveis | Onde | Exemplo |
|---|---|---|
fault.name = "FAULT_NAME" |
FAULT_NAME é o nome da falha, conforme indicado na tabela Erros de tempo 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 especificado pelo utilizador da política 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
É adicionado um objeto CorsFlowInfo FlowInfo, que fica disponível para rastreio.
| Propriedade | Tipo | Leitura/escrita | Descrição | O âmbito começa |
|---|---|---|---|---|
cross_origin_resource_sharing.allow.credentials |
Booleano | Leitura/escrita | Valor de <AllowCredentials> |
Pedido de proxy |
cross_origin_resource_sharing.allow.headers |
String | Leitura/escrita | Valor de <AllowHeaders> |
Pedido de proxy |
cross_origin_resource_sharing.allow.methods |
String | Leitura/escrita | Valor de <AllowMethods> |
Pedido de proxy |
cross_origin_resource_sharing.allow.origin |
String | Leitura/escrita | A origem do pedido permitida, vazia se não estiver na lista de autorizações | Pedido de proxy |
cross_origin_resource_sharing.allow.origins.list |
String | Leitura/escrita | Valor de <AllowOrigins> |
Pedido de proxy |
cross_origin_resource_sharing.expose.headers |
String | Leitura/escrita | Valor de <ExposeHeaders> |
Pedido de proxy |
cross_origin_resource_sharing.max.age |
Número inteiro | Leitura/escrita | Valor de <MaxAge> |
Pedido de proxy |
cross_origin_resource_sharing.preflight.accepted |
Booleano | Leitura/escrita | Indica se o pedido de verificação prévia é aceite | Pedido de proxy |
cross_origin_resource_sharing.request.headers |
String | Leitura/escrita | O valor do cabeçalho Access-Control-Request-Headers do pedido |
Pedido de proxy |
cross_origin_resource_sharing.request.method |
String | Leitura/escrita | O valor do cabeçalho Access-Control-Request-Method do pedido |
Pedido de proxy |
cross_origin_resource_sharing.request.origin |
String | Leitura/escrita | Igual a request.header.origin |
Pedido de proxy |
cross_origin_resource_sharing.request.type |
String | Leitura/escrita |
Tipo de pedido CORS. Valores possíveis:
|
Pedido de proxy |