Usar plug-ins

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

Edge Microgateway v. 2.5.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. Esses incluem:

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 a validação do token OAuth e da chave de API ao Edge Microgateway. Consulte Configuração configurar o Edge Microgateway.
cota Não Aplica a cota às solicitações para o Edge Microgateway. Usa o Apigee Edge para armazenar e gerenciar as cotas. Consulte Como usar o plug-in de cotas.
spikearrest (em inglês) Não Protege contra picos de tráfego e ataques DoS. Consulte Como usar o plug-in de detenção de pico.
cabeçalho maiúsculo Não Um proxy de amostra comentado que serve como um guia para ajudar os desenvolvedores a criar plug-ins personalizados. Consulte Plug-in de amostra do Edge Microgateway.
accumulate-request Não Acumula dados da solicitação em um único objeto antes de transmitir os dados para o próximo na cadeia do plug-in. Útil para escrever plug-ins de transformação que precisam operar em um objeto de conteúdo de solicitação acumulado.
accumulate-response Não Acumula dados de resposta em um único objeto antes de transmitir os dados para o próximo na cadeia do plug-in. Útil para escrever plug-ins de transformação que precisam operar em um objeto de conteúdo de resposta único e acumulado.
transformar maiúsculas Não Transforma dados de solicitação ou resposta. Este plug-in representa uma prática recomendada implementação 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 e 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 tipo de conteúdo. Para detalhes, consulte o plug-in documentação no GitHub.
quota-memory (em inglês) Não Aplica a cota às solicitações para o Edge Microgateway. Armazena e gerencia cotas no local memória.
verificação de integridade Não Retorna informações sobre o processo do Edge Microgateway: uso de memória, uso de CPU etc. Para usar o plug-in, chame o URL /healthcheck no Edge Instância do Microgateway. Este plug-in pretende ser um exemplo que você pode usar para implemente seu próprio plug-in de verificação de integridade.

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
  1. 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
    
  1. Salve o arquivo.
  2. 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.

  1. Clique em Salvar.
  2. 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

Não há outras opções de configuração para o plug-in de cotas.

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.