Usar plug-ins

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

Edge Microgateway v. 3.3.x

Público-alvo

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

O que é um plug-in do Edge Microgateway?

Um plug-in é um módulo Node.js que adiciona funcionalidade ao Edge Microgateway. Módulos de plug-in seguem um padrão consistente e são armazenados em um local conhecido pelo Edge Microgateway, microgateway para descobrir e carregá-los automaticamente. O Edge Microgateway inclui várias plug-ins. Você também pode criar plug-ins personalizados, conforme explicado em Desenvolver plug-ins personalizados.

Plug-ins já incluídos no Edge Microgateway

Vários plug-ins são fornecidos com o Edge Microgateway na instalação. O seguinte descreve alguns dos plug-ins mais usados.

Onde encontrar plug-ins

Os plug-ins que já vêm com o Edge Microgateway estão localizados aqui, em que [prefix] é o diretório de prefixo 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 obter detalhes, consulte Fazer alterações na configuração para 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

4. Configure o plug-in. Alguns plug-ins têm parâmetros opcionais que você pode configurar no arquivo de configuração. Por exemplo, você pode adicionar a seguinte estrofe para configurar a prisão de pico plug-in. Consulte Como usar o plug-in de detenção 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
   

5. Salve o arquivo.
6. Reinicie ou recarregue o Edge Microgateway, dependendo do arquivo de configuração editado.

Configuração específica do plug-in

É possível modificar os parâmetros do plug-in especificados no arquivo de configuração criando um específica do plug-in neste diretório:

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

em que [prefix] é o diretório do prefixo 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, é possível colocar em plugins/spikearrest/config/default.yaml, e elas vão substituir qualquer outro configurações.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Como usar o plug-in de detenção de pico

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

Como adicionar o plug-in de detenção de pico

Consulte Como adicionar e configurar plug-ins.

Exemplo de configuração para prisã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 prisão de pico

• timeUnit: com que frequência a janela de execução da prisão de pico é redefinida. Valores válidos são segundos ou minutos.
• allow: o número máximo de solicitações a serem permitidas durante a unidade de tempo. Consulte Além disso, se você executar múltiplas e processos.
• bufferSize: (opcional, padrão = 0) if bufferSize > 0, detenção de pico armazena esse número de solicitações em um buffer. Assim que a próxima "janela" de execução ocorrer, a as solicitações 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 forma de se proteger contra picos de tráfego, e não como um de limitar o tráfego a um número específico de solicitações. As APIs e o back-end podem lidar com uma determinada de tráfego intenso, e a política de detenção de pico ajuda a direcionar o tráfego para os volumes gerais que você quiser.

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

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

spikearrest:
   timeUnit: minute
   allow: 30

Em testes, você pode pensar que poderia enviar 30 solicitações em 1 segundo, desde que elas venham dentro de um minuto. Mas não é assim que a política aplica a configuração. Se pararmos para pensar, 30 as solicitações dentro de um período de um segundo podem ser consideradas um pequeno pico em alguns ambientes.

O que realmente acontece? Para evitar comportamentos semelhantes aos de pico, a detenção de picos suaviza o tráfego dividindo as configurações em intervalos menores, da seguinte forma:

Tarifas por minuto

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

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

Taxas por segundo

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

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

Quando o limite é excedido

Se o número de solicitações exceder o limite dentro do intervalo de tempo especificado, a prisão de pico retorna 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ê vai perceber que a API não retorna um erro imediatamente quando você excede o limite de detenção de pico ou ao atingir um limite estabelecido. Em vez disso, as solicitações são armazenadas em buffer (até o número especificado) processados assim que a próxima janela de execução apropriada estiver disponível. O padrão bufferSize é 0.

Se você estiver executando várias versões do Edge Micro processos

O número de solicitações permitidas depende do número de processos de worker do Edge Micro que estão em execução. A parada 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, você pode 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ê quer que a detenção de pico seja acionada a 100 solicitações em um determinado período, e se você iniciar o Edge Microgateway com a opção --processes 4, depois defina allow: 25 no configuração de detenção de pico. Em resumo, a regra prática é definir a configuração allow para o valor "número desejado de detenção de pico / número de processos".

Como usar o plug-in de cotas

Uma cota especifica o número de mensagens de solicitação que um aplicativo tem permissão para enviar a uma API ao longo de uma hora, dia, semana ou mês. Quando um aplicativo atinge seu limite de cota, as Chamadas de API são rejeitadas. Veja também Qual é a diferença entre detenção de pico e cota?

Como adicionar o plug-in de cotas

Consulte Como adicionar e configurar plug-ins.

Configuração de produto na Apigee Borda

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

1. Faça login na sua conta da organização do Apigee Edge.
2. Na interface do Edge, abra o produto associado ao proxy com reconhecimento de microgateway para o qual em que você quer aplicar a cota.
   1. Na interface, 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 um minuto. Ou 50.000 solicitações a cada 2 horas.
      
      

3. Clique em Salvar.
4. Verifique se o produto foi adicionado a um app de desenvolvedor. Você vai precisar das chaves deste app para fazer chamadas de API autenticadas.

Exemplo de configuração para 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 para cotas

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

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

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

edgemicro:
...
quotas:
  isHTTPStatusTooManyRequestEnabled: true

edgemicro:
...
quotas:
  failOpen: true

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

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}

Noções básicas sobre como as cotas são contabilizadas

Por padrão, o microgateway sincroniza o contador de cotas com o Apigee Edge a cada cinco segundos se o intervalo de cota é 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 é 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 por um minuto, uma hora, um dia, uma semana ou um 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.

O YAML do plug-in quota do Edge Microgateway configuração não define a cota interval; é uma maneira de ajustar a frequência com que um Edge Microgateway local sincroniza a cota 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 deve ser configurados? A prática recomendada é configurar o Edge Microgateway com intervalos de sincronização que são inferiores aos intervalos de cota definidos nos produtos de 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 é definido como "minuto" intervalo. O Edge Microgateway será sincronizado com o Edge após a cada 50 solicitações ou 5 segundos, o que ocorrer primeiro.
• O produto B está definido como "hora" intervalo. O Edge Microgateway será sincronizado com o Edge após a cada 2.000 solicitações ou 1 minuto, o que ocorrer primeiro.
• O produto C está definido como "mês" intervalo. O Edge Microgateway será sincronizado com o Edge após a cada solicitação ou por um minuto, o que ocorrer primeiro.

Sempre que uma instância de microgateway sincroniza com o Edge, o a contagem de cotas estiver definida como aquela recuperada.

As configurações bufferSize permitem ajustar como o contador de cotas é sincronizada com o Edge. Em situações de tráfego intenso, as configurações de bufferSize permitir que o contador de buffer sincronize antes do acionamento da sincronização padrão baseada em tempo.

Noções básicas sobre escopo de cota

A contagem de cotas tem o escopo definido para um ambiente em uma organização. Para atingir 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 cotas

Para usar um armazenamento de apoio 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 para armazenamento de cota:

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

quotas:
  useRedis: true

Como testar o plug-in de cotas

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

{"error": "exceeded quota"}

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

É importante escolher a ferramenta certa para o trabalho em questão. Configurar as políticas de cotas o número de mensagens de solicitação que um app cliente pode enviar a uma API ao longo do curso de uma hora, um dia, uma semana ou um mês. A política de cotas aplica limites de consumo em apps clientes, e a manutenção de 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 e o gerenciamento de tráfego operacional. Por exemplo, uma cota pode ser usada para limitar o tráfego para um serviço sem custo financeiro, além de permitir o acesso total para clientes pagantes.

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