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

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:

  1. 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.

  2. Na seção Políticas de Solicitação de API da página Informações Básicas, especifique políticas de solicitação que se apliquem globalmente a todas as rotas na especificação de implantação de API:

    • TLS Mútuo: Uma política para controlar o acesso a APIs que você implanta em gateways de API com base no certificado TLS apresentado pelo cliente de API que faz uma solicitação. Só pode aplicar uma política mTLS globalmente a todas as rotas na especificação de implantação de API (e não a rotas individuais). Consulte Adicionando suporte 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.

  3. 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.

  4. Selecione Próximo para informar detalhes de rotas individuais na implantação de API na página Rotas.

  5. Para especificar políticas de solicitação que sejam aplicáveis a uma rota individual, selecione Mostrar Políticas de Solicitação de Rota e especifique:

  6. Para especificar políticas de resposta que se aplicam a uma rota individual, selecione Mostrar Políticas de Resposta de Rota e especifique:

  7. Selecione Próximo para revisar os detalhes informados para a implantação de API.
  8. Selecione Criar ou Salvar Alterações para criar ou atualizar a implantação de API.
  9. (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:

  1. 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"
      }
    }
  ]
}

  2. 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.

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

    1. 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": {}
    }
  ]
}

    2. 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.

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

    1. 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": {}
    }
  ]
}

    2. 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 Editando um Arquivo JSON para Adicionar Políticas de Resposta de Transformação de Cabeçalho.

  5. Salve o arquivo JSON que contém a especificação de implantação de API.

  6. 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.