Usar plug-ins

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Edge Microgateway v. 3.3.x

Público-alvo

Este tópico é destinado a operadores do Edge Microgateway que querem usar plug-ins instalados com o microgateway. Ela também discute em detalhes a suspensão de pico e os plug-ins de cota (ambos estão incluídos na instalação). Se você for um desenvolvedor que quer desenvolver novos plug-ins, consulte Desenvolver plug-ins personalizados.

O que é um plug-in Edge Microgateway?

Um plug-in é um módulo do Node.js que adiciona funcionalidade ao Edge Microgateway. Os módulos de plug-in seguem um padrão consistente e são armazenados em um local conhecido pelo Edge Microgateway, permitindo que o microgateway os descubra e carregue automaticamente. O Edge Microgateway inclui vários plug-ins personalizados. Também é possível criar plug-ins personalizados, conforme explicado em Desenvolver plug-ins personalizados.

Plug-ins incluídos no Edge Microgateway

Vários plug-ins são fornecidos com o Edge Microgateway na instalação. A tabela a seguir descreve alguns dos plug-ins mais usados.

Plug-in Ativado por padrão Descrição
estatísticas Sim Envia dados de análise do Edge Microgateway para o Apigee Edge.
oauth Sim Adiciona o token OAuth e a validação da chave de API ao Edge Microgateway. Consulte Como instalar e configurar o Edge Microgateway.
cota Não Aplica a cota a solicitações para o Edge Microgateway. Usa o Apigee Edge para armazenar e gerenciar as cotas. Consulte Como usar o plug-in de cota.
detenção de pico Não Protege contra picos de tráfego e ataques DoS. Consulte Como usar o plug-in de restrição de pico.
cabeçalho em maiúsculas Não Um proxy de exemplo comentado que serve como um guia para ajudar os desenvolvedores a escrever plug-ins personalizados. Consulte Plug-in de amostra do Edge Microgateway.
acumular-solicitação Não Acumula dados de solicitação em um único objeto antes de passar os dados para o próximo gerenciador na cadeia de plug-ins. Útil para escrever plug-ins de transformação que precisam operar em um único objeto de conteúdo de solicitação acumulado.
acumular-resposta Não Acumula dados de resposta em um único objeto antes de passar os dados para o próximo gerenciador na cadeia de plug-ins. Útil para programar plug-ins de transformação que precisam operar em um único objeto de conteúdo de resposta acumulado.
transformar-maiúsculas Não Transforma dados de solicitação ou resposta. Este plug-in representa uma implementação de prática recomendada de um plug-in de transformação. O plug-in de exemplo executa uma transformação trivial (converte dados de solicitação ou resposta em maiúsculas). No entanto, ele pode ser facilmente adaptado para executar outros tipos de transformações, como XML para JSON.
json2xml. Não Transforma dados de solicitação ou resposta com base em cabeçalhos de aceitação ou do tipo de conteúdo. Para mais detalhes, consulte a documentação do plug-in no GitHub (em inglês).
cota-memória Não Aplica a cota a solicitações para o Edge Microgateway. Armazena e gerencia cotas na memória local.
healthcheck Não Retorna informações sobre o processo do Edge Microgateway, como uso de memória, de CPU etc. Para usar o plug-in, chame o URL /healthcheck na instância do Edge Microgateway. Este plug-in é um exemplo que pode ser usado para implementar seu próprio plug-in de verificação de integridade.

Onde encontrar plug-ins existentes

Os plug-ins já incluídos no Edge Microgateway estão localizados aqui, em que [prefix] é o diretório de prefixos npm. Consulte Onde o Edge Microgateway está instalado se não for possível localizar esse diretório.

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins

Como adicionar e configurar plug-ins

Siga este padrão para adicionar e configurar plug-ins:

  1. Parar o Edge Microgateway.
  2. Abra um arquivo de configuração do Edge Microgateway. Para mais detalhes, consulte Como fazer alterações na configuração para mais opções.
  3. Adicione o plug-in ao elemento plugins:sequence do arquivo de configuração da seguinte maneira: Os plug-ins são executados na ordem em que aparecem nesta lista.
edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
     level: info
     dir: /var/tmp
     stats_log_interval: 60
  plugins:
     dir: ../plugins
     sequence:   
     - oauth
     - plugin-name
  1. Configure o plug-in. Alguns plug-ins têm parâmetros opcionais que podem ser configurados no arquivo de configuração. Por exemplo, você pode adicionar a estrofe a seguir para configurar o plug-in de detenção de pico. Consulte Como usar o plug-in de parada de pico para mais informações.
    edgemicro:
      home: ../gateway
      port: 8000
      max_connections: -1
      max_connections_hard: -1
      logging:
        level: info
        dir: /var/tmp
        stats_log_interval: 60
      plugins:
        dir: ../plugins
        sequence:
          - oauth
          - spikearrest
    spikearrest:
       timeUnit: minute
       allow: 10
    
  1. Salve o arquivo.
  2. Reinicie ou recarregue o Edge Microgateway, dependendo do arquivo de configuração que você editou.

