Utilizzare i plug-in

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Edge Microgateway v. 3.3.x

Pubblico

Questo argomento è rivolto agli operatori di Edge Microgateway che vogliono utilizzare i plug-in esistenti installati con il microgateway. Vengono inoltre descritti in dettaglio i plug-in per l'arresto dei picchi e delle quote (entrambi inclusi nell'installazione). Se sei uno sviluppatore che vuole sviluppare nuovi plugin, consulta Sviluppare plugin personalizzati.

Che cos'è un plug-in Edge Microgateway?

Un plug-in è un modulo Node.js che aggiunge funzionalità a Edge Microgateway. I moduli plug-in seguono un pattern coerente e vengono archiviati in una posizione nota a Edge Microgateway, consentendo al microgateway di rilevarli e caricarli automaticamente. Edge Microgateway include diversi plug-in esistenti e puoi anche creare plug-in personalizzati, come spiegato in Sviluppare plug-in personalizzati.

Plug-in esistenti inclusi in Edge Microgateway

Durante l'installazione vengono forniti diversi plug-in con Edge Microgateway. La seguente tabella descrive alcuni dei plug-in di uso comune.

Dove trovare i plug-in esistenti

I plug-in esistenti inclusi in Edge Microgateway si trovano qui, dove [prefix] è la directory del prefisso npm. Consulta Dove è installato Edge Microgateway se non riesci a trovare questa directory.

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

Aggiunta e configurazione dei plug-in

Segui questo pattern per aggiungere e configurare i plug-in:

1. Arresta Edge Microgateway.
2. Apri un file di configurazione di Edge Microgateway. Per maggiori dettagli, vedi Apportare modifiche alla configurazione per le opzioni.
3. Aggiungi il plug-in all'elemento plugins:sequence del file di configurazione, come segue. I plug-in vengono eseguiti nell'ordine in cui sono visualizzati in questo elenco.

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. Configura il plug-in. Alcuni plug-in hanno parametri facoltativi che puoi configurare nel file di configurazione. Ad esempio, puoi aggiungere la seguente sezione per configurare il plug-in di protezione dai picchi. Per ulteriori informazioni, consulta la pagina Utilizzo del plug-in Spike Arrest.

   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. Salva il file.
6. Riavvia o ricarica Edge Microgateway, a seconda del file di configurazione che hai modificato.

Configurazione specifica del plug-in

Puoi eseguire l'override dei parametri del plug-in specificati nel file di configurazione creando una configurazione specifica del plug-in in questa directory:

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

dove [prefix] è la directory del prefisso npm. Consulta Dove è installato Edge Microgateway se non riesci a trovare questa directory.

plugins/<plugin_name>/config/default.yaml. Ad esempio, puoi inserire questo blocco in plugins/spikearrest/config/default.yaml e le impostazioni di configurazione verranno sostituite.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Utilizzo del plug-in Spike Arrest

Il plug-in Spike Arrest protegge dai picchi di traffico. Limita il numero di richieste elaborate da un'istanza Edge Microgateway.

Aggiunta del plug-in SpikeArrest

Vedi Aggiungere e configurare i plug-in.

Configurazione di esempio per l'arresto dei picchi

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

Opzioni di configurazione per spike arrest

• timeUnit: la frequenza con cui viene reimpostata la finestra di esecuzione dell'arresto dei picchi. I valori validi sono secondo o minuto.
• allow: il numero massimo di richieste da consentire durante timeUnit. Vedi anche Se esegui più processi Edge Micro.
• bufferSize: (facoltativo, valore predefinito = 0) se bufferSize > 0, spike arrest memorizza questo numero di richieste in un buffer. Non appena si verifica la successiva "finestra" di esecuzione, le richieste memorizzate nel buffer vengono elaborate per prime. Vedi anche Aggiungere un buffer.

Come funziona il blocco dei picchi?

Pensa all'arresto dei picchi come a un modo per proteggerti in generale dai picchi di traffico, piuttosto che come a un modo per limitare il traffico a un numero specifico di richieste. Le tue API e il tuo backend possono gestire una determinata quantità di traffico e il criterio di controllo dei picchi ti aiuta a uniformare il traffico in base agli importi generali che preferisci.

Il comportamento di arresto dei picchi di runtime è diverso da quello che potresti aspettarti di vedere dai valori letterali al minuto o al secondo che inserisci.

Ad esempio, supponiamo che tu specifichi una frequenza di 30 richieste al minuto, in questo modo:

spikearrest:
   timeUnit: minute
   allow: 30

