Questa pagina è stata tradotta dall'API Cloud Translation.

Riferimento per le operazioni e la configurazione di Edge Microgateway

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

Edge Microgateway v. 3.2.x

Questo argomento spiega come gestire e configurare Edge Microgateway.

Eseguire l'upgrade di Edge Microgateway se disponi di una connessione a internet

Questa sezione spiega come eseguire l'upgrade di un'installazione esistente di Edge Microgateway. Se operi senza una connessione a internet, consulta Posso installare Edge Microgateway senza una connessione a internet?.

Apigee consiglia di testare la configurazione esistente con la nuova versione prima di eseguire l'upgrade dell'ambiente di produzione.

Esegui il seguente comando npm per eseguire l'upgrade alla versione più recente di Edge Microgateway:
```
npm upgrade edgemicro -g
```
Per installare una versione specifica di Edge Microgateway, devi specificare il numero di versione nel comando di installazione. Ad esempio, per installare la versione 3.2.3, utilizza il seguente comando:
```
npm install edgemicro@3.2.3 -g
```

Controlla il numero di versione. Ad esempio, se hai installato la versione 3.2.3:

edgemicro --version
current nodejs version is v12.5.0
current edgemicro version is 3.2.3

Infine, esegui l'upgrade alla versione più recente del proxy edgemicro-auth:
```
edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME
```

Apportare modifiche alla configurazione

I file di configurazione che devi conoscere includono:

File di configurazione di sistema predefinito
File di configurazione predefinito per un'istanza Edge Microgateway appena inizializzata
File di configurazione dinamico per le istanze in esecuzione

Questa sezione illustra questi file e cosa devi sapere per modificarli.

File di configurazione di sistema predefinito

Quando installi Edge Microgateway, un file di configurazione di sistema predefinito viene inserito qui:

prefix/lib/node_modules/edgemicro/config/default.yaml

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

Se modifichi il file di configurazione di sistema, devi inizializzare, riconfigurare e riavviare Edge Microgateway:

edgemicro init
edgemicro configure [params]
edgemicro start [params]

File di configurazione predefinito per le istanze Edge Microgateway appena inizializzate

Quando esegui edgemicro init, il file di configurazione di sistema (descritto sopra), default.yaml, viene inserito nella directory ~/.edgemicro.

Se modifichi il file di configurazione in ~/.edgemicro, devi ricollegare e riavviare Edge Microgateway:

edgemicro stop
edgemicro configure [params]
edgemicro start [params]

File di configurazione dinamico per le istanze in esecuzione

Quando esegui edgemicro configure [params], viene creato un file di configurazione dinamico in ~/.edgemicro. Il file è denominato in base a questo schema: org-env-config.yaml, dove org e env sono i nomi dell'organizzazione e dell'ambiente Apigee Edge. Puoi utilizzare questo file per apportare modifiche alla configurazione, quindi ricaricarle senza tempi di riposo. Ad esempio, se aggiungi e configuri un plug-in, puoi ricaricare la configurazione senza tempi di riposo, come spiegato di seguito.

Se Edge Microgateway è in esecuzione (opzione senza tempo di riposo):

