Adicionando suporte CORS a Implantações de API

Saiba como usar uma política de solicitação para adicionar suporte CORS a implantações de API com o Gateway de API.

Em geral, os Web browsers implementam uma "política same-origin" para impedir que o código faça solicitações em uma origem distinta daquela da qual o código foi fornecido. A intenção da política 'same-origin' é fornecer proteção contra sites maliciosos. No entanto, a política 'same-origin' também pode evitar interações legítimas entre um servidor e clientes de uma origem conhecida e confiável.

O compartilhamento de recursos entre origens (CORS, Cross-Origin Resource Sharing) é um padrão de compartilhamento entre origens para relaxar a política 'same-origin', permitindo que o código em uma página Web consuma uma API REST fornecida por outra origem. O padrão CORS usa cabeçalhos de solicitação HTTP e cabeçalhos de resposta adicionais para especificar as origens que podem ser acessadas.

O padrão CORS também requer que, para determinados métodos de solicitação HTTP, a solicitação tenha que ser "comprovada". Antes de enviar a solicitação real, o web browser envia uma solicitação de comprovação ao servidor para determinar se há suporte para os métodos na solicitação real. O servidor responde com os métodos que ele permitirá em uma solicitação real. O Web browser só enviará a solicitação real se a resposta do servidor indicar que os métodos na solicitação real são permitidos. O padrão CORS também permite que os servidores notifiquem os clientes se as solicitações podem incluir credenciais (cookies, cabeçalhos de autorização ou certificados do cliente TLS).

Para obter mais informações sobre o CORS, consulte os recursos disponíveis on-line, incluindo os do W3C e do Mozilla.

Usando o serviço API Gateway, você pode ativar o suporte a CORS nas APIs que implantar nos gateways de API. Quando você ativa o suporte a CORS em uma implantação de API, as solicitações de comprovação e as solicitações reais para a implantação de API retornam um ou mais cabeçalhos de resposta de CORS para o cliente de API. Você define os valores do cabeçalho de resposta CORS na especificação de implantação de API.

Você usa políticas de solicitação para adicionar suporte de CORS a APIs (consulte Adicionando Políticas de Solicitação e Políticas de Resposta a Especificações de Implantação de API). Você pode aplicar uma política de solicitação de CORS globalmente a todas as rotas em uma especificação de implantação de API ou apenas a rotas específicas.

Você pode adicionar uma política de solicitação CORS a uma especificação de implantação de API fazendo o seguinte:

usando a Console
editando um arquivo JSON

Usando a Console para Adicionar Políticas de Solicitação CORS

Para adicionar uma política de solicitação CORS a uma especificação de implantação de API usando a Console:

Crie ou atualize uma implantação de API usando a Console. Selecione a opção Totalmente Nova e insira os detalhes na página Informações Básicas.

Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.
Na seção Políticas de Solicitação de API da página Informações Básicas, selecione o botão Adicionar ao lado de CORS e especifique:
- Origens Permitidas: Uma origem que tem permissão para acessar a implantação de API. Por exemplo, https://oracle.com. Selecione + Outra Origem para inserir a segunda origem e as origens subsequentes.
- Métodos Permitidos: Um ou mais métodos que são permitidos na solicitação real para a implantação de API. Por exemplo, GET, PUT.
- Cabeçalhos Permitidos: Opcionalmente, um cabeçalho HTTP que é permitido na solicitação real para a implantação de API. Por exemplo, opc-request-id ou If-Match. Selecione + Outro Cabeçalho para inserir o segundo cabeçalho e os cabeçalhos subsequentes.
- Cabeçalhos Expostos: Opcionalmente, um cabeçalho HTTP que os clientes podem acessar na resposta da implantação de API a uma solicitação real. Por exemplo, ETag ou opc-request-id. Selecione + Outro Cabeçalho para inserir o segundo cabeçalho e os cabeçalhos subsequentes.
- Idade máxima em segundos: Opcionalmente, um valor inteiro que indica por quanto tempo (em delta-segundos) os resultados de uma solicitação de comprovação podem ser armazenados em cache por um browser. Se você não especificar um valor, o padrão será 0.
- Ativar Permissão de Credenciais: Se a solicitação real para a implantação de API pode ser feita usando credenciais (cookies, cabeçalhos de autorização ou certificados do cliente TLS). Por padrão, essa opção não está selecionada.
Para saber como os diferentes campos da política de solicitação CORS é mapeado para diferentes cabeçalhos de resposta CORS, consulte Como uma Política de Solicitação CORS é Mapeada para uma Resposta CORS.
Selecione Aplicar Alterações.
Selecione Próximo para especificar opções de autenticação na página Autenticação.

