Utilizzare i plug-in

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X.
informazioni

Microgateway Edge v. 3.3.x

Pubblico

Questo argomento è rivolto agli operatori Edge Microgateway che vogliono utilizzare i plug-in esistenti installati con il microgateway. Descrive inoltre in dettaglio l'arresto dei picchi e i plug-in per le quote (entrambi sono inclusi nell'installazione). Se sei uno sviluppatore che vuole sviluppare nuovi plug-in, consulta l'articolo Sviluppare plug-in 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 uno schema coerente e vengono archiviati in una posizione nota a Edge Microgateway, in modo che il microgateway li rilevi e li carichi automaticamente. Edge Microgateway include vari plug-in esistenti e puoi anche creare plug-in personalizzati, come spiegato nella sezione Sviluppare plug-in personalizzati.

Plug-in esistenti in bundle con Edge Microgateway

Al momento dell'installazione di Edge Microgateway, vengono forniti numerosi plug-in. La seguente tabella descrive alcuni dei plug-in più utilizzati.

Plug-in Abilitato per impostazione predefinita Descrizione
Analytics Invia i dati di analisi da Edge Microgateway ad Apigee Edge.
oauth Aggiunge il token OAuth e la convalida delle chiavi API a Edge Microgateway. Consulta Configurazione e configurazione di Edge Microgateway.
quota No Applica la quota per le richieste a Edge Microgateway. Utilizza Apigee Edge per archiviare e gestire le quote. Consulta Utilizzo del plug-in per la quota.
spikearrest No Protegge da picchi di traffico e attacchi DoS. Consulta la sezione Utilizzo del plug-in di arresto dei picchi di traffico.
intestazione-maiuscole No Un proxy di esempio commentato, da utilizzare come guida per aiutare gli sviluppatori a scrivere plug-in personalizzati. Consulta la pagina relativa al plug-in di esempio Edge Microgateway.
accumulare-richiesta No Accumula i dati della richiesta in un singolo oggetto prima di passare i dati al gestore successivo nella catena di plug-in. Utile per scrivere plug-in di trasformazione che devono operare su un singolo oggetto di contenuti di richiesta accumulati.
accumula-risposta No Accumula i dati di risposta in un singolo oggetto prima di passare i dati al gestore successivo nella catena di plug-in. Utile per scrivere plug-in di trasformazione che devono operare su un singolo oggetto di contenuto risposta accumulato.
trasforma-maiuscole No Trasforma i dati delle richieste o delle risposte. Questo plug-in rappresenta una best practice per l'implementazione di un plug-in di trasformazione. Il plug-in di esempio esegue una trasformazione semplice (converte i dati di richiesta o risposta in lettere maiuscole); tuttavia, può essere facilmente adattato per eseguire altri tipi di trasformazioni, ad esempio da XML in JSON.
json2xml No Trasforma i dati di richieste o risposte in base a intestazioni di tipo Accetto o tipo di contenuti. Per maggiori dettagli, consulta la documentazione relativa ai plug-in in GitHub.
quota-memoria No Applica la quota per le richieste a Edge Microgateway. Archivia e gestisce le quote nella memoria locale.
healthcheck No Restituisce informazioni sul processo Edge Microgateway: utilizzo della memoria, utilizzo della CPU e così via. Per utilizzare il plug-in, chiama l'URL /healthcheck sull'istanza del Microgateway Edge. Questo plug-in è un esempio che puoi utilizzare per implementare il tuo plug-in per il controllo di integrità.

Dove trovare i plug-in esistenti

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

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

Aggiungere e configurare plug-in

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

  1. Fermate il Microgateway Edge.
  2. Apri un file di configurazione di Edge Microgateway. Per maggiori dettagli, vedi Modifiche alla configurazione per conoscere le opzioni.
  3. Aggiungi il plug-in all'elemento plugins:sequence del file di configurazione come indicato di seguito. I plug-in vengono eseguiti nell'ordine in cui sono visualizzati nell'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
  1. Configura il plug-in. Alcuni plug-in hanno parametri facoltativi che possono essere configurati nel file di configurazione. Ad esempio, puoi aggiungere la stanza seguente per configurare il plug-in per l'arresto dei picchi. Per ulteriori informazioni, consulta la sezione sull'utilizzo del plug-in 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
    
  1. Salva il file.
  2. Riavvia o ricarica Edge Microgateway, a seconda del file di configurazione che hai modificato.

Configurazione specifica per il plug-in

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

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

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