Configuração específica do plug-in

Você pode modificar os parâmetros do plug-in especificados no arquivo de configuração criando uma configuração específica do plug-in neste diretório:

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins/config

em que [prefix] é o diretório de prefixos npm. Consulte Onde o Edge Microgateway está instalado se não for possível localizar esse diretório.

plugins/<plugin_name>/config/default.yaml. Por exemplo, se você colocar esse bloco em plugins/spikearrest/config/default.yaml, ele vai substituir todas as outras definições de configuração.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Como usar o plug-in pico arrest

O plug-in de detenção de pico protege contra picos de tráfego. Isso limita o número de solicitações processadas por uma instância do Edge Microgateway.

Adicionar o plug-in de detenção de pico

Consulte Como adicionar e configurar plug-ins.

Exemplo de configuração para detenção de pico

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
   bufferSize: 5

Opções de configuração para detenção de pico

  • timeUnit: a frequência com que a janela de execução da prisão de pico é redefinida. Os valores válidos são segundos ou minutos.
  • allow: o número máximo de solicitações permitidas durante o timeUnit. Consulte também Se você estiver executando vários processos do Edge Micro.
  • bufferSize: (opcional, padrão = 0). Se bufferSize > 0, a retenção de pico armazenará esse número de solicitações em um buffer. Assim que a próxima "janela" de execução ocorrer, as solicitações armazenadas em buffer serão processadas primeiro. Consulte também Como adicionar um buffer.

Como funciona a detenção de pico?

Pense na detenção de pico como uma maneira de se proteger geralmente contra picos de tráfego, não como uma maneira de limitar o tráfego a um número específico de solicitações. Suas APIs e seu back-end podem lidar com uma determinada quantidade de tráfego, e a política de detenção de pico ajuda a reduzir o tráfego para os valores gerais desejados.

O comportamento de detenção de pico no tempo de execução é diferente do que você pode esperar dos valores literais por minuto ou por segundo inseridos.

Por exemplo, digamos que você especifique uma taxa de 30 solicitações por minuto, assim:

spikearrest:
   timeUnit: minute
   allow: 30

Nos testes, você pode pensar que poderia enviar 30 solicitações em um segundo, contanto que elas cheguem em até um minuto. Mas não é assim que a política aplica a configuração. 30 solicitações em um período de um segundo podem ser consideradas um pequeno pico em alguns ambientes.

O que realmente acontece? Para evitar um comportamento semelhante ao de pico, a detenção de pico suaviza o tráfego permitido dividindo as configurações em intervalos menores, da seguinte maneira:

Taxas por minuto

As taxas por minuto são suavizadas em intervalos permitidos de segundos de solicitações. Por exemplo, 30 solicitações por minuto são suavizadas assim:

60 segundos (1 minuto) / 30 = intervalos de 2 segundos, ou cerca de 1 solicitação permitida a cada 2 segundos. Uma segunda solicitação dentro de dois segundos vai falhar. Além disso, a 31a solicitação em um minuto falhará.

Taxas por segundo

As taxas por segundo são suavizadas nas solicitações permitidas em intervalos de milissegundos. Por exemplo, 10 solicitações/segundo são suavizadas assim:

1.000 milissegundos (1 segundo) / 10 = intervalos de 100 milissegundos, ou seja, cerca de uma solicitação permitida a cada 100 milissegundos. Uma segunda solicitação em 100 ms falhará. Além disso, uma 11a solicitação dentro de um segundo falhará.

Quando o limite é excedido

Se o número de solicitações exceder o limite dentro do intervalo de tempo especificado, a detenção de pico retornará esta mensagem de erro com um status HTTP 503:

{"error": "spike arrest policy violated"}

Como adicionar um buffer

Você tem a opção de adicionar um buffer à política. Digamos que você definiu o buffer como 10. Você verá que a API não retorna um erro imediatamente quando você excede o limite de detenção de pico. Em vez disso, as solicitações são armazenadas em buffer (até o número especificado) e as solicitações em buffer são processadas assim que a próxima janela de execução adequada fica disponível. O bufferSize padrão é 0.

Se você estiver executando vários processos do Edge Micro