Ricarica la configurazione di Edge Microgateway:
```
edgemicro reload -o $ORG -e $ENV -k $KEY -s $SECRET
```
Dove:
- $ORG è il nome della tua organizzazione Edge (devi essere un amministratore dell'organizzazione).
- $ENV è un ambiente nella tua organizzazione (ad esempio "test" o "prod").
- $KEY è la chiave restituita in precedenza dal comando configure.
- $SECRET è la chiave restituita in precedenza dal comando configure.
Ad esempio:
```
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \
  -s 05c14356e42ed1...4e34ab0cc824
```

Se Edge Microgateway è fermo:

Riavvia Edge Microgateway:
```
edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET
```
Dove:
- $ORG è il nome della tua organizzazione Edge (devi essere un amministratore dell'organizzazione).
- $ENV è un ambiente della tua organizzazione (ad esempio "test" o "prod").
- $KEY è la chiave restituita in precedenza dal comando configure.
- $SECRET è la chiave restituita in precedenza dal comando configure.
Ad esempio:
```
edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
  -s 05c1435...e34ab0cc824
```

Ecco un esempio di file di configurazione. Per informazioni dettagliate sulle impostazioni del file di configurazione, consulta la documentazione di riferimento sulla configurazione di Edge Microgateway.

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

Imposta le variabili di ambiente

I comandi dell'interfaccia a riga di comando che richiedono valori per l'organizzazione e per l'ambiente Edge, nonché la chiave e il segreto necessari per avviare Edge Microgateway, possono essere memorizzati in queste variabili di ambiente:

EDGEMICRO_ORG
EDGEMICRO_ENV
EDGEMICRO_KEY
EDGEMICRO_SECRET

L'impostazione di queste variabili è facoltativa. Se li imposti, non devi specificare i relativi valori quando utilizzi l'interfaccia a riga di comando (CLI) per configurare e avviare Edge Microgateway.

Configurazione di SSL sul server Edge Microgateway

Guarda i seguenti video per scoprire come configurare TLS nel microgateway Apigee Edge:

Video	Descrizione
Configurare TLS unidirezionale in uscita	Scopri come configurare TLS in Apigee Edge Microgateway. Questo video fornisce una panoramica di TLS e della sua importanza, introduce TLS in Edge Microgateway e mostra come configurare TLS unidirezionale in uscita.
Configurare TLS nord-sud bidirezionale	Questo è il secondo video sulla configurazione di TLS in Apigee Edge Microgateway. Questo video spiega come configurare TLS bidirezionale verso nord.
Configurare TLS in uscita unidirezionale e bidirezionale	Questo terzo video sulla configurazione di TLS in Apigee Edge Microgateway spiega come configurare TLS unidirezionale e bidirezionale southbound.

Puoi configurare il server Microgateway in modo che utilizzi SSL. Ad esempio, con SSL configurato, puoi chiamare le API tramite Edge Microgateway con il protocollo "https", come segue:

https://localhost:8000/myapi

Per configurare SSL sul server Microgateway, segui questi passaggi:

Genera o ottieni un certificato e una chiave SSL utilizzando l'utilità openssl o il metodo che preferisci.

Aggiungi l'attributo edgemicro:ssl al file di configurazione di Edge Microgateway. Per un elenco completo delle opzioni, consulta la tabella seguente. Ad esempio:

edgemicro:
  ssl:
   key: <absolute path to the SSL key file>
   cert: <absolute path to the SSL cert file>
   passphrase: admin123 #option added in v2.2.2
   rejectUnauthorized: true #option added in v2.2.2
   requestCert: true

Riavvia Edge Microgateway. Segui i passaggi descritti in Eseguire modifiche alla configurazione a seconda del file di configurazione modificato: il file predefinito o il file di configurazione di runtime.

Ecco un esempio della sezione edgemicro del file di configurazione con SSL configurato:

edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
  ssl:
    key: /MyHome/SSL/em-ssl-keys/server.key
    cert: /MyHome/SSL/em-ssl-keys/server.crt
    passphrase: admin123 #option added in v2.2.2
    rejectUnauthorized: true #option added in v2.2.2

Di seguito è riportato un elenco di tutte le opzioni del server supportate:

Opzione	Descrizione
`key`	Percorso di un file `ca.key` (in formato PEM).
`cert`	Percorso di un file `ca.cert` (in formato PEM).
`pfx`	Percorso di un file `pfx` contenente la chiave privata, il certificato e i certificati CA del client in formato PFX.
`passphrase`	Una stringa contenente la passphrase per la chiave privata o il file PFX.
`ca`	Percorso di un file contenente un elenco di certificati attendibili in formato PEM.
`ciphers`	Una stringa che descrive le cifre da utilizzare separate da un ":".
`rejectUnauthorized`	Se true, il certificato del server viene verificato in base all'elenco delle CA fornite. Se la verifica non va a buon fine, viene restituito un errore.
`secureProtocol`	Il metodo SSL da utilizzare. Ad esempio, SSLv3_method per forzare la versione 3 di SSL.
`servername`	Il nome del server per l'estensione TLS SNI (Server Name Indication).
`requestCert`	true per SSL bidirezionale; false per SSL unidirezionale

Utilizzo delle opzioni SSL/TLS client

Puoi configurare Edge Microgateway come client TLS o SSL quando ti connetti agli endpoint di destinazione. Nel file di configurazione di Microgateway, utilizza l'elemento targets per impostare le opzioni SSL/TLS. Tieni presente che puoi specificare più target specifici. Di seguito è riportato un esempio di targeting multiplo.

Questo esempio fornisce le impostazioni che verranno applicate a tutti gli host:

edgemicro:
...
targets:
  ssl:
    client:
      key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
      cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
      passphrase: admin123
      rejectUnauthorized: true

In questo esempio, le impostazioni vengono applicate solo all'host specificato:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    ssl:
      client:
        key: /Users/myname/twowayssl/ssl/client.key
        cert: /Users/myname/twowayssl/ssl/ca.crt
        passphrase: admin123
        rejectUnauthorized: true

Ecco un esempio per TLS:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    tls:
      client:
        pfx: /Users/myname/twowayssl/ssl/client.pfx
        passphrase: admin123
        rejectUnauthorized: true

Se vuoi applicare le impostazioni TLS/SSL a più destinazioni specifiche, devi specificare il primo host nella configurazione come "vuoto", il che attiva le richieste universali, quindi specificare gli host specifici in qualsiasi ordine. In questo esempio, le impostazioni vengono applicate a più host specifici:

targets:
 - host:   ## Note that this value must be "empty"
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       passphrase: admin123
       rejectUnauthorized: true
 - host: 'myserver1.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true
 - host: 'myserver2.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true

Di seguito è riportato un elenco di tutte le opzioni client supportate:

Opzione	Descrizione
`pfx`	Percorso di un file `pfx` contenente la chiave privata, il certificato e i certificati CA del client in formato PFX.
`key`	Percorso di un file `ca.key` (in formato PEM).
`passphrase`	Una stringa contenente la passphrase per la chiave privata o il file PFX.
`cert`	Percorso di un file `ca.cert` (in formato PEM).
`ca`	Percorso di un file contenente un elenco di certificati attendibili in formato PEM.
`ciphers`	Una stringa che descrive le cifre da utilizzare separate da un ":".
`rejectUnauthorized`	Se true, il certificato del server viene verificato in base all'elenco delle CA fornite. Se la verifica non va a buon fine, viene restituito un errore.
`secureProtocol`	Il metodo SSL da utilizzare. Ad esempio, SSLv3_method per forzare la versione 3 di SSL.
`servername`	Il nome del server per l'estensione TLS SNI (Server Name Indication).

Personalizzazione del proxy edgemicro-auth

Per impostazione predefinita, Edge Microgateway utilizza un proxy di cui è stato eseguito il deployment su Apigee Edge per l'autenticazione OAuth2. Questo proxy viene implementato quando esegui inizialmente edgemicro configure. Puoi modificare la configurazione predefinita di questo proxy per aggiungere il supporto di attestazioni personalizzate a un token web JSON (JWT), configurare la scadenza del token e generare token di aggiornamento. Per maggiori dettagli, consulta la pagina edgemicro-auth su GitHub.

Utilizzo di un servizio di autenticazione personalizzato

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

Se vuoi utilizzare il tuo servizio personalizzato per gestire l'autenticazione, modifica il valore authUri nel file di configurazione in modo che rimandi al tuo servizio. Ad esempio, potresti avere un servizio che utilizza LDAP per verificare l'identità.

Importante: se sostituisci il proxy di autenticazione predefinito, il nuovo proxy o servizio deve restituire un formato di risposta identico a quello del proxy edgemicro-auth predefinito.

Gestione dei file di log

Edge Microgateway registra informazioni su ogni richiesta e risposta. I file di log forniscono informazioni utili per il debug e la risoluzione dei problemi.

Dove vengono archiviati i file di log

Per impostazione predefinita, i file di log vengono archiviati in /var/tmp.

Come modificare la directory dei file log predefinita

La directory in cui vengono archiviati i file di log è specificata nel file di configurazione di Edge Microgateway. Consulta anche Apportare modifiche alla configurazione.

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Modifica il valore dir per specificare una directory dei file di log diversa.

Invia i log alla console

Puoi configurare la registrazione in modo che le informazioni dei log vengano inviate all'output standard anziché a un file di log. Imposta il flag to_console su true come segue:

edgemicro:
  logging:
    to_console: true

Con questa impostazione, i log verranno inviati allo standard out. Al momento, non puoi inviare i log sia allo stato di uscita sia a un file di log.

Come impostare il livello di logging

Specifica il livello di log da utilizzare nella configurazione edgemicro. Per un elenco completo dei livelli di log e delle relative descrizioni, consulta gli attributi edgemicro.

Ad esempio, la seguente configurazione imposta il livello di logging su debug:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: debug
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Come modificare gli intervalli di log

Puoi configurare questi intervalli nel file di configurazione di Edge Microgateway. Consulta anche Apportare modifiche alla configurazione.

Gli attributi configurabili sono:

stats_log_interval: (valore predefinito: 60) Intervallo, in secondi, in cui viene scritto il record di statistiche nel file di log dell'API.
rotate_interval: (valore predefinito: 24) Intervallo, in ore, in cui vengono girati i file di log. Ad esempio:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Come allentare le autorizzazioni rigorose dei file di log

Per impostazione predefinita, Edge Microgateway genera il file di log dell'applicazione (api-log.log) con il livello di autorizzazione del file impostato su 0600. Questo livello di autorizzazione non consente ad applicazioni o utenti esterni di leggere il file di log. Per allentare questo livello di autorizzazione rigoroso, imposta logging:disableStrictLogFile su true. Quando questo attributo è true, il file di log viene creato con l'autorizzazione del file impostata su 0755. Se false o se l'attributo non viene fornito, l'autorizzazione predefinita è 0600.

Aggiunta nella versione 3.2.3.

Ad esempio:

edgemicro:
 logging:
   disableStrictLogFile: true

Buone pratiche per la manutenzione dei file di log

Poiché i dati dei file di log si accumulano nel tempo, Apigee consiglia di adottare le seguenti pratiche:

Poiché i file di log possono diventare molto grandi, assicurati che la directory dei file di log abbia spazio sufficiente. Consulta le seguenti sezioni Dove vengono archiviati i file di log e Come modificare la directory predefinita dei file di log.
Elimina o sposta i file di log in una directory di archivio separata almeno una volta alla settimana.
Se il tuo criterio è eliminare i log, puoi utilizzare il comando CLI edgemicro log -c per rimuovere (pulire) i log precedenti.

Convenzione di denominazione dei file di log

Ogni istanza Edge Microgateway produce un file di log con estensione .log. La convenzione di denominazione per i file di log è la seguente:

edgemicro-HOST_NAME-INSTANCE_ID-api.log

Ad esempio:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log

Informazioni sui contenuti dei file di log

Aggiunto in: v2.3.3

Per impostazione predefinita, il servizio di registrazione omette il JSON dei proxy e dei prodotti scaricati e il token web JSON (JWT). Se vuoi visualizzare questi oggetti nella console, imposta il flag della riga di comando DEBUG=* quando avvii Edge Microgateway. Ad esempio:

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

Su Windows, utilizza SET DEBUG=*

Contenuti del file di log "api"

Il file di log "api" contiene informazioni dettagliate sul flusso di richieste e risposte tramite Edge Microgateway. I file di log "api" sono denominati come segue:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

Per ogni richiesta effettuata a Edge Microgateway, nel file log "api" vengono acquisiti quattro eventi:

Richiesta in arrivo dal client
Richiesta in uscita effettuata al target
Risposta in arrivo dal target
Risposta in uscita al cliente

Ognuna di queste voci separate è rappresentata in una notazione abbreviata per contribuire a rendere i file log più compatti. Di seguito sono riportate quattro voci di esempio che rappresentano ciascuno dei quattro eventi. Nel file di log, hanno il seguente aspetto (i numeri di riga sono solo per riferimento nel documento e non vengono visualizzati nel file di log).

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

Vediamoli uno alla volta:

1. Esempio di richiesta in arrivo dal cliente:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0

1436403888651 - timestamp Unix
info: il livello di logging. Questo valore dipende dal contesto della transazione e dal livello di registrazione impostato nella configurazione di edgemicro. Consulta Come impostare il livello di logging. Per i record delle statistiche, il livello è impostato su stats. I record delle statistiche vengono registrati a un intervallo regolare impostato con la configurazione stats_log_interval. Consulta anche Come modificare gli intervalli dei log.
req: identifica l'evento. In questo caso, richiedi al cliente.
m: il verbo HTTP utilizzato nella richiesta.
u: la parte dell'URL che segue il percorso di base.
h: l'host e il numero di porta su cui Edge Microgateway è in ascolto.
r: l'host e la porta remoti da cui ha avuto origine la richiesta del client.
i: l'ID richiesta. Tutte e quattro le voci evento condivideranno questo ID. A ogni richiesta viene assegnato un ID univoco. La correlazione dei record dei log in base all'ID richiesta può fornire informazioni preziose sulla latenza del target.
d: la durata in millisecondi dall'invio della richiesta da parte del microgateway Edge. Nell'esempio precedente, la risposta del target per la richiesta 0 è stata ricevuta dopo 7 millisecondi (riga 3) e la risposta è stata inviata al client dopo altri 4 millisecondi (riga 4). In altre parole, la latenza totale della richiesta era di 11 millisecondi, di cui 7 millisecondi sono stati occupati dal target e 4 millisecondi dall'Edge Microgateway stesso.

2. Esempio di richiesta in uscita effettuata al target:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0

1436403888651 - timestamp Unix
info: il livello di logging. Questo valore dipende dal contesto della transazione e dal livello di registrazione impostato nella configurazione di edgemicro. Consulta Come impostare il livello di logging. Per i record delle statistiche, il livello è impostato su stats. I record delle statistiche vengono registrati a un intervallo regolare impostato con la configurazione stats_log_interval. Consulta anche Come modificare gli intervalli dei log.
treq: identifica l'evento. In questo caso, richiesta target.
m: il verbo HTTP utilizzato nella richiesta di destinazione.
u: la parte dell'URL che segue il percorso di base.
h: l'host e il numero di porta del target di backend.
i: l'ID della voce di log. Tutte e quattro le voci evento condivideranno questo ID.

3. Esempio di risposta in arrivo dal target

1436403888672 info tres s=200, d=7, i=0

1436403888651 - timestamp Unix

info: il livello di logging. Questo valore dipende dal contesto della transazione e dal livello di registrazione impostato nella configurazione di edgemicro. Consulta Come impostare il livello di logging. Per i record delle statistiche, il livello è impostato su stats. I record delle statistiche vengono registrati a un intervallo regolare impostato con la configurazione stats_log_interval. Consulta anche Come modificare gli intervalli dei log.
tres: identifica l'evento. In questo caso, la risposta target.
s: lo stato della risposta HTTP.
d: la durata in millisecondi. Il tempo impiegato per la chiamata API da parte del target.
i: l'ID della voce di log. Tutte e quattro le voci evento condivideranno questo ID.

4. Esempio di risposta in uscita al cliente

1436403888676 info res s=200, d=11, i=0

1436403888651 - timestamp Unix

info: il livello di logging. Questo valore dipende dal contesto della transazione e dal livello di registrazione impostato nella configurazione di edgemicro. Consulta Come impostare il livello di logging. Per i record delle statistiche, il livello è impostato su stats. I record delle statistiche vengono registrati a un intervallo regolare impostato con la configurazione stats_log_interval. Consulta anche Come modificare gli intervalli dei log.
res: identifica l'evento. In questo caso, la risposta al client.
s: lo stato della risposta HTTP.
d: la durata in millisecondi. Si tratta del tempo totale impiegato dalla chiamata API, inclusi il tempo impiegato dall'API di destinazione e il tempo impiegato dal microgateway Edge stesso.
i: l'ID della voce di log. Tutte e quattro le voci evento condivideranno questo ID.

Pianificazione dei file di log

I file di log vengono ruotati nell'intervallo specificato dall'attributo di configurazione rotate_interval. Le voci continueranno ad essere aggiunte allo stesso file di log fino alla scadenza dell'intervallo di rotazione. Tuttavia, ogni volta che Edge Microgateway viene riavviato, riceve un nuovo UID e crea un nuovo set di file di log con questo UID. Consulta anche Buone pratiche per la gestione dei file log.

Messaggi di errore

Alcune voci di log conterranno messaggi di errore. Per identificare dove e perché si verificano gli errori, consulta il riferimento agli errori di Edge Microgateway.

Riferimento per la configurazione di Edge Microgateway

Posizione del file di configurazione

Gli attributi di configurazione descritti in questa sezione si trovano nel file di configurazione di Edge Microgateway. Consulta anche Apportare modifiche alla configurazione.

Attributi edge_config

Queste impostazioni vengono utilizzate per configurare l'interazione tra l'istanza Edge Microgateway e Apigee Edge.

bootstrap: (valore predefinito: nessuno) un URL che rimanda a un servizio specifico per microgateway Edge in esecuzione su Apigee Edge. Edge Microgateway utilizza questo servizio per comunicare con Apigee Edge. Questo URL viene restituito quando esegui il comando per generare la coppia di chiavi pubblica/privata: edgemicro genkeys. Per maggiori dettagli, consulta la sezione Configurare Edge Microgateway.
jwt_public_key: (valore predefinito: nessuno) un URL che rimanda al proxy Edge Microgateway di cui è stato eseguito il deployment su Apigee Edge. Questo proxy funge da endpoint di autenticazione per la generazione di token di accesso firmati per i client. Questo URL viene restituito quando esegui il comando per eseguire il deployment del proxy: edgemicro configure. Per maggiori dettagli, consulta la sezione Configurare Edge Microgateway.
quotaUri: imposta questa proprietà di configurazione se vuoi gestire le quote tramite il proxy edgemicro-auth di cui è stato eseguito il deployment nella tua organizzazione. Se questa proprietà non è impostata, l'endpoint quota predefinito è l'endpoint Edge Microgateway interno.
```
edge_config:
  quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
```

Attributi edgemicro

Queste impostazioni configurano il processo Edge Microgateway.

port: (valore predefinito: 8000) il numero di porta su cui rimane in ascolto il processo Edge Microgateway.
max_connections: (valore predefinito: -1) specifica il numero massimo di connessioni in entrata simultanee che Edge Microgateway può ricevere. Se questo numero viene superato, viene restituito il seguente stato:

res.statusCode = 429; // Too many requests
max_connections_hard: (valore predefinito: -1) il numero massimo di richieste simultanee che Edge Microgateway può ricevere prima di arrestare la connessione. Questa impostazione è progettata per sventare gli attacchi di tipo "denial of service". In genere, impostalo su un numero maggiore di max_connections.
logging:
- level: (valore predefinito: error)
  - info: (opzione consigliata) registra tutte le richieste e le risposte che passano attraverso un'istanza Edge Microgateway.
  - warn: registra solo i messaggi di avviso.
  - error: registra solo i messaggi di errore.
  - debug: registra i messaggi di debug insieme a messaggi di informazioni, avviso ed errore.
  - trace: registra le informazioni di traccia per gli errori, oltre a messaggi di informazioni, avviso ed errore.
  - none: non viene creato alcun file di log.
- dir: (valore predefinito: /var/tmp) la directory in cui vengono memorizzati i file di log.
- stats_log_interval: (valore predefinito: 60) Intervallo, in secondi, in cui viene scritto il record statistiche nel file di log dell'API.
- rotate_interval: (valore predefinito: 24) Intervallo, in ore, in cui vengono girati i file di log.

plugins: i plug-in aggiungono funzionalità a Edge Microgateway. Per informazioni dettagliate sullo sviluppo di plug-in, vedi Sviluppare plug-in personalizzati.

dir: un percorso relativo dalla directory ./gateway alla directory ./plugins o un percorso assoluto.
sequence: un elenco di moduli plug-in da aggiungere all'istanza Edge Microgateway. I moduli verranno eseguiti nell'ordine in cui sono specificati qui.

debug: aggiunge il debug remoto al processo Edge Microgateway.
- port: il numero di porta su cui ascoltare. Ad esempio, imposta il debugger IDE in modo che esegua l'ascolto su questa porta.
- args: argomenti per il processo di debug. Ad esempio: args --nolazy
config_change_poll_interval: (valore predefinito: 600 secondi) Edge Microgateway carica periodicamente una nuova configurazione ed esegue un ricaricamento in caso di modifiche. Il polling rileva eventuali modifiche apportate a Edge (modifiche ai prodotti, proxy compatibili con i microgateway e così via), nonché le modifiche apportate al file di configurazione locale.
disable_config_poll_interval: (valore predefinito: false) Imposta su true per disattivare il polling delle modifiche automatiche.
request_timeout: imposta un timeout per le richieste target. Il timeout è impostato in secondi. Se si verifica un timeout, Edge Microgateway risponde con un codice di stato 504. (Aggiunta v2.4.x)
keep_alive_timeout: questa proprietà consente di impostare il timeout (in millisecondi) del microgateway Edge. (valore predefinito: 5 secondi) (aggiunto nella versione 3.0.6)
headers_timeout: questo attributo limita il tempo (in millisecondi) che il parser HTTP attenderà per ricevere le intestazioni HTTP complete.
Ad esempio:
```
edgemicro:
  keep_alive_timeout: 6000
  headers_timeout: 12000
```
Internamente, il parametro imposta l'attributo Node.js Server.headersTimeout sulle richieste. (Valore predefinito: 5 secondi in più rispetto al tempo impostato con edgemicro.keep_alive_timeout. Questa impostazione predefinita impedisce ai bilanciatori del carico o ai proxy di disconnettere erroneamente la connessione. (Aggiunta nella versione 3.1.1)
noRuleMatchAction: (stringa) L'azione da eseguire (consenti o nega l'accesso) se la regola di corrispondenza specificata nel plug-in accesscontrol non viene risolta (non corrisponde). Valori validi: ALLOW o DENY Valore predefinito: ALLOW (aggiunto nella versione 3.1.7)
enableAnalytics: (valore predefinito: true) imposta l'attributo su false per impedire il caricamento del plug-in di analisi. In questo caso, non verranno effettuate chiamate ad Apigee Edge Analytics. Se impostato su true o se questo attributo non viene fornito, il plug-in di analisi funzionerà come al solito. Per maggiori dettagli, consulta gli attributi edgemicro. (Aggiunta nella versione 3.1.8).
Esempio:
```
edgemicro
  enableAnalytics=false|true
```
Se enableAnalytics è impostato su false, ma Edge Microgateway viene avviato utilizzando il plug-in delle metriche, il plug-in di analisi funzionerà come di consueto, perché il plug-in delle metriche ha bisogno del plug-in di analisi per funzionare. Per informazioni sul plug-in delle metriche, consulta le note di rilascio di Edge Microgateway 1.3.6.

on_target_response_abort: questo attributo consente di controllare il comportamento di Edge Microgateway se la connessione tra il client (Edge Microgateway) e il server di destinazione si chiude prematuramente.

Valore	Descrizione
Predefinito	Se `on_target_response_abort` non è specificato, il comportamento predefinito è troncare la risposta senza mostrare un errore. Nei file di log viene visualizzato un messaggio di avviso con `targetResponse aborted` e un codice di risposta 502.
`appendErrorToClientResponseBody`	L'errore personalizzato `TargetResponseAborted` viene restituito al client. Nei file di log viene visualizzato un messaggio di avviso con `targetResponse aborted` e un codice di risposta 502. Inoltre, viene registrato l'errore `TargetResponseAborted` con il messaggio `Target response ended prematurely.`
`abortClientRequest`	Edge Microgateway interrompe la richiesta e viene scritto un avviso nei file di log: `TargetResponseAborted` con il codice di stato della richiesta 502.

Esempio:

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

Attributi headers

Queste impostazioni configurano il modo in cui vengono trattate determinate intestazioni HTTP.

x-forwarded-for: (valore predefinito: true) impostato su false per impedire che le intestazioni x-forwarded-for vengano passate al target. Tieni presente che se nella richiesta è presente un'intestazione x-forwarded-for, il relativo valore verrà impostato sul valore client-ip in Edge Analytics.
x-forwarded-host: (valore predefinito: true) impostato su false per impedire il passaggio delle intestazioni x-forwarded-host al target.
x-request-id: (valore predefinito: true) impostato su false per impedire il passaggio delle intestazioni x-request-id al target.
x-response-time: (valore predefinito: true) impostato su false per impedire che le intestazioni x-response-time vengano trasmesse al target.
via: (valore predefinito: true) impostato su false per impedire il passaggio delle intestazioni via al target.

Attributi OAuth

Queste impostazioni configurano il modo in cui l'autenticazione del client viene applicata da Edge Microgateway.

allowNoAuthorization: (valore predefinito: false) se impostato su true, le chiamate API sono consentite per passare attraverso Edge Microgateway senza alcuna intestazione Authorization. Imposta questo valore su false per richiedere un'intestazione Authorization (valore predefinito).
allowInvalidAuthorization: (valore predefinito: false) se impostato su true, le chiamate all'API sono consentite se il token passato nell'intestazione Authorization non è valido o è scaduto. Imposta questo valore su false per richiedere token validi (valore predefinito).
authorization-header: (valore predefinito: Authorization: Bearer) l'intestazione utilizzata per inviare il token di accesso a Edge Microgateway. Ti consigliamo di modificare il valore predefinito nei casi in cui la destinazione debba utilizzare l'intestazione Authorization per altri scopi.
api-key-header: (valore predefinito: x-api-key) il nome dell'intestazione o del parametro di query utilizzato per passare una chiave API a Edge Microgateway. Consulta anche Utilizzo di una chiave API.
keep-authorization-header: (valore predefinito: false) se impostato su true, l'intestazione Authorization inviata nella richiesta viene trasmessa al target (viene conservata).
allowOAuthOnly: se impostato su true, ogni API deve contenere un'intestazione Authorization con un token di accesso Bearer. Ti consente di consentire solo il modello di sicurezza OAuth (mantenendo la compatibilità con le versioni precedenti). (Aggiunta nella versione 2.4.x)
allowAPIKeyOnly: se impostato su true, ogni API deve contenere un x-api-key intestazione (o una posizione personalizzata) con una chiave API.Consente di consentire solo il modello di sicurezza della chiave API (mantenendo la compatibilità con le versioni precedenti). (Aggiunta 2.4.x)
Non impostare su true sia allowOAuthOnly sia allowAPIKeyOnly. L'impostazione predefinita è che entrambi i flag sono impostati su false (per la compatibilità con le versioni precedenti).
gracePeriod: questo parametro aiuta a evitare errori causati da leggere discrepanze tra l'orologio di sistema e le date e gli orari di emissione (Not Before (nbf) o Issued At (iat)) specificati nel token di autorizzazione JWT. Imposta questo parametro sul numero di secondi da consentire per queste discrepanze. (Aggiunta 2.5.7)

Attributi specifici del plug-in

Consulta Utilizzare i plug-in per informazioni dettagliate sugli attributi configurabili per ciascun plug-in.

Proxy con filtri

Puoi filtrare i proxy compatibili con il microgateway che verranno elaborati da un'istanza Edge Microgateway. Quando Edge Microgateway si avvia, scarica tutti i proxy compatibili con il microgateway nell'organizzazione a cui è associato. Utilizza la seguente configurazione per limitare i proxy che il microgateway elaborerà. Ad esempio, questa configurazione limita a tre i proxy elaborati dal microgateway: edgemicro_proxy-1, edgemicro_proxy-2 e edgemicro_proxy-3:

edgemicro:
  proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

Filtrare i prodotti per nome

Utilizza la seguente configurazione per limitare il numero di prodotti API che Edge Microgateway scarica e elabora. Per filtrare i prodotti scaricati, aggiungi il parametro di query productnamefilter all'API /products elencata nel file *.config.yaml del microgateway Edge. Ad esempio:

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

Tieni presente che il valore del parametro di query deve essere specificato in formato di espressione regolare e deve essere codificato nell'URL. Ad esempio, la regex ^[Ee]dgemicro.*$ acquisisce nomi come: "edgemicro-test-1" , "edgemicro_demo" ed "Edgemicro_New_Demo". Il valore con codifica URL, adatto per essere utilizzato nel parametro di query, è: %5E%5BEe%5Ddgemicro.%2A%24.

Il seguente output di debug mostra che sono stati scaricati solo i prodotti filtrati:

...
2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK
...
....
....
{
   "apiProduct":[
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590549037549,
         "createdBy":"k***@g********m",
         "displayName":"test upper case in name",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590549037549,
         "lastModifiedBy":"k***@g********m",
         "name":"Edgemicro_New_Demo",
         "proxies":[
            "catchall"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590548328998,
         "createdBy":"k***@g********m",
         "displayName":"edgemicro test 1",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590548328998,
         "lastModifiedBy":"k***@g********m",
         "name":"edgemicro-test-1",
         "proxies":[
            "Lets-Encrypt-Validation-DoNotDelete"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[
            "/",
            "/**"
         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1558182193472,
         "createdBy":"m*********@g********m",
         "displayName":"Edge microgateway demo product",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1569077897465,
         "lastModifiedBy":"m*********@g********m",
         "name":"edgemicro_demo",
         "proxies":[
            "edgemicro-auth",
            "edgemicro_hello"
         ],
         "quota":"600",
         "quotaInterval":"1",
         "quotaTimeUnit":"minute",
         "scopes":[

         ]
      }
   ]
}

Filtrare i prodotti per attributi personalizzati

Per filtrare i prodotti in base ad attributi personalizzati:

Nell'interfaccia utente di Edge, seleziona il proxy edgemicro_auth nell'organizzazione/nell'ambiente in cui hai configurato Edge Microgateway.
Nella scheda Sviluppa, apri il criterio JavaCallout nell'editor.
Aggiungi un attributo personalizzato con la chiave products.filter.attributes con un elenco di nomi di attributi separati da virgole. Solo i prodotti che contengono uno dei nomi degli attributi personalizzati verranno restituiti a Edge Microgateway.
Se vuoi, puoi disattivare il controllo per verificare se il prodotto è abilitato per l'ambiente corrente impostando l'attributo personalizzato products.filter.env.enable su false. (il valore predefinito è true).
(Solo cloud privato) Se utilizzi Edge per il cloud privato, imposta la proprietà org.noncps su true per estrarre i prodotti per gli ambienti non CPS.

Ad esempio:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <FaultRules/>
    <Properties>
        <Property name="products.filter.attributes">attrib.one, attrib.two</Property>
        <Property name="products.filter.env.enable">false</Property>
        <Property name="org.noncps">true</Property>
    </Properties>
    <ClassName>io.apigee.microgateway.javacallout.Callout</ClassName>
    <ResourceURL>java://micro-gateway-products-javacallout-2.0.0.jar</ResourceURL>
</JavaCallout>

Filtrare i prodotti in base allo stato di revoca

I prodotti API hanno tre codici di stato: In attesa, Approvato e Revoked. Una nuova proprietà denominata allowProductStatus è stata aggiunta al criterio Imposta variabili JWT nel proxy edgemicro-auth. Per utilizzare questa proprietà per filtrare i prodotti API elencati nel JWT:

Apri il proxy edgemicro-auth nell'editor dei proxy Apigee.

Aggiungi la proprietà allowProductStatus al codice XML del criterio SetJWTVariables e specifica un elenco separato da virgole di codici di stato in base ai quali filtrare. Ad esempio, per filtrare in base agli stati Pending (In attesa) e Revoked (Ritirata):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript timeLimit="20000" async="false" continueOnError="false"
    enabled="true" name="Set-JWT-Variables">
    <DisplayName>Set JWT Variables</DisplayName>
    <FaultRules/>
    <Properties>
        <Property name="allowProductStatus">Pending,Revoked</Property>
    </Properties>
    <ResourceURL>jsc://set-jwt-variables.js</ResourceURL>
</Javascript>

Se vuoi che vengano elencati solo i prodotti Approvati, imposta la proprietà come segue:

<Property name="allowProductStatus">Approved</Property>

Salva il proxy.
Se il tag Property non è presente, nel JWT verranno elencati i prodotti con tutti i codici di stato.

Per utilizzare questa nuova proprietà, devi eseguire l'upgrade del proxy edgemicro-auth.

Configurare la frequenza di push dei dati di analisi

Utilizza questi parametri di configurazione per controllare la frequenza con cui Edge Microgateway invia i dati di analisi ad Apigee:

bufferSize (facoltativo): il numero massimo di record di analisi che il buffer può contenere prima di iniziare a eliminare i record più vecchi. Valore predefinito: 10000
batchSize (facoltativo): la dimensione massima di un batch di record di analisi inviati ad Apigee. Valore predefinito: 500
flushInterval (facoltativo): il numero di millisecondi tra ogni svuotamento di un batch di record di analisi inviati ad Apigee. Valore predefinito: 5000

Ad esempio:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Mascheramento dei dati di analisi

La seguente configurazione impedisce la visualizzazione delle informazioni sul percorso della richiesta in Edge Analytics. Aggiungi quanto segue alla configurazione del microgateway per mascherare l'URI e/o il percorso della richiesta. Tieni presente che l'URI è costituito dalle parti del nome host e del percorso della richiesta.

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

Separazione delle chiamate API in Edge Analytics

Puoi configurare il plug-in di analisi in modo da separare un percorso API specifico in modo che venga visualizzato come un proxy separato nelle dashboard di Edge Analytics. Ad esempio, puoi separare un'API di controllo di integrità nella dashboard per evitare di confonderla con le chiamate proxy dell'API effettive. Nella dashboard di Analytics, i proxy segregati seguono questo modello di denominazione:

edgemicro_proxyname-health

L'immagine seguente mostra due proxy segregati nella dashboard di Analytics: edgemicro_hello-health e edgemicro_mock-health:

Utilizza questi parametri per separare i percorsi relativi e assoluti nella dashboard di Analytics come proxy separati:

relativePath (facoltativo): specifica un percorso relativo da separare nella dashboard di Analytics. Ad esempio, se specifichi /healthcheck, tutte le chiamate API che contengono il percorso /healthcheck verranno visualizzate nella dashboard come edgemicro_proxyname-health. Tieni presente che questo flag ignora il percorso base del proxy. Per eseguire la segregazione in base a un percorso completo, incluso il percorso base, utilizza il flag proxyPath.
proxyPath (facoltativo): specifica un percorso completo del proxy dell'API, incluso il percorso di base del proxy, da separare nella dashboard di analisi. Ad esempio, se specifichi /mocktarget/healthcheck, dove /mocktarget è il percorso di base del proxy, tutte le chiamate API con il percorso /mocktarget/healthcheck verranno visualizzate nella dashboard come edgemicro_proxyname-health.

Ad esempio, nella configurazione seguente, qualsiasi percorso dell'API contenente /healthcheck verrà distinto dal plug-in di analisi. Ciò significa che /foo/healthcheck e /foo/bar/healthcheck verranno separati come proxy separato denominato edgemicro_proxyname-health nella dashboard di analisi.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  relativePath: /healthcheck

Nella configurazione seguente, qualsiasi API con il percorso del proxy /mocktarget/healthcheck verrà distinta come proxy separato denominato edgemicro_proxyname-health nella dashboard di Dati.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  proxyPath: /mocktarget/healthcheck

Configurazione di Edge Microgateway dietro un firewall aziendale

Utilizzare un proxy HTTP per la comunicazione con Apigee Edge

Aggiunta nella versione 3.1.2.

Per utilizzare un proxy HTTP per la comunicazione tra Edge Microgateway e Apigee Edge:

Imposta le variabili di ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY. Queste variabili controllano gli host di ogni proxy HTTP che vuoi utilizzare per la comunicazione con Apigee Edge o gli host che non devono gestire la comunicazione con Apigee Edge. Ad esempio:
```
export HTTP_PROXY='http://localhost:3786'
export HTTPS_PROXY='https://localhost:3786'
export NO_PROXY='localhost,localhost:8080'
```
Tieni presente che NO_PROXY può essere un elenco di domini separati da virgole per i quali Edge Microgateway non deve eseguire il proxy.

Per ulteriori informazioni su queste variabili, consulta https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables
Riavvia Edge Microgateway.

Utilizzare un proxy HTTP per la comunicazione con la destinazione

Aggiunta nella versione 3.1.2.

Per utilizzare un proxy HTTP per la comunicazione tra Edge Microgateway e i target di backend: segui questi passaggi:

Aggiungi la seguente configurazione al file di configurazione del microgateway:
```
edgemicro:
  proxy:
    tunnel: true | false
    url: proxy_url
    bypass: target_host # target hosts to bypass the proxy.
    enabled: true | false
```
Dove:
- tunnel: (facoltativo) se true, Edge Microgateway utilizza il metodo CONNECT HTTP per eseguire il tunneling delle richieste HTTP su una singola connessione TCP. Lo stesso vale se le variabili di ambiente, come indicato di seguito, per la configurazione del proxy sono abilitate per TLS. Valore predefinito: false
- url: l'URL del proxy HTTP.
- bypass: (Facoltativo) specifica uno o più URL host target separati da virgole che devono ignorare il proxy HTTP. Se questa proprietà non è impostata, utilizza la variabile di ambiente NO_PROXY per specificare quali URL target ignorare.
- enabled: se è True e proxy.url è impostato, utilizza il valore proxy.url per il proxy HTTP. Se il valore è true e proxy.url non è impostato, utilizza i proxy specificati nelle variabili di ambiente proxy HTTP HTTP_PROXY e HTTPS_PROXY, come descritto in Utilizzare un proxy HTTP per la comunicazione con Apigee Edge.
Ad esempio:
```
edgemicro:
  proxy:
    tunnel: true
    url: 'http://localhost:3786'
    bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy.
    enabled: true
```
NOTA: se edgemicro.proxy viene omesso dal file di configurazione o se edgemicro.proxy.enabled è false, Edge Microgateway non utilizzerà un proxy HTTP per la comunicazione con il target.
Riavvia Edge Microgateway.

Utilizzo di caratteri jolly nei proxy consapevoli di Microgateway

Puoi utilizzare uno o più caratteri jolly "*" nel percorso di base di un proxy edgemicro_* (compatibile con Microgateway). Ad esempio, un percorso di base di /team/*/members consente ai client di chiamare https://[host]/team/blue/members e https://[host]/team/green/members senza che tu debba creare nuovi proxy API per supportare i nuovi team. Tieni presente che /**/ non è supportato.

Importante:Apigee NON supporta l'utilizzo di un carattere jolly "*" come primo elemento di un percorso di base. Ad esempio, NON è supportata la ricerca di /*/.

Rotazione delle chiavi JWT

In che modo Edge Microgateway utilizza i JWT

Il token web JSON (JWT) è uno standard di token descritto in RFC7519. JWT fornisce un modo per firmare un insieme di attestazioni, che possono essere verificate in modo affidabile dal destinatario del JWT.

Puoi generare un JWT utilizzando la CLI e utilizzarlo nell'header Authorization delle chiamate API anziché una chiave API. Ad esempio:

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

Per informazioni sulla generazione di JWT con l'interfaccia a riga di comando, consulta Generare un token.

Che cos'è la rotazione delle chiavi?

Dopo aver generato inizialmente un JWT, potrebbe essere necessario modificare la coppia di chiavi pubblica/privata memorizzata nella KVM criptata Edge. Questa procedura di generazione di una nuova coppia di chiavi è chiamata rotazione delle chiavi. Quando ruoti le chiavi, viene generata e memorizzata una nuova coppia di chiavi privata/pubblica nel KVM "microgateway" nell'organizzazione/nell'ambiente Apigee Edge. Inoltre, la vecchia chiave pubblica viene conservata insieme al relativo valore ID chiave originale.

Per generare un JWT, Edge utilizza le informazioni memorizzate nella KVM criptata. Un VM KVM denominato microgatewayè stato creato e compilato con le chiavi durante la configurazione iniziale (configurazione) del microgateway Edge. Le chiavi nella KVM vengono utilizzate per firmare e criptare un JWT.

Le chiavi KVM includono:

private_key: la chiave privata RSA più recente (creata più di recente) utilizzata per firmare i JWT.
public_key: il certificato più recente (creato più di recente) utilizzato per verificare i JWT firmati con la chiave privata.
private_key_kid: l'ID chiave privata più recente (creato più di recente). Questo ID chiave è associato al valore private_key e viene utilizzato per supportare la rotazione delle chiavi.
public_key1_kid: l'ID chiave pubblica più recente (creato più di recente). Questa chiave è associata al valore public_key1 e viene utilizzata per supportare la rotazione delle chiavi. Questo valore corrisponde al kid della chiave privata.
public_key1: la chiave pubblica più recente (creata più di recente).

Quando esegui la rotazione delle chiavi, i valori delle chiavi esistenti vengono sostituiti nella mappa e vengono aggiunte nuove chiavi per conservare le vecchie chiavi pubbliche. Ad esempio:

public_key2_kid: il vecchio ID chiave pubblica. Questa chiave è associata al valore public_key2 e viene utilizzata per supportare la rotazione delle chiavi.
public_key2: la vecchia chiave pubblica.

I JWT presentati per la verifica verranno verificati utilizzando la nuova chiave pubblica. Se la verifica non va a buon fine, verrà utilizzata la vecchia chiave pubblica fino alla scadenza del JWT (dopo l'intervallo token_expiry*, predefinito 30 minuti). In questo modo, puoi "ruotare" le chiavi senza interrompere immediatamente il traffico dell'API.

Come eseguire la rotazione delle chiavi

Questa sezione spiega come eseguire una rotazione delle chiavi.

Per eseguire l'upgrade del KVM, utilizza il comando edgemicro upgradekvm. Per maggiori dettagli sull'esecuzione di questo comando, vedi Eseguire l'upgrade del KVM. Dovrai eseguire questo passaggio una sola volta.
Per eseguire l'upgrade del proxy edgemicro-oauth, utilizza il comando edgemicro upgradeauth. Per informazioni dettagliate sull'esecuzione di questo comando, consulta Eseguire l'upgrade del proxy edgemicro-auth. Dovrai eseguire questo passaggio una sola volta.
Aggiungi la riga seguente al file ~/.edgemicro/org-env-config.yaml, in cui devi specificare la stessa organizzazione e lo stesso ambiente per cui hai configurato il microgateway:
```
jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'
```

Esegui il comando di rotazione delle chiavi per ruotarle. Per maggiori dettagli su questo comando, consulta Gestire le chiavi.

edgemicro rotatekey -o $ORG -e $ENV -k $KEY -s $SECRET

Ad esempio:

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47

Dopo la rotazione delle chiavi, Edge restituisce più chiavi a Edge Microgateway. Nota che nel seguente esempio, ogni chiave ha un valore "kid" (ID chiave) univoco. Il microgateway utilizza quindi queste chiavi per convalidare i token di autorizzazione. Se la convalida del token non riesce, il microgateway cerca di vedere se è presente una chiave precedente nell'insieme di chiavi e la prova. Il formato delle chiavi restituite è JSON Web Key (JWK). Puoi leggere informazioni su questo formato nella RFC 7517.

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

Configurazione di un ritardo "non prima del"

Per le versioni 3.1.5 e precedenti, la nuova chiave privata generata dal comando rotatekey è stata applicata immediatamente e i nuovi token generati sono stati firmati con la nuova chiave privata. Tuttavia, la nuova chiave pubblica veniva resa disponibile alle istanze Edge Microgateway solo ogni 10 minuti (per impostazione predefinita) quando la configurazione del microgateway veniva aggiornata. A causa di questo ritardo tra la firma del token e l'aggiornamento dell'istanza del microgateway, i token firmati con la chiave più recente verranno rifiutati fino a quando tutte le istanze non avranno ricevuto la chiave pubblica più recente.

Nei casi in cui esistono più istanze di microgateway, il ritardo della chiave pubblica a volte ha provocato errori di runtime intermittenti con stato 403, perché la convalida del token andava a buon fine in un'istanza, ma non in un'altra finché non venivano aggiornate tutte le istanze.

A partire dalla versione 3.1.6, un nuovo flag del comando rotatekey consente di specificare un ritardo per l'applicazione della nuova chiave privata, in modo da consentire l'aggiornamento di tutte le istanze del microgateway e la ricezione della nuova chiave pubblica. Il nuovo flag è --nbf, che significa "non prima". Questo flag accetta un valore intero, il numero di minuti di ritardo.

Nell'esempio seguente, il ritardo è impostato su 15 minuti:

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \
--nbf 15

Tieni presente che è buona norma impostare un ritardo superiore all'impostazione di configurazione config_change_poll_internal, che è 10 minuti per impostazione predefinita. Vedi anche gli attributi edgemicro.

Filtrare i proxy scaricati

Per impostazione predefinita, Edge Microgateway scarica tutti i proxy nell'organizzazione Edge che iniziano con il prefisso di denominazione "edgemicro_". Puoi modificare questa impostazione predefinita per scaricare i proxy cuyos nomi corrispondono a un pattern.

Apri il file di configurazione di Edge Micro: ~/.edgemicro/org-env-config.yaml
Aggiungi l'elemento proxyPattern in edge_config. Ad esempio, il seguente pattern consentirà di scaricare proxy come edgemicro_foo, edgemicro_fast ed edgemicro_first.
```
edge_config:
…
proxyPattern: edgemicro_f*
```

Specificare i prodotti senza proxy API

In Apigee Edge, puoi creare un prodotto API che non contiene proxy API. Questa configurazione del prodotto consente a una chiave API associata al prodotto di funzionare con qualsiasi proxy di cui è stato eseguito il deployment nella tua organizzazione. A partire dalla versione 2.5.4, Edge Microgateway supporta questa configurazione del prodotto.

Debug e risoluzione dei problemi

Connessione a un debugger

Puoi eseguire Edge Microgateway con un debugger, ad esempio node-inspector. Questo è utile per la risoluzione dei problemi e il debug dei plug-in personalizzati.

Riavvia Edge Microgateway in modalità di debug. Per farlo, aggiungi DEBUG=* all'inizio del comando start:
```
DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET
```
NOTA: su Windows, utilizza SET DEBUG=*

Per indirizzare l'output di debug a un file, puoi utilizzare questo comando:
```
export DEBUG=* nohup edgemicro start \
-o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log
```
Avvia il debugger e impostalo in modo che ascolti sul numero di porta per la procedura di debug.
Ora puoi eseguire il codice di Edge Microgateway, impostare i punti di interruzione, monitorare le espressioni e così via.

Puoi specificare flag Node.js standard relativi alla modalità di debug. Ad esempio, --nolazy aiuta a eseguire il debug del codice asincrono.

Controllo dei file di log

Se riscontri problemi, assicurati di esaminare i file di log per i dettagli di esecuzione e le informazioni sugli errori. Per maggiori dettagli, vedi Gestire i file di log.

Utilizzo della sicurezza delle chiavi API

Le chiavi API forniscono un semplice meccanismo per autenticare i client che inviano richieste all'Edge Microgateway. Puoi ottenere una chiave API copiando il valore della chiave consumer (chiamato anche ID client) da un prodotto Apigee Edge che include il proxy di autenticazione del microgateway Edge.

Memorizzazione nella cache delle chiavi

Le chiavi API vengono scambiate per token di accesso, che vengono memorizzati nella cache. Puoi disattivare la memorizzazione nella cache impostando l'intestazione Cache-Control: no-cache sulle richieste in arrivo all'Edge Microgateway.

Utilizzo di una chiave API

Puoi passare la chiave API in una richiesta API come parametro di query o in un'intestazione. Per impostazione predefinita, il nome dell'intestazione e del parametro di query sono entrambi x-api-key.

Esempio di parametro di query:

curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz

Esempio di titoli:

curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Configurazione del nome della chiave API

Per impostazione predefinita, x-api-key è il nome utilizzato sia per l'intestazione della chiave API sia per il parametro di query. Puoi modificare questo valore predefinito nel file di configurazione, come spiegato in Apportare modifiche alla configurazione. Ad esempio, per modificare il nome in apiKey:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  api-key-header: apiKey

In questo esempio, sia il parametro di query sia il nome dell'intestazione vengono modificati in apiKey. Il nome x-api-key non funzionerà più in nessuno dei due casi. Consulta anche Apportare modifiche alla configurazione.

Ad esempio:

curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Per scoprire di più sull'utilizzo delle chiavi API con le richieste proxy, consulta Secure Edge Microgateway.

Attivare i codici di risposta a monte

Per impostazione predefinita, il plug-in oauth restituisce solo codici di stato di errore 4xx se la risposta non è uno stato 200. Puoi modificare questo comportamento in modo che restituisca sempre il codice 4xx o 5xx esatto, a seconda dell'errore.

Per attivare questa funzionalità, aggiungi la proprietà oauth.useUpstreamResponse: true alla configurazione di Edge Microgateway. Ad esempio:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  gracePeriod: 10
  useUpstreamResponse: true

Utilizzo della sicurezza dei token OAuth2

Questa sezione spiega come ottenere token di accesso e token di aggiornamento OAuth2. I token di accesso vengono utilizzati per effettuare chiamate API sicure tramite il microgateway. I token di aggiornamento vengono utilizzati per ottenere nuovi token di accesso.

Come ottenere un token di accesso

Questa sezione spiega come utilizzare il proxy edgemicro-auth per ottenere un token di accesso.

Puoi anche ottenere un token di accesso utilizzando il comando edgemicro token CLI. Per informazioni dettagliate sulla CLI, vedi Gestire i token.

API 1: invia le credenziali come parametri del corpo

Sostituisci i nomi dell'organizzazione e dell'ambiente nell'URL e sostituisci i valori Consumer-ID e Consumer-Secret ottenuti da un'app per sviluppatori su Apigee Edge per i parametri del corpo client_id e client_secret:

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2: invia le credenziali in un'intestazione di autenticazione di base

Invia le credenziali del client come intestazione di autenticazione di base e grant_type come parametro del modulo. Questo formato del comando è descritto anche nel RFC 6749: The OAuth 2.0 Authorization Framework.

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

Esempio di output

L'API restituisce una risposta JSON. Tieni presente che non c'è differenza tra le proprietà token e access_token. Puoi utilizzare uno dei due. Tieni presente che expires_in è un valore intero specificato in secondi.

{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": 1799
}

Come ottenere un token di aggiornamento

Per ottenere un token di aggiornamento, effettua una chiamata API all'endpoint /token del proxy edgemicro-auth. DEVI effettuare questa chiamata API con il tipo di autorizzazione password. I passaggi che seguono illustrano la procedura.

Ottieni un token di accesso e di aggiornamento con l'API /token. Tieni presente che il tipo di autorizzazione è password:

curl -X POST \
  https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
  -H 'Content-Type: application/json' \
  -d '{
   "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
   "client_secret":"bUdDcFgv3nXffnU",
   "grant_type":"password",
   "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
   "password":"bUdD2FvnMsXffnU"
}'

L'API restituisce un token di accesso e un token di aggiornamento. La risposta sarà simile a questa. Tieni presente che i valori expires_in sono numeri interi e sono specificati in secondi.

{
    "token": "your-access-token",
    "access_token": "your-access-token",
    "token_type": "bearer",
    "expires_in": 108,
    "refresh_token": "your-refresh-token",
    "refresh_token_expires_in": 431,
    "refresh_token_issued_at": "1562087304302",
    "refresh_token_status": "approved"
}

Ora puoi utilizzare il token di aggiornamento per ottenere un nuovo token di accesso chiamando l'endpoint /refresh della stessa API. Ad esempio:

curl -X POST \
  https://willwitman-test.apigee.net/edgemicro-auth/refresh \
  -H 'Content-Type: application/json' \
  -d '{
   "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
   "client_secret":"bUdDc2Fv3nMXffnU",
   "grant_type":"refresh_token",
   "refresh_token":"your-refresh-token"
}'

L'API restituisce un nuovo token di accesso. La risposta sarà simile alla seguente:

{
    "token": "your-new-access-token"
    }

Monitoraggio permanente

Forever è uno strumento Node.js che riavvia automaticamente un'app Node.js nel caso in cui il processo si arresti o presenti un errore. Edge Microgateway ha un file forever.json che puoi configurare per controllare quante volte e con quali intervalli deve essere riavviato. Questo file configura un servizio Forever chiamato forever-monitor, che gestisce Forever in modo programmatico.

Puoi trovare il file forever.json nella directory di installazione radice di Edge Microgateway. Consulta Dove è installato Edge Microgateway. Per informazioni dettagliate sulle opzioni di configurazione, consulta la documentazione di forever-monitor.

Il comando edgemicro forever include flag che consentono di specificare la posizione del file forever.json (flag -f) e di avviare/arrestare il processo di monitoraggio Forever (flag -a). Ad esempio:

edgemicro forever -f ~/mydir/forever.json -a start

Per ulteriori informazioni, consulta la sezione Monitoraggio continuo nella documentazione di riferimento della CLI.

Specifica di un endpoint del file di configurazione

Se esegui più istanze di Edge Microgateway, ti consigliamo di gestire le relative configurazioni da un'unica posizione. A tal fine, specifica un endpoint HTTP in cui Edge Micro può scaricare il file di configurazione. Puoi specificare questo endpoint quando avvii Edge Micro utilizzando il flag -u.

Ad esempio:

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

dove l'endpoint mgconfig restituisce i contenuti del file di configurazione. Si tratta del file che, per impostazione predefinita, si trova in ~/.edgemicro e ha la convenzione di denominazione: org-env-config.yaml.

Disattivazione del buffering dei dati della connessione TCP

Puoi utilizzare l'attributo di configurazione nodelay per disattivare il buffering dei dati per le connessioni TCP utilizzate da Edge Microgateway.

Per impostazione predefinita, le connessioni TCP utilizzano l'algoritmo Nagle per mettere in buffer i dati prima di inviarli. Se imposti nodelay su true, questo comportamento viene disattivato (i dati verranno inviati immediatamente ogni volta che viene chiamato socket.write()). Per ulteriori dettagli, consulta anche la documentazione di Node.js.

Per attivare nodelay, modifica il file di configurazione di Edge Micro come segue:

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Eseguire Edge Microgateway in modalità autonoma

Puoi eseguire Edge Microgateway completamente scollegato da qualsiasi dipendenza Apigee Edge. Questo scenario, chiamato modalità autonoma, ti consente di eseguire e testare Edge Microgateway senza una connessione a internet.

In modalità autonoma, le seguenti funzionalità non funzionano perché richiedono la connessione ad Apigee Edge:

OAuth e chiave API
Quota
Analytics

I plug-in personalizzati e l'arresto degli picchi, invece, funzionano normalmente perché non richiedono una connessione ad Apigee Edge. Inoltre, un nuovo plug-in chiamato extauth ti consente di autorizzare le chiamate API al microgateway con un JWT in modalità autonoma.

Configurazione e avvio del gateway

Per eseguire Edge Microgateway in modalità autonoma:

Crea un file di configurazione denominato come segue: $HOME/.edgemicro/$ORG-$ENV-config.yaml
Puoi utilizzare qualsiasi valore per $ORG e $ENV nel nome del file. La combinazione org/env è semplicemente una convenzione che consente a Edge Microgateway di trovare il file al suo avvio.

Ad esempio:
```
vi $HOME/.edgemicro/foo-bar-config.yaml
```
Incolla il seguente codice nel file:
```
edgemicro:
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - extauth
      - spikearrest
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
extauth:
  publickey_url: https://www.googleapis.com/oauth2/v1/certs
spikearrest:
  timeUnit: second
  allow: 10
  buffersize: 0
```
Il file di configurazione contiene un plug-in facoltativo speciale chiamato extauth. Questo plug-in verifica un token JWT valido passato al microgateway. In un passaggio successivo, scoprirai come ottenere e utilizzare il token. Tieni inoltre presente che il plug-in spikearrest è incluso perché non si basa sulla connettività con Edge. I plug-in quota, oauth e analytics sono esclusi perché si basano sulla connettività con Edge e non funzioneranno in modalità disconnessa. I plug-in personalizzati sono consentiti e funzioneranno come previsto.
Esporta la seguente variabile di ambiente con il valore "1":
```
export EDGEMICRO_LOCAL=1
```
Esegui il seguente comando start, in cui fornisci i valori per l'inizializzazione del proxy locale:
```
edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
  -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH
```
Dove:
- $ORG è il nome "org" utilizzato nel nome del file di configurazione.
- $ENV è il nome "env" utilizzato nel nome del file di configurazione.
- $LOCAL_PROXY_NAME è il nome del proxy locale che verrà creato. Puoi utilizzare qualsiasi nome.
- $LOCAL_PROXY_VERSION è il numero di versione del proxy.
- $TARGET_URL è l'URL del target del proxy. Il target è il servizio chiamato dal proxy.
- $BASE_PATH è il percorso di base del proxy. Questo valore deve iniziare con una barra. Per un percorso base principale, specifica solo una barra, ad esempio "/".
Ad esempio:
```
edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
```
Testa la configurazione.
```
curl http://localhost:8000/echo  { "error" : "missing_authorization" }
```
Poiché il plug-in extauth si trova nel file foo-bar-config.yaml, viene visualizzato un errore "missing_authorization". Questo plug-in convalida un JWT che deve essere presente nell'intestazione Authorization della chiamata API. Nella sezione successiva otterrai un JWT che consentirà alle chiamate API di essere eseguite senza errori.

Esempio: ottengo un token di autorizzazione

L'esempio seguente mostra come ottenere un JWT dall'endpoint JWT di Edge Microgateway su Apigee Edge (edgemicro-auth/jwkPublicKeys). Questo endpoint viene implementato quando esegui una configurazione e impostazione standard di Edge Microgateway. Per ottenere il JWT dall'endpoint Apigee, devi prima eseguire la configurazione standard di Edge Microgateway e essere connesso a internet. L'endpoint Apigee viene utilizzato qui solo come esempio e non è obbligatorio. Se vuoi, puoi utilizzare un altro endpoint del token JWT. In questo caso, dovrai ottenere il JWT utilizzando l'API fornita per quell'endpoint.

L'inclusione del plug-in extauth nella configurazione del microgateway è facoltativa, ma se lo includi, dovrai fornire un token JWT valido nell'intestazione Authorization per le chiamate API.

I passaggi riportati di seguito spiegano come ottenere un token utilizzando l'endpoint edgemicro-auth/jwkPublicKeys:

Per eseguire il deployment del proxy edgemicro-auth nella tua organizzazione/nel tuo ambiente su Apigee Edge, devi eseguire una configurazione e un'impostazione standard di Edge Microgateway. Se hai già eseguito questo passaggio, non devi ripeterlo.
Se hai implementato Edge Microgateway in Apigee Cloud, devi essere connesso a internet per poter ottenere un JWT da questo endpoint.
Interrompi il microgateway Edge:
```
edgemicro stop
```
Nel file di configurazione creato in precedenza ($HOME/.edgemicro/org-env-config.yaml), indirizza l'attributo extauth:publickey_url all'endpoint edgemicro-auth/jwkPublicKeys nell'organizzazione/nell'ambiente Apigee Edge. Ad esempio:
```
extauth:
  publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
```
Riavvia Edge Microgateway come hai fatto in precedenza, utilizzando i nomi org/env che hai utilizzato nel nome del file di configurazione. Ad esempio:
```
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
```
Recupera un token JWT dall'endpoint di autorizzazione. Poiché utilizzi l'endpoint edgemicro-auth/jwkPublicKeys puoi utilizzare questo comando CLI:
Per questo passaggio, è necessaria una connessione a internet. Il seguente comando recupera un token da Apigee Edge. Per eseguire questo passaggio, devi disporre di un'organizzazione Apigee in cui hai eseguito la configurazione e l'impostazione di un microgateway Edge standard. Dopo aver eseguito questo passaggio, non è necessaria la connessione a internet. Il token continuerà a funzionare in modalità autonoma fino alla scadenza.

Puoi generare un JWT per Edge Microgateway utilizzando il comando edgemicro token o un'API. Ad esempio:

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Dove:

your_org è il nome della tua organizzazione Apigee per la quale hai configurato in precedenza Edge Microgateway.
your_env è un ambiente dell'organizzazione.
L'opzione i specifica la Consumer Key di un'app per sviluppatori che ha un prodotto che include il proxy edgemicro-auth.
L'opzione s specifica il secret consumer di un'app per sviluppatori che ha un prodotto che include il proxy edgemicro-auth.

Questo comando chiede ad Apigee Edge di generare un JWT che può essere utilizzato per verificare le chiamate API.

Vedi anche Generare un token.

Testa la configurazione autonoma

Per testare la configurazione, chiama l'API con il token aggiunto nell'intestazione Authorization come segue:

curl http://localhost:8000/echo -H "Authorization: Bearer your_token

Esempio:

curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"

Output di esempio:

{
   "headers":{
      "user-agent":"curl/7.54.0",
      "accept":"*/*",
      "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
      "client_received_start_timestamp":"1535134472699",
      "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==",
      "target_sent_start_timestamp":"1535134472702",
      "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
      "x-forwarded-proto":"http",
      "x-forwarded-host":"localhost:8000",
      "host":"mocktarget.apigee.net",
      "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
      "via":"1.1 localhost, 1.1 google",
      "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
      "connection":"Keep-Alive"
   },
   "method":"GET",
   "url":"/",
   "body":""
}

Utilizzo della modalità proxy locale

In modalità proxy locale, Edge Microgateway non richiede un proxy consapevole del microgateway da eseguire su Apigee Edge. Devi invece configurare un "proxy locale" fornendo un nome, un percorso di base e un URL di destinazione del proxy locale quando avvii il microgateway. Le chiamate API al microgateway vengono quindi inviate all'URL di destinazione del proxy locale. Per tutti gli altri aspetti, la modalità proxy locale funziona esattamente come l'esecuzione di Edge Microgateway nella modalità normale. L'autenticazione funziona allo stesso modo, così come l'arresto di picchi e l'applicazione delle quote, i plug-in personalizzati e così via.

Le due differenze importanti tra la modalità locale e la configurazione normale del microgateway Edge sono: (1) in modalità locale, non è necessario creare un proxy consapevole del microgateway su Apigee Edge e (2) quando crei un prodotto API su Edge, devi aggiungere un solo proxy, il proxy edgemicro-auth. Non è necessario aggiungere altri proxy al prodotto.

Caso d'uso ed esempio

La modalità proxy locale è utile quando devi associare un solo proxy a un'istanza di Edge Microgateway. Ad esempio, puoi iniettare Edge Microgateway in Kubernetes come proxy sidecar, in cui un microgateway e un servizio vengono eseguiti ciascuno in un singolo pod e il microgateway gestisce il traffico verso e dal servizio complementare. La figura seguente illustra questa architettura in cui Edge Microgateway funge da proxy sidecar in un cluster Kubernetes. Ogni istanza di microgateway si rivolge solo a un singolo endpoint del servizio complementare:

Edgemicro come sidecar

Un vantaggio di questo tipo di architettura è che Edge Microgateway fornisce la gestione delle API per i singoli servizi di cui è stato eseguito il deployment in un ambiente di container, ad esempio un cluster Kubernetes.

Configurazione della modalità proxy locale

Per configurare Edge Microgateway in modo che venga eseguito in modalità proxy locale:

Esegui edgemicro init per configurare l'ambiente di configurazione locale, esattamente come faresti in una configurazione tipica di Edge Microgateway. Consulta anche Configurare il microgateway Edge.
Esegui edgemicro configure, come faresti in una procedura di configurazione tipica di Edge Microgateway. Ad esempio:
```
edgemicro configure -o your_org -e your_env -u your_apigee_username
```
Questo comando esegue il deployment del criterio edgemicro-auth in Edge e restituisce una chiave e un segreto necessari per avviare il microgateway. Se hai bisogno di aiuto, consulta Configurare Edge Microgateway.
In Apigee Edge, crea un prodotto API con i seguenti requisiti di configurazione obbligatori (puoi gestire tutte le altre configurazioni come preferisci):
- Devi aggiungere il proxy edgemicro-auth al prodotto. Questo proxy è stato implementato automaticamente quando hai eseguito edgemicro configure.
- Devi fornire un percorso della risorsa. Apigee consiglia di aggiungere questo percorso al prodotto: /**. Per saperne di più, consulta Configurare il comportamento del percorso della risorsa. Consulta anche Creare prodotti API nella documentazione di Edge.
In Apigee Edge, crea uno sviluppatore o, se vuoi, utilizzane uno esistente. Per assistenza, consulta Aggiungere sviluppatori utilizzando l'interfaccia utente di gestione di Edge.
In Apigee Edge, crea un'app per sviluppatori. Devi aggiungere all'app il prodotto API appena creato. Per assistenza, consulta Registrare un'app nell'interfaccia utente di gestione di Edge.
Sulla macchina in cui è installato Edge Microgateway, esporta la seguente variabile di ambiente con il valore "1".
```
export EDGEMICRO_LOCAL_PROXY=1
```
Esegui questo comando start:
```
edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
    -a local_proxy_name -v local_proxy_version -t target_url -b base_path
```
Dove:
- your_org è la tua organizzazione Apigee.
- your_environment è un ambiente della tua organizzazione.
- your_key è la chiave restituita quando hai eseguito edgemicro configure.
- your_secret è il secret restituito quando hai eseguito edgemicro configure.
- local_proxy_name è il nome del proxy locale che verrà creato.
- local_proxy_version è il numero di versione del proxy.
- target_url è l'URL della destinazione del proxy (il servizio che il proxy chiamerà).
- base_path è il percorso di base del proxy. Questo valore deve iniziare con una barra. Per un percorso base principale, specifica solo una barra, ad esempio "/".
Ad esempio:
```
edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
  -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
  -t http://mocktarget.apigee.net -b /echo
```

Testare la configurazione

Puoi testare la configurazione del proxy locale chiamando l'endpoint del proxy. Ad esempio, se hai specificato un percorso base /echo, puoi chiamare il proxy come segue:

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

Questa chiamata API iniziale ha generato un errore perché non hai fornito una chiave API valida. Puoi trovare la chiave nell'app per sviluppatori che hai creato in precedenza. Apri l'app nell'interfaccia utente di Edge, copia la chiave consumer e utilizzala come segue:

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

Ad esempio:

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

Output di esempio:

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}

Utilizzare il sincronizzatore

Questa sezione spiega come utilizzare il sincronizzatore, una funzionalità facoltativa che migliora la resilienza di Edge Microgateway consentendogli di recuperare i dati di configurazione da Apigee Edge e di scriverli in un database Redis locale. Con un'istanza di sincronizzazione in esecuzione, altre istanze di Edge Microgateway in esecuzione su nodi diversi possono recuperare la propria configurazione direttamente da questo database.

Al momento la funzionalità di sincronizzazione è supportata per Redis 5.0.x.

Che cos'è il sincronizzatore?

Il sincronizzatore fornisce un livello di resilienza per Edge Microgateway. Contribuisce a garantire che ogni istanza di Edge Microgateway utilizzi la stessa configurazione e che in caso di interruzione di internet, le istanze di Edge Microgateway possano avviarsi e funzionare correttamente.

Per impostazione predefinita, le istanze Edge Microgateway devono essere in grado di comunicare con Apigee Edge per recuperare e aggiornare i dati di configurazione, ad esempio i proxy API e le configurazioni dei prodotti API. Se la connessione a internet con Edge viene interrotta, le istanze del microgateway possono continuare a funzionare perché i dati di configurazione più recenti vengono memorizzati nella cache. Tuttavia, le nuove istanze di microgateway non possono essere avviate senza una connessione chiara. Inoltre, è possibile che un'interruzione di internet provochi l'esecuzione di una o più istanze di microgateway con informazioni di configurazione non sincronizzate con le altre istanze.

Il sincronizzatore di Edge Microgateway fornisce un meccanismo alternativo per le istanze di Edge Microgateway per recuperare i dati di configurazione necessari per avviare ed elaborare il traffico del proxy API. I dati di configurazione recuperati dalle chiamate ad Apigee Edge includono: la chiamata jwk_public_keys, la chiamata jwt_public_key, la chiamata di bootstrap e la chiamata ai prodotti API. Il sincronizzatore consente a tutte le istanze di Edge Microgateway in esecuzione su nodi diversi di avviarsi correttamente e rimanere sincronizzate anche se la connessione a internet tra Edge Microgateway e Apigee Edge viene interrotta.

Il sincronizzatore è un'istanza di Edge Microgateway configurata in modo speciale. Il suo unico scopo è eseguire il polling di Apigee Edge (la tempistica è configurabile), recuperare i dati di configurazione e scriverli in un database Redis locale. L'istanza di sincronizzazione stessa non può elaborare il traffico del proxy API. Altre istanze di Edge Microgateway in esecuzione su nodi diversi possono essere configurate per recuperare i dati di configurazione dal database Redis anziché da Apigee Edge. Poiché tutte le istanze di microgateway estraggono i dati di configurazione dal database locale, possono avviarsi ed elaborare le richieste API anche in caso di interruzione dell'accesso a internet.

Configurazione di un'istanza di sincronizzazione

Aggiungi la seguente configurazione al file org-env/config.yaml per l'installazione di Edge Microgateway che vuoi utilizzare come sincronizzatore:

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Ad esempio:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Opzione	Descrizione
`redisHost`	L'host in cui è in esecuzione l'istanza Redis. Valore predefinito: 127.0.0.1
`redisPort`	La porta dell'istanza Redis. Valore predefinito: 6379
`redisDb`	Il database Redis da utilizzare. Valore predefinito: 0
`redisPassword`	La password del database.

Puoi utilizzare la variabile di ambiente EDGEMICRO_REDIS_PASSWORD per sostituire il parametro edgemicro.redisPassword. Consulta anche Impostazione degli attributi di configurazione con i valori delle variabili di ambiente.

Infine, salva il file di configurazione e avvia l'istanza Edge Microgateway. Inizierà a eseguire il polling di Apigee Edge e a memorizzare i dati di configurazione scaricati nel database Redis.

Configurazione di istanze Edge Microgateway regolari

Con il sincronizzatore in esecuzione, puoi configurare altri nodi Edge Microgateway per eseguire istanze di microgateway regolari che elaborano il traffico del proxy API. Tuttavia, queste istanze vengono configurate in modo da ottenere i dati di configurazione dal database Redis anziché da Apigee Edge.

Aggiungi la seguente configurazione al file org-env/config.yaml di ogni nodo Edge Microgateway aggiuntivo. Tieni presente che la proprietà synchronizerMode è impostata su 0. Questa proprietà imposta l'istanza in modo che funzioni come una normale istanza Edge Microgateway che elabora il traffico proxy dell'API e l'istanza otterrà i dati di configurazione dal database Redis.

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Ad esempio:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Proprietà di configurazione

Per supportare l'utilizzo del sincronizzatore sono state aggiunte le seguenti proprietà di configurazione:

Attributo Valori Descrizione

Attributo	Valori	Descrizione
`edge_config.synchronizerMode`	0 o 1	Se il valore è 0 (il valore predefinito), Edge Microgateway opera in modalità standard. Se 1, avvia l'istanza Edge Microgateway in modo che funzioni come sincronizzatore. In questa modalità, l'istanza estrae i dati di configurazione da Apigee Edge e li archivia in un database Redis locale. Questa istanza non è in grado di elaborare le richieste di proxy API. Il suo unico scopo è eseguire il polling di Apigee Edge per i dati di configurazione e scriverli nel database locale. Devi quindi configurare altre istanze di microgateway per la lettura dal database.
`edge_config.redisBasedConfigCache`	true o false	Se true, l'istanza Edge Microgateway recupera i dati di configurazione dal database Redis anziché da Apigee Edge. Il database Redis deve essere lo stesso su cui è configurato lo strumento di sincronizzazione per scrivere. Se il database Redis non è disponibile o se è vuoto, il microgateway cerca un file `cache-config.yaml` esistente per la relativa configurazione. Se è false (il valore predefinito), l'istanza Edge Microgateway recupera i dati di configurazione da Apigee Edge come di consueto.
`edgemicro.config_change_poll_interval`	Intervallo di tempo, in secondi	Specifica l'intervallo di polling per il recupero dei dati da Apigee Edge da parte del sincronizzatore.

edge_config.synchronizerMode

0 o 1

Se il valore è 0 (il valore predefinito), Edge Microgateway opera in modalità standard.

Se 1, avvia l'istanza Edge Microgateway in modo che funzioni come sincronizzatore. In questa modalità, l'istanza estrae i dati di configurazione da Apigee Edge e li archivia in un database Redis locale. Questa istanza non è in grado di elaborare le richieste di proxy API. Il suo unico scopo è eseguire il polling di Apigee Edge per i dati di configurazione e scriverli nel database locale. Devi quindi configurare altre istanze di microgateway per la lettura dal database.

edge_config.redisBasedConfigCache

true o false

Se true, l'istanza Edge Microgateway recupera i dati di configurazione dal database Redis anziché da Apigee Edge. Il database Redis deve essere lo stesso su cui è configurato lo strumento di sincronizzazione per scrivere. Se il database Redis non è disponibile o se è vuoto, il microgateway cerca un file cache-config.yaml esistente per la relativa configurazione.

Se è false (il valore predefinito), l'istanza Edge Microgateway recupera i dati di configurazione da Apigee Edge come di consueto.

edgemicro.config_change_poll_interval Intervallo di tempo, in secondi Specifica l'intervallo di polling per il recupero dei dati da Apigee Edge da parte del sincronizzatore.

Configurare gli URL da escludere per i plug-in

Puoi configurare il microgateway in modo da saltare l'elaborazione dei plug-in per URL specificati. Puoi configurare questi URL "escludi" a livello globale (per tutti i plug-in) o per plug-in specifici.

Ad esempio:

...
edgemicro:
  ...
  plugins:
    excludeUrls: '/hello,/proxy_one' # global exclude urls
    sequence:
      - oauth
      - json2xml
      - quota
json2xml:
  excludeUrls: '/hello/xml'  # plugin level exclude urls
...

In questo esempio, i plug-in non elaboreranno le chiamate proxy API in arrivo con i percorsi /hello o /proxy_one. Inoltre, il plug-in json2xml verrà ignorato per le API con /hello/xml nel percorso.

Non puoi escludere il plug-in analytics.

Impostazione degli attributi di configurazione con i valori delle variabili di ambiente

Puoi specificare le variabili di ambiente utilizzando i tag nel file di configurazione. I tag delle variabili di ambiente specificati vengono sostituiti dai valori effettivi delle variabili di ambiente. Le sostituzioni vengono memorizzate solo in memoria e non nei file di configurazione o della cache originali.

Nota: per impostazione predefinita, il tag <E> analizza i valori delle variabili come stringhe. Per specificare valori booleani e interi positivi, utilizza i tag <n> e <b> interni come illustrato negli esempi riportati di seguito.

In questo esempio, l'attributo key viene sostituito dal valore della variabile di ambiente TARGETS_SSL_CLIENT_KEY e così via.

targets:
  - ssl:
      client:
        key: <E>TARGETS_SSL_CLIENT_KEY</E>
        cert: <E>TARGETS_SSL_CLIENT_CERT</E>
        passphrase: <E>TARGETS_SSL_CLIENT_PASSPHRASE</E>

In questo esempio, il tag <n> viene utilizzato per indicare un valore intero. Sono supportati solo i numeri interi positivi.

edgemicro:
  port: <E><n>EMG_PORT</n></E>

In questo esempio, il tag <b> viene utilizzato per indicare un valore booleano ( ovvero true o false).

quotas:
  useRedis: <E><b>EMG_USE_REDIS</b></E>