plugins/<plugin_name>/config/default.yaml. Ad esempio, potresti inserire questo blocco in plugins/spikearrest/config/default.yaml, in modo da sostituire qualsiasi altra impostazione di configurazione.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Utilizzare il plug-in di arresto dei picchi di traffico

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

Aggiunta del plug-in di arresto dei picchi di traffico

Consulta la sezione Aggiungere e configurare 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 l'arresto dei picchi di traffico

  • timeUnit: la frequenza con cui viene reimpostata la finestra di esecuzione dell'arresto dei picchi. I valori validi sono secondi o minuti.
  • allow: il numero massimo di richieste da consentire durante l'intervallo di tempo timeUnit. Vedi anche Se esegui più processi Edge Micro.
  • bufferSize: (facoltativo, predefinito = 0) se bufferSize > 0, l'arresto dei picchi archivia questo numero di richieste in un buffer. Non appena si verifica la successiva "finestra" di esecuzione, le richieste nel buffer verranno elaborate per prime. Vedi anche Aggiunta di un buffer.

Come funziona l'arresto dei picchi?

Pensa all'arresto dei picchi come a un modo per proteggere in genere dai picchi di traffico, piuttosto che come a un modo per limitare il traffico a un numero specifico di richieste. Le API e il backend possono gestire una certa quantità di traffico e il criterio di arresto per i picchi di traffico ti aiuta a semplificare il traffico verso gli importi generici che vuoi.

Il comportamento di arresto dei picchi di runtime è diverso da ciò che ti aspetti dai valori letterali al minuto o al secondo che inserisci.

Supponiamo, ad esempio, di specificare una frequenza di 30 richieste al minuto, come segue:

spikearrest:
   timeUnit: minute
   allow: 30

Durante i test, potresti pensare di inviare 30 richieste in un secondo, a condizione che vengano ricevute entro un minuto. Ma questo non è il modo in cui il criterio 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 allora? Per evitare comportamenti di tipo picco, l'arresto dei picchi snellisce il traffico consentito dividendo le impostazioni in intervalli più piccoli, come segue:

Tariffe al minuto

Le tariffe al minuto vengono semplificate negli intervalli di secondi consentiti per le richieste. Ad esempio, 30 richieste al minuto vengono semplificate 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 avrà esito negativo. Inoltre, la 31a richiesta entro un minuto non andrà a buon fine.

Tariffe al secondo

Le frequenze al secondo vengono semplificate nelle richieste consentite a intervalli di millisecondi. Ad esempio, 10 richieste al secondo vengono semplificate in questo modo:

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

Quando il limite viene superato

Se il numero di richieste supera il limite nell'intervallo di tempo specificato, l'arresto dei picchi restituisce questo messaggio di errore con stato HTTP 503:

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

Aggiunta di un buffer

Hai la possibilità di aggiungere un buffer al criterio. Supponiamo che tu abbia impostato il buffer su 10. Noterai che l'API non restituisce immediatamente un errore quando superi il limite di arresto dei picchi. Le richieste, invece, vengono 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. L'arresto con picchi calcola il numero consentito di richieste per processo di worker. Per impostazione predefinita, il numero di processi Edge Micro corrisponde 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 l'arresto 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 dell'arresto dei picchi. In sintesi, come regola generale imposta il parametro di configurazione allow sul valore "numero di arresto dei picchi desiderato / numero di processi".

Utilizzare il plug-in per le quote

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 successive chiamate API vengono rifiutate. Vedi anche Qual è la differenza tra arresto dei picchi e quota?

Aggiunta del plug-in per la quota

Consulta la sezione Aggiungere e configurare plug-in.

Configurazione del prodotto in Apigee Edge

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

  1. Accedi all'account dell'organizzazione Apigee Edge.
  2. Nella UI di Edge, apri il prodotto associato al proxy sensibile al 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 di quota. Ad esempio, 100 richieste al minuto. O 50.000 richieste ogni 2 ore.

  1. Fai clic su Salva.
  2. Assicurati che il prodotto venga aggiunto a un'app per sviluppatori. Avrai bisogno delle chiavi di questa app per effettuare chiamate API autenticate.

Configurazione di esempio 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 della 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
...
Opzione Descrizione
bufferSize

(Numero intero) La configurazione bufferSize consente di regolare la frequenza con cui Edge Microgateway sincronizza il conteggio delle quote con Apigee Edge. Per comprendere bufferSize, considera la seguente configurazione di esempio:

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

