Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Edge Microgateway v. 3.2.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
Diversi plug-in esistenti vengono forniti con Edge Microgateway al momento dell'installazione. tra cui:
Plug-in | Abilitato per impostazione predefinita | Descrizione |
---|---|---|
Analytics | Sì | Invia i dati di analisi da Edge Microgateway ad Apigee Edge. |
oauth | Sì | 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:
- Fermate il Microgateway Edge.
- Apri un file di configurazione di Edge Microgateway. Per maggiori dettagli, vedi Modifiche alla configurazione per conoscere le opzioni.
- 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
- 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
- Salva il file.
- 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.
- Accedi all'account dell'organizzazione Apigee Edge.
- Nella UI di Edge, apri il prodotto associato al proxy sensibile al microgateway a cui vuoi applicare la quota.
- Nell'interfaccia utente, seleziona Prodotti dal menu Pubblica.
- Apri il prodotto contenente l'API a cui vuoi applicare la quota.
- Fai clic su Modifica.
- Nel campo Quota, specifica l'intervallo di quota. Ad esempio, 100 richieste al minuto. O 50.000 richieste ogni 2 ore.
- Fai clic su Salva.
- 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 ...
Opzione | Descrizione |
---|---|
bufferSize |
(Numero intero) La configurazione 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: |
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 { "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: truePer 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.