O número de solicitações permitidas depende da quantidade de processos de worker do Edge Micro em execução. A detenção de pico calcula o número permitido de solicitações por processo de worker. Por padrão, o número de processos do Edge Micro é igual ao número de CPUs na máquina em que o Edge Micro está instalado. No entanto, é possível configurar o número de processos de worker ao iniciar o Edge Micro usando a opção --processes no comando start. Por exemplo, se você quiser que a detenção de pico seja acionada em 100 solicitações em um determinado período e iniciar o Edge Microgateway com a opção --processes 4, defina allow: 25 na configuração de detenção de pico. Em resumo, a regra prática é definir o parâmetro de configuração allow como o valor "contagem de picos de prescrição / número de processos desejado".

Como usar o plug-in de cota

Uma cota especifica o número de mensagens de solicitação que um app pode enviar para uma API ao longo de uma hora, dia, semana ou mês. Quando um app atinge o limite da cota, as chamadas de API subsequentes são rejeitadas. Consulte também Qual é a diferença entre detenção de pico e cota?.

Como adicionar o plug-in de cota

Consulte Como adicionar e configurar plug-ins.

Configuração de produtos na Apigee Edge

Você configura cotas na IU do Apigee Edge, em que configura os produtos de API. É necessário saber qual produto contém o proxy com reconhecimento de microgateway que você quer limitar com uma cota. Esse produto precisa ser adicionado a um app de desenvolvedor. Quando você faz chamadas de API autenticadas usando chaves no app do desenvolvedor, a cota é aplicada a essas chamadas de API.

  1. Faça login na sua conta da organização do Apigee Edge.
  2. Na IU do Edge, abra o produto associado ao proxy com reconhecimento de microgateway em que você quer aplicar a cota.
    1. Na IU, selecione Produtos no menu Publicar.
    2. Abra o produto que contém a API a que você quer aplicar a cota.
    3. Clique em Editar.
    4. No campo "Cota", especifique o intervalo da cota. Por exemplo, 100 solicitações a cada minuto. Ou 50.000 solicitações a cada 2 horas.

  1. Clique em Salvar.
  2. Confira se o produto foi adicionado a um app de desenvolvedor. Você vai precisar das chaves desse app para fazer chamadas de API autenticadas.

Exemplo de configuração de cota

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota

Opções de configuração da cota

Para configurar o plug-in de cota, adicione o elemento quotas ao arquivo de configuração, conforme mostrado no exemplo a seguir:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota
quotas:
    bufferSize:
      hour: 20000
      minute: 500
      month: 1
      default: 10000
    useDebugMpId: true
    failOpen: true
    isHTTPStatusTooManyRequestEnabled: true
...
Opção Descrição
bufferSize

(Inteiro) A configuração bufferSize permite ajustar a frequência com que o Edge Microgateway sincroniza a contagem de cotas com o Apigee Edge. Para entender bufferSize, considere o seguinte exemplo de configuração:

quotas:
 bufferSize:
  minute: 500
  default: 10000
 useDebugMpId: true
 failOpen: true

Por padrão, o microgateway sincroniza o contador de cotas com o Apigee Edge a cada cinco segundos se o intervalo de cota estiver definido como "minuto". A configuração acima diz que, se o intervalo de cota for definido no produto da API como "minuto", o Edge Microgateway vai fazer a sincronização com o Edge para receber a contagem atual a cada 500 solicitações ou após cinco segundos, o que ocorrer primeiro. Para mais informações, consulte Noções básicas sobre como as cotas são contadas.

As unidades de tempo permitidos incluem: minute, hour, day, week, month e default.

isHTTPStatusTooManyRequestEnabled

Configura o plug-in de cota para retornar um status de resposta HTTP 429 em vez do status 403 se houver uma violação de cota.

Padrão: false. Por padrão, ou se a sinalização for definida como false, a cota retornará o status HTTP 403 quando a cota for excedida.

Se a sinalização estiver definida como true, a cota retornará o status HTTP 429 quando a cota for excedida.

Para alterar o status de retorno HTTP padrão para 429, use a seguinte configuração:

edgemicro:
...
quotas:
  isHTTPStatusTooManyRequestEnabled: true
failOpen Quando esse recurso estiver ativado, se ocorrer um erro de processamento de cota ou se a solicitação "quota apply" ao Edge não atualizar os contadores remotos, a cota será processada com base em contagens locais somente até que a próxima sincronização remota bem-sucedida ocorra. Em ambos os casos, uma sinalização quota-failed-open é definida no objeto da solicitação.

Para ativar o recurso de "falha ao abrir" cota, defina a seguinte configuração:

edgemicro:
...
quotas:
  failOpen: true
useDebugMpId Defina esta sinalização como true para ativar a geração de registros do ID do MP (processador de mensagens) nas respostas de cota.

Para usar esse recurso, é preciso definir a seguinte configuração:

edgemicro:
...
quotas:
  useDebugMpId: true
...