Per impostazione predefinita, il microgateway sincronizza il proprio contatore di quote con Apigee Edge ogni 5 secondi se l'intervallo di quota è impostato su "minuto". La configurazione precedente indica che se nel prodotto API l'intervallo di quota è impostato su "minuto", Edge Microgateway eseguirà la sincronizzazione con Edge per ottenere il conteggio della quota attuale dopo ogni 500 richieste o dopo 5 secondi, a seconda dell'evento che si verifica per primo. Per maggiori informazioni, consulta la sezione Informazioni sulla modalità di conteggio delle quote.

Le unità di tempo consentite includono: minute, hour, day, week, month e default.

isHTTPStatusTooManyRequestEnabled

Configura il plug-in per le quote in modo che restituisca uno stato di risposta HTTP 429 anziché uno stato 403 in caso di violazione della quota.

Valore predefinito: false. Per impostazione predefinita, o se il flag è impostato su false, la quota restituisce lo stato HTTP 403 quando viene superata.

Se il flag è impostato su true, la quota restituisce lo stato HTTP 429 quando viene superata.

Per cambiare lo stato di ritorno HTTP predefinito su 429, utilizza la seguente configurazione:

edgemicro:
...
quotas:
  isHTTPStatusTooManyRequestEnabled: true
...
failOpen Quando questa funzionalità è abilitata, se si verifica un errore nell'elaborazione della quota o se la richiesta di applicazione della quota a Edge non riesce ad aggiornare i contatori delle quote remote, la quota verrà elaborata in base ai conteggi locali solo fino alla successiva sincronizzazione riuscita della quota remota. In entrambi i casi, viene impostato un flag quota-failed-open nell'oggetto della richiesta.

Per abilitare la funzionalità di mancata apertura della quota, imposta la seguente configurazione:

edgemicro:
...
quotas:
  failOpen: true
...
useDebugMpId Imposta questo flag su true per abilitare il logging dell'ID MP (processore messaggi) nelle risposte di quota.

Per utilizzare questa funzionalità, devi impostare la seguente configurazione:

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

Se useDebugMpId è impostato, le risposte di quota di Edge conterranno l'ID MP e verranno registrate da Edge Microgateway. Ad esempio:

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}
useRedis Se impostato su true, il plug-in utilizza Redis per l'archivio di backup della quota. Per maggiori dettagli, vedi Utilizzo di un backstore Redis per la quota.

Informazioni su come vengono conteggiate le quote

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

È importante notare che specifichi gli intervalli di quota nei prodotti API definiti su Apigee Edge. Gli intervalli di quota specificano il numero di richieste consentite per minuto, ora, giorno, settimana o 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 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 delle quote con Apigee Edge.

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

  • 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 1000000 richieste al mese

Tenendo a mente queste impostazioni di quota, come deve essere configurato il plug-in quota di Edge Microgateway? La best practice prevede di configurare Edge Microgateway con intervalli di sincronizzazione inferiori a quelli 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 in "minuti". 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 richiesta o 1 minuto, a seconda dell'evento che 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 dell'evento che si verifica per primo.

Ogni volta che un'istanza del microgateway si sincronizza con Edge, il conteggio delle quote del microgateway viene impostato sul conteggio della quota recuperata.

Le impostazioni bufferSize consentono di regolare la modalità di sincronizzazione del contatore delle quote con Edge. In situazioni di traffico elevato, le impostazioni bufferSize consentono al contatore del buffer di sincronizzarsi prima dell'attivazione della sincronizzazione predefinita basata sulla durata.

Informazioni sull'ambito della quota

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

Utilizzo di un backupstore Redis per la quota

Per utilizzare un archivio di backup Redis per la quota, usa la stessa configurazione utilizzata per la funzionalità di sincronizzazione. Di seguito è riportata la configurazione di base richiesta per utilizzare Redis per l'archiviazione della quota:

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

quotas:
  useRedis: true
Per informazioni dettagliate sui parametri edgemicro.redis*, consulta Utilizzo del sincronizzatore.

Test del plug-in per le quote

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

{"error": "exceeded quota"}

Qual è la differenza tra arresto dei picchi e quota?

È importante scegliere lo strumento giusto per il lavoro da svolgere. I criteri per le quote consentono di configurare 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. Il criterio per le quote applica i limiti di consumo sulle app client mediante il mantenimento di un contatore distribuito che rileva le richieste in entrata.

Utilizza i criteri per le quote per applicare contratti aziendali o SLA (accordi sul livello del servizio) con sviluppatori e partner, anziché per la gestione del traffico operativo. Ad esempio, potresti utilizzare una quota per limitare il traffico di 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 delle API. In genere, l'arresto dei picchi viene utilizzato per scongiurare possibili attacchi DDoS o altri attacchi dannosi.