Durante il test, potresti pensare di poter inviare 30 richieste in 1 secondo, purché vengano inviate entro un minuto. Tuttavia, non è così che la norma applica l'impostazione. Se ci pensi, 30 richieste in un periodo di 1 secondo potrebbero essere considerate un mini picco in alcuni ambienti.

Che cosa succede effettivamente? Per evitare comportamenti simili a picchi, l'arresto dei picchi attenua il traffico consentito dividendo le impostazioni in intervalli più piccoli, come segue:

Tariffe al minuto

Le tariffe al minuto vengono uniformate in intervalli di secondi consentiti per le richieste. Ad esempio, 30 richieste al minuto vengono uniformate in questo modo:

60 secondi (1 minuto) / 30 = intervalli di 2 secondi o circa 1 richiesta consentita ogni 2 secondi. Una seconda richiesta entro 2 secondi non andrà a buon fine. Inoltre, una 31ª richiesta entro un minuto non andrà a buon fine.

Tariffe al secondo

Le tariffe al secondo vengono uniformate in richieste consentite a intervalli di millisecondi. Ad esempio, 10 richieste/secondo vengono uniformate nel seguente modo:

1000 millisecondi (1 secondo) / 10 = intervalli di 100 millisecondi o circa 1 richiesta consentita ogni 100 millisecondi . Una seconda richiesta entro 100 ms non andrà a buon fine. Inoltre, l'undicesima richiesta entro un secondo non andrà a buon fine.

Quando il limite viene superato

Se il numero di richieste supera il limite entro l'intervallo di tempo specificato, spike arrest restituisce questo messaggio di errore con uno stato HTTP 503:

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

Aggiungere un margine

Puoi aggiungere un buffer alle norme. Supponiamo che tu imposti il buffer su 10. Vedrai che l'API non restituisce immediatamente un errore quando superi il limite di spike arrest. Le richieste vengono invece memorizzate nel buffer (fino al numero specificato) e vengono elaborate non appena è disponibile la successiva finestra di esecuzione appropriata. Il valore predefinito di bufferSize è 0.

Se esegui più processi Edge Micro

Il numero di richieste consentite dipende dal numero di processi worker Edge Micro in esecuzione. Spike Arrest calcola il numero consentito di richieste per processo worker. Per impostazione predefinita, il numero di processi Edge Micro è uguale al numero di CPU sulla macchina in cui è installato Edge Micro. Tuttavia, puoi configurare il numero di processi worker quando avvii Edge Micro utilizzando l'opzione --processes nel comando start. Ad esempio, se vuoi che il controllo dei picchi venga attivato a 100 richieste in un determinato periodo di tempo e se avvii Edge Microgateway con l'opzione --processes 4, imposta allow: 25 nella configurazione del controllo dei picchi. In sintesi, la regola generale è impostare il parametro di configurazione allow sul valore "numero di picchi desiderato / numero di processi".

Utilizzare il plug-in per la quota

Una quota specifica il numero di messaggi di richiesta che un'app può inviare a un'API nel corso di un'ora, un giorno, una settimana o un mese. Quando un'app raggiunge il limite di quota, le chiamate API successive vengono rifiutate. Vedi anche Qual è la differenza tra protezione dai picchi e quota?

Aggiungere il plug-in per le quote

Vedi Aggiungere e configurare i plug-in.

Configurazione del prodotto in Apigee Edge

Configura le quote nella UI di Apigee Edge, dove configuri i prodotti API. Devi sapere quale prodotto contiene il proxy compatibile con microgateway che vuoi limitare con una quota. Questo prodotto deve essere aggiunto a un'app per sviluppatori. Quando effettui chiamate API autenticate utilizzando le chiavi nell'app per sviluppatori, la quota verrà applicata a queste chiamate API.

1. Accedi all'account dell'organizzazione Apigee Edge.
2. Nell'interfaccia utente Edge, apri il prodotto associato al proxy compatibile con il microgateway a cui vuoi applicare la quota.
   1. Nell'interfaccia utente, seleziona Prodotti dal menu Pubblica.
   2. Apri il prodotto contenente l'API a cui vuoi applicare la quota.
   3. Fai clic su Modifica.
   4. Nel campo Quota, specifica l'intervallo della quota. Ad esempio, 100 richieste ogni minuto. o 50.000 richieste ogni 2 ore.
      
      

3. Fai clic su Salva.
4. Assicurati che il prodotto sia aggiunto a un'app per sviluppatori. Per effettuare chiamate API autenticate, ti serviranno le chiavi di questa app.

Esempio di configurazione per la quota

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

Opzioni di configurazione per la quota

