Adicionando Políticas de Solicitação e Políticas de Resposta a Especificações de Implantação de API

Descubra como controlar o comportamento de implantações de API adicionando políticas de solicitação e resposta a especificações de API criadas anteriormente com o serviço API Gateway.

Você pode controlar o comportamento de uma implantação de API criada em um gateway de API adicionando políticas de solicitação e resposta à especificação de implantação de API:

uma política de solicitação descreve ações a serem executadas em uma solicitação de entrada de um cliente de API antes de ser enviada a um back-end
uma política de resposta descreve as ações a serem executadas em uma resposta retornada de um back-end antes de ela ser enviada a um cliente de API

Você pode usar políticas de solicitação e/ou políticas de resposta para:

limitar o número de solicitações enviadas a serviços de back-end
ativar o suporte ao compartilhamento de recursos entre origens (CORS, Cross-Origin Resource Sharing)
fornecer autenticação e autorização
adicionar suporte a mTLS
validar solicitações antes de enviá-las para serviços de back-end
modificar solicitações de entrada e respostas de saída
respostas de cache para melhorar o desempenho e reduzir a carga em serviços de back-end
tornar as implantações de API elegíveis para inclusão em planos de uso que monitoram e gerenciam o acesso do assinante

Você pode adicionar políticas a uma especificação de implantação de API que se aplique globalmente a todas as rotas na especificação de implantação de API, bem como políticas que se apliquem somente a rotas específicas.

Observe que as políticas de solicitação e resposta do serviço API Gateway são diferentes das políticas do serviço IAM, que controlam o acesso aos recursos do Oracle Cloud Infrastructure.

Você pode adicionar políticas de solicitação e resposta a uma especificação de implantação de API:

usando a Console
editando um arquivo JSON

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

Para adicionar políticas de solicitação e políticas de resposta 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 Criar implantação e informe detalhes na página Informações Básicas.

Para obter mais informações, consulte Implantando uma API em um Gateway da API Criando uma Implantação de API e Updating an API Gateway.
Na seçãoPolíticas de solicitação de API da página Informações básicas, especifique políticas que se aplicam globalmente a todas as rotas na especificação da implantação da API:
- Mutual-TLS: Uma política para controlar o acesso a APIs implantadas em gateways de API com base no certificado TLS apresentado pelo cliente de API que está fazendo uma solicitação. Você só pode aplicar um política de mTLS globalmente a todas as rotas na especificação da implantação de API (não a rotas individuais). Consulte Adicionando suporte a mTLS a Implantações de API.
- CORS: Uma política para ativar o suporte a CORS nas APIs que você implanta para gateways de API. Você também pode especificar políticas de CORS que se apliquem a rotas individuais na especificação de implantação de API (não é necessário ter informado primeiro uma política de CORS global). Consulte Adicionando suporte de CORS a Implantações de API.
- Limitação de Taxa: Uma política para limitar a taxa na qual os clientes de API podem fazer solicitações a serviços de back-end. Só é possível aplicar uma política de limitação de taxa globalmente a todas as rotas na especificação de implantação de API (e não a rotas individuais). Consulte Limitando o Número de Solicitações a Back-ends de Gateway de API.
- Planos de uso: Uma política para tornar uma implantação de API elegível para inclusão em um plano de uso especificando o local de um token de cliente informado em uma solicitação. Consulte Tornando uma Implantação de API Elegível para Inclusão em um Plano de Uso.
Selecione Próximo para especificar opções para definir uma política de solicitação de autenticação global na página Autenticação.