Quando useDebugMpId estiver definido, as respostas de cota do Edge vão conter o ID de MP e serão registradas pelo Edge Microgateway. Exemplo:

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}
useRedis Se definido como true, o plug-in usará o Redis para o armazenamento de apoio de cota. Para detalhes, consulte Como usar um armazenamento de apoio do Redis para cota.

Como as cotas são contadas

Por padrão, o microgateway sincroniza o contador de cotas com o Apigee Edge a cada cinco segundos se o intervalo de cota estiver definido como "minuto". Se o intervalo for definido para um nível maior que "minuto", como "semana" ou "mês", o período de atualização padrão será de 1 minuto.

É importante observar que você especifica intervalos de cota nos produtos de API definidos no Apigee Edge. Os intervalos de cota especificam quantas solicitações são permitidas para um minuto, hora, dia, semana ou mês. Por exemplo, o Produto A pode ter um intervalo de cota de 100 solicitações por minuto,e o Produto B pode ter um intervalo de cota de 10.000 solicitações por hora.

A configuração YAML do plug-in quota do Edge Microgateway não define o intervalo de cota. Em vez disso, ela fornece uma maneira de ajustar a frequência com que uma instância local do Edge Microgateway sincroniza a contagem de cotas com o Apigee Edge.

Por exemplo, suponha que há três produtos de API definidos no Apigee Edge com os seguintes intervalos de cota especificados:

  • O produto A tem uma cota de 100 solicitações por minuto.
  • O Produto B tem uma cota de 5.000 solicitações por hora
  • O produto C tem uma cota de 1.000.000 solicitações por mês

Com essas configurações de cota em mente, como o plug-in quota do Edge Microgateway precisa ser configurado? A prática recomendada é configurar o Edge Microgateway com intervalos de sincronização menores que os intervalos de cota definidos nos produtos da API. Exemplo:

quotas:
    bufferSize:
      hour: 2000
      minute: 50
      month: 1
      default: 10000

Essa configuração define os seguintes intervalos de sincronização para os produtos de API descritos anteriormente:

  • O produto A está definido para o intervalo de "minutos". O Edge Microgateway será sincronizado com o Edge a cada 50 solicitações ou 5 segundos, o que ocorrer primeiro.
  • O produto B está definido para o intervalo "hora". O Edge Microgateway será sincronizado com o Edge a cada 2.000 solicitações ou um minuto, o que ocorrer primeiro.
  • O produto C é definido para o intervalo "mês". O Edge Microgateway será sincronizado com o Edge após cada solicitação ou um minuto, o que ocorrer primeiro.

Sempre que uma instância de microgateway é sincronizada com o Edge, a contagem da cota do microgateway é definida como a contagem da cota recuperada.

As configurações de bufferSize permitem ajustar como o contador de cotas é sincronizado com o Edge. Em situações de tráfego intenso, as configurações de bufferSize permitem que o contador de buffer faça a sincronização antes que a sincronização padrão baseada em tempo seja acionada.

Noções básicas sobre o escopo da cota

A contagem de cota é definida como escopo para um ambiente em uma organização. Para alcançar esse escopo, o Edge Microgateway cria um identificador de cota que é uma combinação de "org + env + appName + productName".

Como usar um armazenamento de apoio do Redis para cota

Para usar um armazenamento de apoio do Redis para cota, use a mesma configuração usada para o recurso "Sincronizador". Veja a seguir a configuração básica necessária para usar o Redis no armazenamento de cotas:

edgemicro:
  redisHost: localhost
  redisPort: 6379
  redisDb: 2
  redisPassword: codemaster

quotas:
  useRedis: true
Veja mais detalhes sobre os parâmetros edgemicro.redis* em Como usar o sincronizador.

Como testar o plug-in de cota

Quando a cota é excedida, um status HTTP 403 é retornado ao cliente, junto com a seguinte mensagem:

{"error": "exceeded quota"}

Qual é a diferença entre detenção de pico e cota?

É importante escolher a ferramenta certa para o trabalho em questão. As políticas de cotas configuram o número de mensagens de solicitação que um app cliente pode enviar a uma API ao longo de uma hora, dia, semana ou mês. A política de cotas aplica limites de consumo em apps clientes mantendo um contador distribuído que conta as solicitações recebidas.

Use uma política de cotas para aplicar contratos de negócios ou SLAs com desenvolvedores e parceiros, em vez de gerenciar o tráfego operacional. Por exemplo, uma cota pode ser usada para limitar o tráfego de um serviço sem custo financeiro e, ao mesmo tempo, permitir acesso total para clientes pagantes.

Use a detenção de pico para se proteger contra picos repentinos no tráfego da API. Normalmente, a detenção de pico é usada para impedir possíveis ataques DDoS ou outros ataques maliciosos.