Per configurare il plug-in quota, aggiungi l'elemento quotas al file di configurazione, come mostrato nell'esempio seguente:

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"
}

Informazioni su come vengono conteggiate le quote

Per impostazione predefinita, il microgateway sincronizza il contatore della quota con Apigee Edge ogni 5 secondi se l'intervallo della quota è impostato su "minuto". Se l'intervallo è impostato su un livello superiore a "minuto", ad esempio "settimana" o "mese", il periodo di aggiornamento predefinito è 1 minuto.

È importante notare che gli intervalli di quota vengono specificati nei prodotti API definiti in Apigee Edge. Gli intervalli di quota specificano il numero di richieste consentite per un minuto, un'ora, un giorno, una settimana o un mese. Ad esempio, il prodotto A potrebbe avere un intervallo di quota di 100 richieste al minuto e il prodotto B potrebbe avere un intervallo di quota di 10.000 richieste all'ora.

La configurazione YAML del plug-in quota di Edge Microgateway non imposta l'intervallo di quota, ma fornisce un modo per regolare la frequenza con cui un'istanza locale di Edge Microgateway sincronizza il conteggio della quota con Apigee Edge.

Ad esempio, supponiamo che in Apigee Edge siano definiti tre prodotti API con i seguenti intervalli di quota specificati:

• Il prodotto A ha una quota di 100 richieste al minuto
• Il prodotto B ha una quota di 5000 richieste all'ora
• Il prodotto C ha una quota di 1.000.000 di richieste al mese

Tenendo presente queste impostazioni di quota, come deve essere configurato il plug-in Edge Microgateway quota? La best practice consiste nel configurare Edge Microgateway con intervalli di sincronizzazione inferiori agli intervalli di quota definiti nei prodotti API. Ad esempio:

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

Questa configurazione definisce i seguenti intervalli di sincronizzazione per i prodotti API descritti in precedenza:

• Il prodotto A è impostato sull'intervallo "minuto". Edge Microgateway si sincronizzerà con Edge dopo ogni 50 richieste o 5 secondi, a seconda dell'evento che si verifica per primo.
• Il prodotto B è impostato sull'intervallo "ora". Edge Microgateway si sincronizzerà con Edge dopo ogni 2000 richieste o 1 minuto, a seconda di quale evento si verifica per primo.
• Il prodotto C è impostato sull'intervallo "mese". Edge Microgateway si sincronizzerà con Edge dopo ogni singola richiesta o dopo 1 minuto, a seconda di quale evento si verifica per primo.

Ogni volta che un'istanza di microgateway si sincronizza con Edge, il conteggio della quota di microgateway viene impostato sul conteggio della quota recuperato.

Le impostazioni di bufferSize consentono di regolare la sincronizzazione del contatore della quota con Edge. In situazioni di traffico elevato, le impostazioni bufferSize consentono la sincronizzazione del contatore del buffer prima dell'attivazione della sincronizzazione predefinita basata sul tempo.

Informazioni sull'ambito della quota

Il conteggio delle quote è limitato a un ambiente in un'organizzazione. Per raggiungere questo ambito, Edge Microgateway crea un identificatore di quota che è una combinazione di "org + env + appName + productName".

Utilizzo di un archivio di supporto Redis per la quota

Per utilizzare un archivio di supporto Redis per la quota, utilizza la stessa configurazione utilizzata per la funzionalità Synchronizer. Di seguito è riportata la configurazione di base necessaria per utilizzare Redis per l'archiviazione delle quote:

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

quotas:
  useRedis: true

Test del plug-in quota

Quando la quota viene superata, al client viene restituito uno stato HTTP 403, insieme al seguente messaggio:

{"error": "exceeded quota"}

Qual è la differenza tra spike arrest e quota?

È importante scegliere lo strumento giusto per il lavoro da svolgere. I criteri per le quote configurano il numero di messaggi di richiesta che un'app client può inviare a un'API nel corso di un'ora, un giorno, una settimana o un mese. I criteri per le quote applicano limiti di consumo alle app client mantenendo un contatore distribuito che conteggia le richieste in entrata.

Utilizza una norma relativa alle quote per applicare contratti commerciali o SLA con sviluppatori e partner, piuttosto che per la gestione del traffico operativo. Ad esempio, una quota potrebbe essere utilizzata per limitare il traffico per un servizio senza costi, consentendo al contempo l'accesso completo ai clienti paganti.

Utilizza l'arresto dei picchi per proteggerti da picchi improvvisi nel traffico API. In genere, l'arresto dei picchi viene utilizzato per prevenire possibili attacchi DDoS o altri attacchi dannosi.