A política de solicitação de autenticação controla o acesso às APIs que você implanta nos gateways de API. Depois de especificar uma política de autenticação global primeiro, você poderá especificar políticas de autorização que se apliquem a rotas individuais na especificação de implantação de API. 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.
Selecione Adicionar rota e especifique as políticas de solicitação que se aplicam a uma rota individual selecionando Mostrar políticas de solicitação de rota e especifique:
- Autorização: Uma política para especificar as operações que um usuário final pode executar, com base nos escopos de acesso do usuário final. Observe que você já deverá ter especificado uma política de autenticação global para que possa especificar uma política de autorização em uma rota individual. Consulte Adicionando Autenticação e Autorização às Implantações de API.
- CORS: Uma política para ativar o suporte ao CORS para rotas individuais na especificação de implantação de API (você não precisa ter informado primeiro uma política de CORS global). Consulte Adicionando suporte de CORS a Implantações de API.
- Validações de cabeçalho: Uma política para validar cabeçalhos em solicitações. Consulte Usando a Console para Adicionar Políticas de Solicitação de Validação.
- Validações de parâmetro de consulta: Uma política para validar parâmetros de consulta em solicitações. Consulte Usando a Console para Adicionar Políticas de Solicitação de Validação.
- Validação do corpo: Uma política para validar o conteúdo no corpo das solicitações. Consulte Usando a Console para Adicionar Políticas de Solicitação de Validação
- Transformações de cabeçalho: Uma política para adicionar, remover e modificar cabeçalhos em solicitações. Consulte Adicionando Políticas da Solicitação de Transformação de Cabeçalho.
- Transformações de parâmetros da consulta: Uma política para adicionar, remover e modificar parâmetros da consulta em solicitações. Consulte Adicionando Políticas da Solicitação de Transformação do Parâmetro da Consulta.
Para especificar políticas da resposta que se aplicam a uma rota individual, selecione Mostrar políticas da resposta da rota e especifique:
- Transformações de cabeçalho: Uma política para adicionar, remover e modificar cabeçalhos em respostas. Consulte Adicionando Políticas da Resposta à Transformação de Cabeçalho.
Selecione Criar para criar a rota.
(Opcional) Selecione Adicionar rota para informar detalhes de rotas adicionais.
Selecione Próximo para revisar os detalhes informados para a implantação de API.
Selecione Criar ou Atualizar 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 e Políticas de Resposta

Para adicionar políticas de solicitação e políticas de resposta 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 uma política de solicitação ou política de resposta ou crie uma nova especificação de implantação de API (consulte Criando uma Especificação de Implantação de API).

No mínimo, a especificação de implantação de API incluirá uma seção routes contendo:
- Um caminho. Por exemplo, /hello
- Um ou mais métodos. Por exemplo, GET
- Uma definição de um back-end. Por exemplo, um URL ou o OCID de uma função no OCI Functions.
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 adicionar uma política de solicitação que se aplique globalmente a todas as rotas na especificação de implantação de API:
1. Insira uma seção requestPolicies antes da seção routes. Por exemplo:
```
{
  "requestPolicies": {},
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
2. Inclua uma política de solicitação na seção requestPolicies.
  
  Por exemplo, para limitar o número de solicitações enviadas a todas as rotas em uma especificação de implantação de API, inclua a política rateLimiting na seção requestPolicies da seguinte forma:
```
{
  "requestPolicies": {
    "rateLimiting": {
      "rateKey": "CLIENT_IP",
      "rateInRequestsPerSecond": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
  Para obter mais informações sobre a política de solicitação rateLimiting, consulte Limitando o Número de Solicitações a Back-ends de Gateway de API.

Para adicionar uma política de solicitação que se aplique a uma rota individual na especificação de implantação de API:

Insira uma seção requestPolicies após a seção backend da rota. Por exemplo:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}

Inclua uma política de solicitação na seção requestPolicies.

Por exemplo, para ativar o suporte a CORS em uma implantação de API para uma rota específica, inclua a política cors na seção requestPolicies da seguinte forma:

{
  "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 obter mais informações sobre a política de solicitação cors, consulte Adicionando suporte CORS a Implantações de API.

Para adicionar uma política de resposta que se aplique a uma rota individual na especificação de implantação de API:

Insira uma seção responsePolicies após a seção backend da rota. Por exemplo:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "responsePolicies": {}
    }
  ]
}

Inclua uma política de resposta na seção responsePolicies.

Por exemplo, para renomear qualquer cabeçalho X-Username como X-User-ID na resposta de uma rota específica, inclua a política headerTransformations na seção responsePolicies da seguinte forma:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "responsePolicies": {
        "headerTransformations": {
          "renameHeaders": {
            "items": [
              {
                "from": "X-Username",
                "to": "X-User-ID"
              }
            ]
          }
        }
      }
    }
  ]
}

Para obter mais informações sobre a política de resposta headerTransformations, consulte Adicionando Políticas de Resposta de Transformação de Cabeçalho.

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ê seleciona a opção Fazer Upload de uma API de implantação 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.

Documentação do Oracle Cloud Infrastructure

Adicionando Políticas de Solicitação e Políticas de Resposta a Especificações de Implantação de API

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

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