Para obter mais informações sobre opções de autenticação, consulte Adicionando Autenticação e Autorização às Implantações de API.
Selecione Próximo para informar detalhes de rotas individuais na implantação de API na página Rotas. Para especificar políticas de solicitação CORS que se aplicam a uma rota individual, selecione Mostrar Políticas de Solicitação de Rota, selecione o botão Adicionar ao lado de CORS e especifique:
- Origens Permitidas: Uma origem que tem permissão para acessar a rota. Por exemplo, https://oracle.com. Selecione + Outra Origem para inserir a segunda origem e as origens subsequentes.
- Métodos Permitidos: Um ou mais métodos que são permitidos na solicitação real para a rota. Por exemplo, GET, PUT.
- Cabeçalhos Permitidos: Opcionalmente, um cabeçalho HTTP que é permitido na solicitação real para a rota. Por exemplo, opc-request-id ou If-Match. Selecione + Outro Cabeçalho para inserir o segundo cabeçalho e os cabeçalhos subsequentes.
- Cabeçalhos Expostos: Opcionalmente, um cabeçalho HTTP que os clientes podem acessar na resposta da implantação de API a uma solicitação real. Por exemplo, ETag ou opc-request-id. Selecione + Outro Cabeçalho para inserir o segundo cabeçalho e os cabeçalhos subsequentes.
- Idade máxima em segundos: Opcionalmente, um valor inteiro que indica por quanto tempo (em delta-segundos) os resultados de uma solicitação de comprovação podem ser armazenados em cache por um browser. Se você não especificar um valor, o padrão será 0.
- Ativar Permissão de Credenciais: Se a solicitação real para a rota pode ser feita usando credenciais (cookies, cabeçalhos de autorização ou certificados do cliente TLS). Por padrão, essa opção não está selecionada.
Para saber como os diferentes campos da política de solicitação CORS é mapeado para diferentes cabeçalhos de resposta CORS, consulte Como uma Política de Solicitação CORS é Mapeada para uma Resposta CORS.
Selecione Aplicar Alterações e, em seguida, selecione Próximo para revisar os detalhes informados para a implantação de API e para rotas individuais.
Selecione Criar ou Salvar Alterações para criar ou atualizar a implantação de API.
(Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Editando um Arquivo JSON para Adicionar Políticas de Solicitação CORS

Para adicionar uma política de solicitação CORS a uma especificação de implantação de API em um arquivo JSON:

Usando seu editor JSON preferido, edite a especificação de implantação de API existente à qual você deseja adicionar suporte de CORS ou crie uma nova especificação de implantação de API (consulte Criando uma Especificação de Implantação de API).

Por exemplo, a seguinte especificação básica de implantação de API define uma função simples sem servidor Hello World no OCI Functions como um único back-end:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
Para especificar uma política de solicitação de CORS que se aplique globalmente a todas as rotas em uma implantação de API:
1. Insira uma seção requestPolicies antes da seção routes, se ainda não existir uma. Por exemplo:
```
{
  "requestPolicies": {},
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
2. Adicione a seguinte política cors à nova seção requestPolicies para aplicar globalmente a todas as rotas em uma implantação de API:
```
{
  "requestPolicies": {
    "cors":{
      "allowedOrigins": [<list-of-origins>],
      "allowedMethods": [<list-of-methods>],
      "allowedHeaders": [<list-of-implicit-headers>],
      "exposedHeaders": [<list-of-exposed-headers>],
      "isAllowCredentialsEnabled": <true|false>,
      "maxAgeInSeconds": <seconds>
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
  em que:
  - "allowedOrigins": [<list-of-origins>] é uma lista separada por vírgulas de origens que podem acessar a implantação de API. Por exemplo, , "allowedOrigins": ["*", "https://oracle.com"]
  - "allowedMethods": [<list-of-methods>] é uma lista opcional separada por vírgulas de métodos HTTP que são permitidos na solicitação real para a implantação de API. Por exemplo, "allowedMethods": ["*", "GET"]
  - "allowedHeaders": [<list-of-implicit-headers>] é uma lista opcional separada por vírgulas de cabeçalhos HTTP permitidos na solicitação real para a implantação de API. Por exemplo, "allowedHeaders": ["opc-request-id", "If-Match"]
  - "exposedHeaders": [<list-of-exposed-headers>] é uma lista opcional separada por vírgulas de cabeçalhos HTTP que os clientes de API podem acessar na resposta de implantação de API a uma solicitação real. Por exemplo, "exposedHeaders": ["ETag", "opc-request-id"]
  - "isAllowCredentialsEnabled": <true|false> é true ou false, indicando se a solicitação real à implantação de API pode ser feita usando credenciais (cookies, cabeçalhos de autorização ou certificados de cliente TLS). Se não for especificado, o valor padrão será false.
  - "maxAgeInSeconds": <seconds> é um valor inteiro, que indica por quanto tempo (em delta-segundos) os resultados de uma solicitação de comprovação podem ser armazenados em cache por um browser. Se não for especificado, o valor padrão será 0.
  Por exemplo:
```
{
  "requestPolicies": {
    "cors":{
      "allowedOrigins": ["*", "https://oracle.com"],
      "allowedMethods": ["*", "GET"],
      "allowedHeaders": [],
      "exposedHeaders": [],
      "isAllowCredentialsEnabled": false,
      "maxAgeInSeconds": 3000
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
  Para saber como os diferentes campos da política de solicitação CORS é mapeado para diferentes cabeçalhos de resposta CORS, consulte Como uma Política de Solicitação CORS é Mapeada para uma Resposta CORS.
Para especificar uma política de solicitação de CORS que se aplique a uma rota individual:
1. Insira uma seção requestPolicies após a seção de back-end para a rota à qual você deseja que a política se aplique. Por exemplo:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}
```
2. Adicione a seguinte política cors à nova seção requestPolicies para aplicar somente a esta rota específica:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "cors":{
           "allowedOrigins": [<list-of-origins>],
           "allowedMethods": [<list-of-methods>],
           "allowedHeaders": [<list-of-implicit-headers>],
           "exposedHeaders": [<list-of-exposed-headers>],
           "isAllowCredentialsEnabled": <true|false>,
           "maxAgeInSeconds": <seconds>
        }
      }
    }
  ]
}
```
  em que:
  - "allowedOrigins": [<list-of-origins>] é uma lista separada por vírgulas de origens que podem acessar a implantação de API. Por exemplo, , "allowedOrigins": ["*", "https://oracle.com"]
  - "allowedMethods": [<list-of-methods>] é uma lista opcional separada por vírgulas de métodos HTTP que são permitidos na solicitação real para a implantação de API. Por exemplo, "allowedMethods": ["*", "GET"]
  - "allowedHeaders": [<list-of-implicit-headers>] é uma lista opcional separada por vírgulas de cabeçalhos HTTP permitidos na solicitação real para a implantação de API. Por exemplo, "allowedHeaders": ["opc-request-id", "If-Match"]
  - "exposedHeaders": [<list-of-exposed-headers>] é uma lista opcional separada por vírgulas de cabeçalhos HTTP que os clientes de API podem acessar na resposta de implantação de API a uma solicitação real. Por exemplo, "exposedHeaders": ["ETag", "opc-request-id"]
  - "isAllowCredentialsEnabled": <true|false> é true ou false, indicando se a solicitação real à implantação de API pode ser feita usando credenciais (cookies, cabeçalhos de autorização ou certificados de cliente TLS). Se não for especificado, o valor padrão será false.
  - "maxAgeInSeconds": <seconds> é um valor inteiro, que indica por quanto tempo (em delta-segundos) os resultados de uma solicitação de comprovação podem ser armazenados em cache por um browser. Se não for especificado, o valor padrão será 0.
  Por exemplo:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "cors":{
           "allowedOrigins": ["*", "https://oracle.com"],
           "allowedMethods": ["*", "GET"],
           "allowedHeaders": [],
           "exposedHeaders": [],
           "isAllowCredentialsEnabled": false,
           "maxAgeInSeconds": 3000
        }
      }
    }
  ]
}
```
  Para saber como os diferentes campos da política de solicitação CORS é mapeado para diferentes cabeçalhos de resposta CORS, consulte Como uma Política de Solicitação CORS é Mapeada para uma Resposta CORS.
Salve o arquivo JSON que contém a especificação de implantação de API.
Use a especificação de implantação de API ao criar ou atualizar uma implantação de API das seguintes formas:
- especificando o arquivo JSON na Console quando você selecionar a opção Carregar uma API existente
- especificando o arquivo JSON em uma solicitação à API REST do serviço API Gateway
Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.
(Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Como uma Política de Solicitação CORS É Mapeada para uma Resposta CORS

Os diferentes campos em um mapa de políticas de solicitação CORS para cabeçalhos de resposta CORS diferentes, conforme mostrado na tabela:


Campo	Mapeia para o cabeçalho de resposta CORS	Incluído na resposta à solicitação de comprovação	Incluído na resposta à solicitação real	Observações
`allowed Origins`	Access-Control-Allow-Origin	Sim	Sim	Obrigatório? Sim Tipo de dados: string[] Padrão: n/d Usado para retornar uma lista separada por vírgulas de origens que têm permissão para acessar a implantação da API. Somente uma origem é permitida pela especificação CORS; portanto, no caso de várias origens, a origem do cliente precisa ser verificada dinamicamente com relação à lista de valores permitidos. Os valores "*" e "null" são permitidos.
`allowed Methods`	Access-Control-Allow-Methods	Sim	Não	Obrigatório?: Não Tipo de dados: string[] Padrão: lista vazia Usado para retornar uma lista separada por vírgulas de métodos HTTP que são permitidos na solicitação real para a implantação de API. O padrão de Access-Control-Allow-Methods é permitir todos os métodos simples, mesmo nas solicitações de comprovação.
`allowed Headers`	Access-Control-Allow-Headers	Sim	Não	Obrigatório?: Não Tipo de dados: string[] Padrão: lista vazia Usado para retornar uma lista separada por vírgulas de cabeçalhos HTTP permitidos na solicitação real à implantação de API.
`exposed Headers`	Access-Control-Expose-Headers	Não	Sim	Obrigatório?: Não Tipo de dados: string[] Padrão: lista vazia Usado para retornar uma lista separada por vírgulas de cabeçalhos HTTP que os clientes podem acessar na resposta de implantação de API a uma solicitação real. Essa lista de cabeçalhos HTTP é um acréscimo aos cabeçalhos de resposta CORS-safelisted.
`isAllow Credentials Enabled`	Access-Control-Allow-Credentials	Sim	Sim	Obrigatório?: Não Tipo de dados: booliano Padrão: `false` Usado para retornar `true` ou `false`, indicando se a solicitação real para a implantação de API pode ser feita usando credenciais (cookies, cabeçalhos de autorização ou certificados de cliente TLS) Para permitir que as solicitações sejam feitas com credenciais, defina `isAllowCredentialsEnabled` como `true`.
`maxAge InSeconds`	Access-Control-Max-Age	Sim	Não	Obrigatório?: Não Tipo de dados: número inteiro Padrão: `0` Usado para indicar por quanto tempo (em delta-segundos) os resultados de uma solicitação de comprovação podem ser armazenados em cache por um browser. Ignorado se definido como `0`.

Documentação do Oracle Cloud Infrastructure

Adicionando suporte CORS a Implantações de API

Usando a Console para Adicionar Políticas de Solicitação CORS

Editando um Arquivo JSON para Adicionar Políticas de Solicitação CORS

Como uma Política de Solicitação CORS É Mapeada para uma Resposta CORS