Cette page a été traduite par l'API Cloud Translation.

Documentation de référence sur l'opération et la configuration d'Edge Micropasser

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

Edge Microgateway 3.3.x

Cet article explique comment gérer et configurer la micro passerelle Edge.

Mettre à niveau Edge Microgateway si vous disposez d'une connexion Internet

Cette section explique comment mettre à niveau une installation existante de la micro-passerelle Edge. Si vous ne disposez pas d'une connexion Internet, consultez la section Puis-je installer la micro-passerelle Edge sans connexion Internet ?.

Apigee vous recommande de tester votre configuration existante avec la nouvelle version avant de mettre à niveau votre environnement de production.

Exécutez la commande npm suivante pour passer à la dernière version d'Edge Microgateway:
```
npm upgrade edgemicro -g
```
Pour installer une version spécifique d'Edge Microgateway, vous devez spécifier le numéro de version dans la commande d'installation. Par exemple, pour installer la version 3.2.3, exécutez la commande suivante:
```
npm install edgemicro@3.2.3 -g
```

Vérifiez le numéro de version. Par exemple, si vous avez installé la version 3.2.3:

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

Enfin, passez à la dernière version du proxy edgemicro-auth:
```
edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME
```

Modifier la configuration

Voici les fichiers de configuration que vous devez connaître:

Fichier de configuration système par défaut
Fichier de configuration par défaut pour une instance Edge Microgateway nouvellement initialisée
Fichier de configuration dynamique pour les instances en cours d'exécution

Cette section présente ces fichiers et ce que vous devez savoir pour les modifier.

Fichier de configuration système par défaut

Lorsque vous installez Edge Microgateway, un fichier de configuration système par défaut est placé ici:

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

où prefix est le répertoire du préfixe npm. Consultez Où est installé Edge Microgateway si vous ne parvenez pas à trouver ce répertoire.

Si vous modifiez le fichier de configuration système, vous devez réinitialiser, reconfigurer et redémarrer la micro-passerelle Edge:

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

Fichier de configuration par défaut pour les instances Edge Microgateway nouvellement initialisées

Lorsque vous exécutez edgemicro init, le fichier de configuration système (décrit ci-dessus), default.yaml, est placé dans le répertoire ~/.edgemicro.

Si vous modifiez le fichier de configuration dans ~/.edgemicro, vous devez reconfigurer et redémarrer la micro-passerelle Edge:

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

Fichier de configuration dynamique pour les instances en cours d'exécution

Lorsque vous exécutez edgemicro configure [params], un fichier de configuration dynamique est créé dans ~/.edgemicro. Le fichier est nommé selon ce modèle: org-env-config.yaml, où org et env sont les noms de votre organisation et de votre environnement Apigee Edge. Vous pouvez utiliser ce fichier pour apporter des modifications de configuration, puis les recharger sans temps d'arrêt. Par exemple, si vous ajoutez et configurez un plug-in, vous pouvez recharger la configuration sans aucun temps d'arrêt, comme expliqué ci-dessous.

Si Edge Microgateway est en cours d'exécution (option sans temps d'arrêt):

Rechargez la configuration de Edge Microgateway:
```
edgemicro reload -o $ORG -e $ENV -k $KEY -s $SECRET
```
Où :
- $ORG est le nom de votre organisation Edge (vous devez être administrateur de l'organisation).
- $ENV est un environnement de votre organisation (par exemple, "test" ou "prod").
- $KEY est la clé renvoyée précédemment par la commande de configuration.
- $SECRET est la clé renvoyée précédemment par la commande de configuration.
Exemple :
```
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \
  -s 05c14356e42ed1...4e34ab0cc824
```

Si Edge Microgateway est arrêté:

Redémarrez Edge Microgateway:
```
edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET
```
Où :
- $ORG est le nom de votre organisation Edge (vous devez être administrateur de l'organisation).
- $ENV est un environnement de votre organisation (par exemple, "test" ou "prod").
- $KEY est la clé renvoyée précédemment par la commande de configuration.
- $SECRET est la clé renvoyée précédemment par la commande de configuration.
Exemple :
```
edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
  -s 05c1435...e34ab0cc824
```

Voici un exemple de fichier de configuration. Pour en savoir plus sur les paramètres de fichier de configuration, consultez la documentation de référence sur la configuration d'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

Définir des variables d'environnement

Les commandes de l'interface de ligne de commande qui nécessitent des valeurs pour votre organisation et votre environnement Edge, ainsi que la clé et le secret nécessaires pour démarrer la micro-passerelle Edge, peuvent être stockées dans les variables d'environnement suivantes:

EDGEMICRO_ORG
EDGEMICRO_ENV
EDGEMICRO_KEY
EDGEMICRO_SECRET

La définition de ces variables est facultative. Si vous les définissez, vous n'avez pas besoin de spécifier leurs valeurs lorsque vous utilisez l'interface de ligne de commande (CLI) pour configurer et démarrer la micro-passerelle Edge.

Configurer SSL sur le serveur de la micro passerelle Edge

Regardez les vidéos suivantes pour découvrir comment configurer TLS dans la micro passerelle Apigee Edge:

Vidéo	Description
Configurer TLS Northbound à sens unique	Découvrez comment configurer TLS dans la micro passerelle Apigee Edge. Cette vidéo présente TLS et son importance, présente TLS dans la micro-passerelle Edge et explique comment configurer le TLS unidirectionnel vers le nord.
Configurer TLS bidirectionnel vers le nord	Il s'agit de la deuxième vidéo sur la configuration de TLS dans la micro passerelle Edge d'Apigee. Cette vidéo explique comment configurer TLS à deux voies vers le nord.
Configurer TLS Southbound à sens unique et bidirectionnel	Cette troisième vidéo sur la configuration de TLS dans la micro-passerelle Apigee Edge explique comment configurer le TLS à sens unique et bidirectionnel Southbound.

Vous pouvez configurer le serveur Microgateway pour qu'il utilise SSL. Par exemple, avec SSL configuré, vous pouvez appeler des API via la micro passerelle Edge avec le protocole "https", comme suit:

https://localhost:8000/myapi

Pour configurer SSL sur le serveur de la micro-passerelle, procédez comme suit:

Générez ou obtenez un certificat et une clé SSL à l'aide de l'utilitaire openssl ou de la méthode de votre choix.

Ajoutez l'attribut edgemicro:ssl au fichier de configuration d'Edge Microgateway. Pour obtenir la liste complète des options, consultez le tableau ci-dessous. Par exemple:

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

Redémarrez Edge Microgateway. Suivez les étapes décrites dans la section Modifier la configuration en fonction du fichier de configuration que vous avez modifié: le fichier par défaut ou le fichier de configuration d'exécution.

Voici un exemple de section edgemicro du fichier de configuration, avec SSL configuré:

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

Voici la liste de toutes les options de serveur compatibles:

Option	Description
`key`	Chemin d'accès à un fichier `ca.key` (au format PEM).
`cert`	Chemin d'accès à un fichier `ca.cert` (au format PEM).
`pfx`	Chemin d'accès à un fichier `pfx` contenant la clé privée, le certificat et les certificats CA du client au format PFX.
`passphrase`	Chaîne contenant la phrase secrète de la clé privée ou du fichier PFX.
`ca`	Chemin d'accès à un fichier contenant une liste de certificats approuvés au format PEM.
`ciphers`	Chaîne décrivant les algorithmes de chiffrement à utiliser, séparés par un ":".
`rejectUnauthorized`	Si la valeur est "true", le certificat du serveur est validé par rapport à la liste des autorités de certification fournies. Si la validation échoue, une erreur est renvoyée.
`secureProtocol`	Méthode SSL à utiliser. Par exemple, SSLv3_method pour forcer la version 3 de SSL.
`servername`	Nom du serveur pour l'extension TLS SNI (Server Name Indication).
`requestCert`	"true" pour le SSL à double sens, "false" pour le SSL à sens unique

Utiliser les options SSL/TLS du client

Vous pouvez configurer la micro passerelle Edge en tant que client TLS ou SSL lorsque vous vous connectez aux points de terminaison cibles. Dans le fichier de configuration de Microgateway, utilisez l'élément "targets" pour définir les options SSL/TLS. Notez que vous pouvez spécifier plusieurs cibles spécifiques. Un exemple multicible est inclus ci-dessous.

Cet exemple fournit les paramètres qui seront appliqués à tous les hôtes:

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

Dans cet exemple, les paramètres ne s'appliquent qu'à l'hôte spécifié:

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

Voici un exemple pour TLS:

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

Si vous souhaitez appliquer des paramètres TLS/SSL à plusieurs cibles spécifiques, vous devez spécifier le premier hôte de la configuration comme "vide", ce qui active les requêtes universelles, puis spécifier des hôtes spécifiques dans n'importe quel ordre. Dans cet exemple, les paramètres sont appliqués à plusieurs hôtes spécifiques:

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

Voici la liste de toutes les options client compatibles:

Option	Description
`pfx`	Chemin d'accès à un fichier `pfx` contenant la clé privée, le certificat et les certificats CA du client au format PFX.
`key`	Chemin d'accès à un fichier `ca.key` (au format PEM).
`passphrase`	Chaîne contenant la phrase secrète de la clé privée ou du fichier PFX.
`cert`	Chemin d'accès à un fichier `ca.cert` (au format PEM).
`ca`	Chemin d'accès à un fichier contenant une liste de certificats approuvés au format PEM.
`ciphers`	Chaîne décrivant les algorithmes de chiffrement à utiliser, séparés par un ":".
`rejectUnauthorized`	Si la valeur est "true", le certificat du serveur est validé par rapport à la liste des autorités de certification fournies. Si la validation échoue, une erreur est renvoyée.
`secureProtocol`	Méthode SSL à utiliser. Par exemple, SSLv3_method pour forcer la version 3 de SSL.
`servername`	Nom du serveur pour l'extension TLS SNI (Server Name Indication).

Personnaliser le proxy edgemicro-auth

Par défaut, Edge Microgateway utilise un proxy déployé sur Apigee Edge pour l'authentification OAuth2. Ce proxy est déployé lorsque vous exécutez edgemicro configure pour la première fois. Vous pouvez modifier la configuration par défaut de ce proxy pour ajouter la prise en charge des revendications personnalisées à un jeton Web JSON (JWT), configurer l'expiration des jetons et générer des jetons d'actualisation. Pour en savoir plus, consultez la page edgemicro-auth sur GitHub.

Utiliser un service d'authentification personnalisé

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

Si vous souhaitez utiliser votre propre service personnalisé pour gérer l'authentification, modifiez la valeur authUri dans le fichier de configuration pour qu'elle pointe vers votre service. Par exemple, vous pouvez avoir un service qui utilise LDAP pour valider l'identité.

Important:Si vous remplacez le proxy d'authentification par défaut, le nouveau proxy ou service doit renvoyer un format de réponse identique à celui du proxy edgemicro-auth par défaut.

Gérer les fichiers journaux

Edge Microgateway consigne des informations sur chaque requête et réponse. Les fichiers journaux fournissent des informations utiles pour le débogage et le dépannage.

Emplacement de stockage des fichiers journaux

Par défaut, les fichiers journaux sont stockés dans /var/tmp.

Modifier le répertoire de fichiers journaux par défaut

Le répertoire dans lequel les fichiers journaux sont stockés est spécifié dans le fichier de configuration d'Edge Microgateway. Consultez également la section Modifier la configuration.

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

Modifiez la valeur dir pour spécifier un autre répertoire de fichiers journaux.

Envoyer des journaux à la console

Vous pouvez configurer la journalisation de manière à ce que les informations de journal soient envoyées à la sortie standard au lieu d'un fichier journal. Définissez l'indicateur to_console sur "true" comme suit:

edgemicro:
  logging:
    to_console: true

Avec ce paramètre, les journaux sont envoyés à la sortie standard. Actuellement, vous ne pouvez pas envoyer de journaux à la fois à stdout et à un fichier journal.

Définir le niveau de journalisation

Vous spécifiez le niveau de journalisation à utiliser dans la configuration edgemicro. Pour obtenir la liste complète des niveaux de journalisation et de leurs descriptions, consultez la section Attributs edgemicro.

Par exemple, la configuration suivante définit le niveau de journalisation sur 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

Modifier les intervalles de journalisation

Vous pouvez configurer ces intervalles dans le fichier de configuration d'Edge Microgateway. Consultez également la section Modifier une configuration.

Les attributs configurables sont les suivants:

stats_log_interval: (valeur par défaut: 60) Intervalle, en secondes, lorsque l'enregistrement des statistiques est écrit dans le fichier journal de l'API.
rotate_interval: (valeur par défaut: 24) Intervalle, en heures, de rotation des fichiers journaux. Exemple :

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

Assouplir les autorisations strictes des fichiers journaux

Par défaut, Edge Microgateway génère le fichier journal de l'application (api-log.log) avec le niveau d'autorisation de fichier défini sur 0600. Ce niveau d'autorisation n'autorise pas les applications ou les utilisateurs externes à lire le fichier journal. Pour assouplir ce niveau d'autorisation strict, définissez logging:disableStrictLogFile sur true. Lorsque cet attribut est défini sur true, le fichier journal est créé avec l'autorisation de fichier définie sur 0755. Si false est défini ou si l'attribut n'est pas fourni, l'autorisation est définie par défaut sur 0600.

Ajouté dans la version 3.2.3.

Exemple :

edgemicro:
 logging:
   disableStrictLogFile: true

Bonnes pratiques de maintenance des fichiers journaux

À mesure que les données des fichiers journaux s'accumulent au fil du temps, Apigee vous recommande d'adopter les pratiques suivantes:

Comme les fichiers journaux peuvent être très volumineux, assurez-vous que le répertoire des fichiers journaux dispose d'un espace suffisant. Consultez les sections suivantes : Emplacement des fichiers journaux et Modifier le répertoire de fichiers journaux par défaut.
Supprimez ou déplacez les fichiers journaux vers un répertoire d'archive distinct au moins une fois par semaine.
Si votre règle consiste à supprimer les journaux, vous pouvez utiliser la commande CLI edgemicro log -c pour supprimer (nettoyer) les journaux plus anciens.

Convention de nommage des fichiers journaux

Chaque instance de micro passerelle Edge génère un fichier journal avec une extension .log. La convention d'attribution de noms pour les fichiers journaux est la suivante:

edgemicro-HOST_NAME-INSTANCE_ID-api.log

Exemple :

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log

À propos du contenu des fichiers journaux

Ajoutée dans la version 2.3.3

Par défaut, le service de journalisation omet le format JSON des proxys et des produits téléchargés, ainsi que le jeton Web JSON (JWT). Si vous souhaitez afficher ces objets dans la console, définissez l'indicateur de ligne de commande DEBUG=* lorsque vous démarrez la micro-passerelle Edge. Exemple :

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

Sous Windows, utilisez SET DEBUG=*.

Contenu du fichier journal "api"

Le fichier journal "api" contient des informations détaillées sur le flux de requêtes et de réponses via Edge Microgateway. Les fichiers journaux "api" sont nommés comme suit:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

Pour chaque requête envoyée à Edge Microgateway, quatre événements sont capturés dans le fichier de journal "api" :

Requête entrante du client
Requête sortante envoyée à la cible
Réponse entrante de la cible
Réponse sortante au client

Chacune de ces entrées distinctes est représentée sous forme de notation abrégée pour réduire la taille des fichiers journaux. Voici quatre exemples d'entrées représentant chacun des quatre événements. Dans le fichier journal, elles se présentent comme suit (les numéros de ligne ne servent qu'à référence dans le document, ils n'apparaissent pas dans le fichier journal).

(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

Examinons-les une par une:

1. Exemple de requête entrante du client:

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

1436403888651 : code temporel Unix
info : niveau de journalisation. Cette valeur dépend du contexte de la transaction et du niveau de journalisation défini dans la configuration edgemicro. Consultez Définir le niveau de journalisation. Pour les enregistrements de statistiques, le niveau est défini sur stats. Les enregistrements de statistiques sont signalés à intervalles réguliers définis avec la configuration stats_log_interval. Consultez également Modifier les intervalles de journalisation.
req : identifie l'événement. Dans ce cas, la requête du client.
m : verbe HTTP utilisé dans la requête.
u : partie de l'URL qui suit le chemin d'accès de base.
h : hôte et numéro de port sur lesquels Edge Microgateway écoute.
r : hôte et port distants d'où provient la requête client.
i : ID de la requête. Les quatre entrées d'événements partageront cet ID. Chaque requête se voit attribuer un ID de requête unique. La corrélation des enregistrements de journal par ID de requête peut fournir des informations précieuses sur la latence de la cible.
d : durée en millisecondes depuis la réception de la requête par Edge Microgateway. Dans l'exemple ci-dessus, la réponse de la cible pour la requête 0 a été reçue au bout de sept millisecondes (ligne 3), et la réponse a été envoyée au client au bout de quatre millisecondes supplémentaires (ligne 4). En d'autres termes, la latence totale de la requête était de 11 millisecondes, dont 7 millisecondes ont été prises par la cible et 4 millisecondes par la micro passerelle Edge elle-même.

2. Exemple de requête sortante envoyée à la cible:

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

1436403888651 : code temporel Unix
info : niveau de journalisation. Cette valeur dépend du contexte de la transaction et du niveau de journalisation défini dans la configuration edgemicro. Consultez Définir le niveau de journalisation. Pour les enregistrements de statistiques, le niveau est défini sur stats. Les enregistrements de statistiques sont signalés à intervalles réguliers définis avec la configuration stats_log_interval. Consultez également Modifier les intervalles de journalisation.
treq : identifie l'événement. Dans ce cas, la requête cible.
m : verbe HTTP utilisé dans la requête cible.
u : partie de l'URL qui suit le chemin d'accès de base.
h : hôte et numéro de port de la cible backend.
i : ID de l'entrée de journal. Les quatre entrées d'événements partageront cet ID.

3. Exemple de réponse entrante de la cible

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

1436403888651 : code temporel Unix

info : niveau de journalisation. Cette valeur dépend du contexte de la transaction et du niveau de journalisation défini dans la configuration edgemicro. Consultez Définir le niveau de journalisation. Pour les enregistrements de statistiques, le niveau est défini sur stats. Les enregistrements de statistiques sont signalés à intervalles réguliers définis avec la configuration stats_log_interval. Consultez également Modifier les intervalles de journalisation.
tres : identifie l'événement. Dans ce cas, la réponse cible.
s : état de la réponse HTTP.
d : durée en millisecondes. Durée de l'appel d'API par la cible.
i : ID de l'entrée de journal. Les quatre entrées d'événements partageront cet ID.

4. Exemple de réponse sortante au client

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

1436403888651 : code temporel Unix

info : niveau de journalisation. Cette valeur dépend du contexte de la transaction et du niveau de journalisation défini dans la configuration edgemicro. Consultez Définir le niveau de journalisation. Pour les enregistrements de statistiques, le niveau est défini sur stats. Les enregistrements de statistiques sont signalés à intervalles réguliers définis avec la configuration stats_log_interval. Consultez également Modifier les intervalles de journalisation.
res : identifie l'événement. Dans ce cas, la réponse au client.
s : état de la réponse HTTP.
d : durée en millisecondes. Il s'agit du temps total pris par l'appel d'API, y compris le temps pris par l'API cible et le temps pris par Edge Microgateway lui-même.
i : ID de l'entrée de journal. Les quatre entrées d'événements partageront cet ID.

Planification des fichiers journaux

Les fichiers journaux sont mis en rotation à l'intervalle spécifié par l'attribut de configuration rotate_interval. Les entrées continueront d'être ajoutées au même fichier journal jusqu'à l'expiration de l'intervalle de rotation. Toutefois, chaque fois que la micro passerelle Edge est redémarrée, elle reçoit un nouvel UID et crée un nouvel ensemble de fichiers journaux avec cet UID. Consultez également les bonnes pratiques de maintenance des fichiers journaux.

Messages d'erreur

Certaines entrées de journal contiennent des messages d'erreur. Pour vous aider à identifier où et pourquoi les erreurs se produisent, consultez la liste des erreurs Edge Microgateway.

Documentation de référence sur la configuration d'Edge Microgateway

Emplacement du fichier de configuration

Les attributs de configuration décrits dans cette section se trouvent dans le fichier de configuration d'Edge Microgateway. Consultez également la section Modifier la configuration.

Attributs edge_config

Ces paramètres permettent de configurer l'interaction entre l'instance de micro-passerelle Edge et Apigee Edge.

bootstrap: (valeur par défaut: aucune) URL pointant vers un service spécifique à Edge Microgateway exécuté sur Apigee Edge. Edge Microgateway utilise ce service pour communiquer avec Apigee Edge. Cette URL est renvoyée lorsque vous exécutez la commande permettant de générer la paire de clés publique/privée: edgemicro genkeys. Pour en savoir plus, consultez Configurer Edge Microgateway.
jwt_public_key (valeur par défaut : aucune) : URL qui pointe vers le proxy de la micro-passerelle Edge déployé sur Apigee Edge. Ce proxy sert de point de terminaison d'authentification pour l'émission de jetons d'accès signés aux clients. Cette URL est renvoyée lorsque vous exécutez la commande de déploiement du proxy: edgemicro configure. Pour en savoir plus, consultez Configurer Edge Microgateway.
quotaUri: définissez cette propriété de configuration si vous souhaitez gérer les quotas via le proxy edgemicro-auth déployé dans votre organisation. Si cette propriété n'est pas définie, le point de terminaison de quota est défini par défaut sur le point de terminaison interne de la micro passerelle Edge.
```
edge_config:
  quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
```

Attributs edgemicro

Ces paramètres configurent le processus Edge Microgateway.

port: (par défaut: 8000) numéro de port sur lequel le processus de micro-passerelle Edge écoute.
max_connections: (valeur par défaut: -1) spécifie le nombre maximal de connexions entrantes simultanées que la micro-passerelle Edge peut recevoir. Si ce nombre est dépassé, l'état suivant est renvoyé:

res.statusCode = 429; // Too many requests
max_connections_hard: (valeur par défaut: -1) Nombre maximal de requêtes simultanées que la micro-passerelle Edge peut recevoir avant de fermer la connexion. Ce paramètre vise à contrecarrer les attaques par déni de service. En règle générale, définissez-le sur un nombre supérieur à max_connections.
Journalisation :
- level: (par défaut: error)
  - info : (recommandé) consigne toutes les requêtes et réponses qui transitent par une instance Edge Microgateway.
  - warn : enregistre uniquement les messages d'avertissement.
  - error : enregistre uniquement les messages d'erreur.
  - debug : consigne les messages de débogage, ainsi que les messages d'information, d'avertissement et d'erreur.
  - trace : journalise les informations de trace pour les erreurs, ainsi que les messages d'information, d'avertissement et d'erreur.
  - none : ne créez pas de fichier journal.
- dir: (valeur par défaut: /var/tmp) répertoire dans lequel les fichiers journaux sont stockés.
- stats_log_interval: (valeur par défaut: 60) Intervalle, en secondes, lorsque l'enregistrement des statistiques est écrit dans le fichier journal de l'API.
- rotate_interval: (valeur par défaut: 24) Intervalle, en heures, de rotation des fichiers journaux.

plug-ins: les plug-ins ajoutent des fonctionnalités à Edge Microgateway. Pour en savoir plus sur le développement de plug-ins, consultez Développer des plug-ins personnalisés.

dir: chemin d'accès relatif du répertoire ./gateway au répertoire ./plugins, ou chemin d'accès absolu.
sequence: liste des modules de plug-in à ajouter à votre instance de micro passerelle Edge. Les modules s'exécutent dans l'ordre dans lequel ils sont spécifiés ici.

debug : ajoute le débogage à distance au processus Edge Microgateway.
- port: numéro de port à écouter. Par exemple, définissez le débogueur de votre IDE pour qu'il écoute sur ce port.
- args: arguments du processus de débogage. Exemple :args --nolazy
config_change_poll_interval: (valeur par défaut:600 secondes) : la micro-passerelle Edge charge une nouvelle configuration périodiquement et effectue un rechargement en cas de modification. L'interrogation détecte toutes les modifications apportées à Edge (modifications apportées aux produits, proxys compatibles avec la micro-passerelle, etc.), ainsi que les modifications apportées au fichier de configuration local.
disable_config_poll_interval (valeur par défaut:false) : définissez sur true pour désactiver la vérification automatique des modifications.
request_timeout: définit un délai avant expiration pour les requêtes cibles. Le délai avant expiration est défini en secondes. En cas de délai avant expiration, la micro passerelle Edge répond avec un code d'état 504. (Ajouté v2.4.x)
keep_alive_timeout: cette propriété vous permet de définir le délai avant expiration d'Edge Microgateway (en millisecondes). (valeur par défaut: 5 secondes) (ajouté dans la version 3.0.6)
headers_timeout: cet attribut limite la durée (en millisecondes) pendant laquelle l'analyseur HTTP attendra de recevoir les en-têtes HTTP complets.
Exemple :
```
edgemicro:
  keep_alive_timeout: 6000
  headers_timeout: 12000
```
En interne, le paramètre définit l'attribut Server.headersTimeout Node.js sur les requêtes. (Par défaut: 5 secondes de plus que le délai défini avec edgemicro.keep_alive_timeout. Ce paramètre par défaut empêche les équilibreurs de charge ou les proxys de couper la connexion par erreur.) (Ajouté v3.1.1)
noRuleMatchAction (chaîne) : action à effectuer (autoriser ou refuser l'accès) si la règle de correspondance spécifiée dans le plug-in accesscontrol n'est pas résolue (sans correspondance). Valeurs valides: ALLOW ou DENY Valeur par défaut: ALLOW (ajouté: version 3.1.7)
enableAnalytics (valeur par défaut : "true") : définissez l'attribut sur false pour empêcher le chargement du plug-in d'analyse. Dans ce cas, aucun appel aux données analytiques d'Apigee Edge ne sera effectué. Si cet attribut est défini sur true ou n'est pas fourni, le plug-in d'analyse fonctionne comme d'habitude. Pour en savoir plus, consultez les attributs edgemicro. (Ajouté v3.1.8)
Exemple :
```
edgemicro
  enableAnalytics=false|true
```
Si enableAnalytics est défini sur false, mais que la micro-passerelle Edge est démarrée à l'aide du plug-in de métriques, le plug-in d'analyse fonctionnera comme d'habitude, car le plug-in de métriques a besoin du plug-in d'analyse pour fonctionner. Pour en savoir plus sur le plug-in de métriques, consultez les notes de version d'Edge Microgateway v1.3.6.

on_target_response_abort: cet attribut vous permet de contrôler le comportement d'Edge Microgateway si la connexion entre le client (Edge Microgateway) et le serveur cible se ferme prématurément.

Valeur	Description
Par défaut	Si `on_target_response_abort` n'est pas spécifié, le comportement par défaut consiste à tronquer la réponse sans afficher d'erreur. Dans les fichiers journaux, un message d'avertissement s'affiche avec `targetResponse aborted` et un code de réponse 502.
`appendErrorToClientResponseBody`	L'erreur personnalisée `TargetResponseAborted` est renvoyée au client. Dans les fichiers journaux, un message d'avertissement s'affiche avec `targetResponse aborted` et un code de réponse 502. En outre, l'erreur `TargetResponseAborted` est enregistrée avec le message `Target response ended prematurely.`.
`abortClientRequest`	La micro passerelle Edge interrompt la requête, et un avertissement est écrit dans les fichiers journaux : `TargetResponseAborted` avec le code d'état de la requête 502.

Exemple :

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

attributs des en-têtes

Ces paramètres configurent la manière dont certains en-têtes HTTP sont traités.

x-forwarded-for: (par défaut : "true") Définissez sur "false" pour empêcher la transmission des en-têtes x-forwarded-for à la cible. Notez que si un en-tête x-forwarded-for est présent dans la requête, sa valeur sera définie sur la valeur client-ip dans Edge Analytics.
x-forwarded-host: (par défaut : "true") Définissez sur "false" pour empêcher la transmission des en-têtes x-forwarded-host à la cible.
x-request-id: (par défaut : "true") Définissez sur "false" pour empêcher les en-têtes x-request-id d'être transmis à la cible.
x-response-time: (par défaut: true) Définissez sur "false" pour empêcher les en-têtes x-response-time d'être transmis à la cible.
via: (valeur par défaut : "true") Définissez cette valeur sur "false" pour empêcher les en-têtes via d'être transmis à la cible.

attributs oauth

Ces paramètres configurent la manière dont l'authentification client est appliquée par Edge Microgateway.

allowNoAuthorization: (valeur par défaut: false) Si cette valeur est définie sur "true", les appels d'API sont autorisés à passer par Edge Microgateway sans en-tête d'autorisation. Définissez cette valeur sur "false" pour exiger un en-tête d'autorisation (par défaut).
allowInvalidAuthorization: (valeur par défaut: false) Si cette valeur est définie sur "true", les appels d'API sont autorisés à passer si le jeton transmis dans l'en-tête "Authorization" n'est pas valide ou a expiré. Définissez cette valeur sur "false" pour exiger des jetons valides (valeur par défaut).
authorization-header: (valeur par défaut: Authorization: Bearer) En-tête utilisé pour envoyer le jeton d'accès à la micro-passerelle Edge. Vous pouvez modifier la valeur par défaut lorsque la cible doit utiliser l'en-tête d'autorisation à d'autres fins.
api-key-header: (valeur par défaut: x-api-key) Nom de l'en-tête ou du paramètre de requête utilisé pour transmettre une clé API à la micro-passerelle Edge. Consultez également la section Utiliser une clé API.
keep-authorization-header: (valeur par défaut : "false") Si défini sur "true", l'en-tête d'autorisation envoyé dans la requête est transmis à la cible (il est conservé).
allowOAuthOnly : si cette valeur est définie sur "true", chaque API doit comporter un en-tête "Authorization" avec un jeton d'accès de type "Bearer". Vous permet d'autoriser uniquement le modèle de sécurité OAuth (tout en conservant la rétrocompatibilité). (Ajoutée dans la version 2.4.x)
allowAPIKeyOnly : si cette valeur est définie sur "true", chaque API doit comporter un en-tête x-api-key (ou un emplacement personnalisé) avec une clé API.Vous ne pouvez autoriser que le modèle de sécurité de la clé API (tout en conservant la rétrocompatibilité). (Ajout 2.4.x)
Ne définissez pas allowOAuthOnly et allowAPIKeyOnly sur "true". Par défaut, les deux indicateurs sont définis sur "false" (pour la rétrocompatibilité).
gracePeriod : ce paramètre permet d'éviter les erreurs causées par de légères différences entre l'horloge système et les heures "Not Before" (nbf) ou "Issued At" (iat) spécifiées dans le jeton d'autorisation JWT. Définissez ce paramètre sur le nombre de secondes à autoriser pour ces écarts. (Ajoutée le 2.5.7)

Attributs spécifiques au plug-in

Pour en savoir plus sur les attributs configurables de chaque plug-in, consultez la section Utiliser des plug-ins.

Proxys de filtrage

Vous pouvez filtrer les proxys compatibles avec la micro passerelle qu'une instance Edge Microgateway traitera. Lorsque Edge Microgateway démarre, il télécharge tous les proxy compatibles avec la micro passerelle de l'organisation à laquelle il est associé. Utilisez la configuration suivante pour limiter les proxys que la micro passerelle traitera. Par exemple, cette configuration limite les proxys que la micro passerelle traitera à trois: edgemicro_proxy-1, edgemicro_proxy-2 et edgemicro_proxy-3:

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

Filtrer les produits par nom

Utilisez la configuration suivante pour limiter le nombre de produits d'API que la micro passerelle Edge télécharge et traite. Pour filtrer les produits téléchargés, ajoutez le paramètre de requête productnamefilter à l'API /products listée dans le fichier *.config.yaml de la micro passerelle Edge. Exemple :

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'

Notez que la valeur du paramètre de requête doit être spécifiée au format d'expression régulière et encodée au format URL. Par exemple, l'expression régulière ^[Ee]dgemicro.*$ détecte les noms tels que "edgemicro-test-1" , "edgemicro_demo" et "Edgemicro_New_Demo". La valeur encodée au format URL, adaptée à l'utilisation dans le paramètre de requête, est la suivante: %5E%5BEe%5Ddgemicro.%2A%24.

La sortie de débogage suivante montre que seuls les produits filtrés ont été téléchargés:

...
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":[

         ]
      }
   ]
}

Filtrer les produits par attributs personnalisés

Pour filtrer les produits en fonction d'attributs personnalisés:

Dans l'interface utilisateur Edge, sélectionnez le proxy edgemicro_auth dans l'organisation/l'environnement dans lequel vous avez configuré Edge Microgateway.
Dans le volet "Développer", ouvrez la stratégie JavaCallout dans l'éditeur.
Ajoutez un attribut personnalisé avec la clé products.filter.attributes et une liste de noms d'attributs séparés par une virgule. Seuls les produits contenant l'un des noms d'attributs personnalisés seront renvoyés à la micro-passerelle Edge.
Vous pouvez éventuellement désactiver la vérification pour voir si le produit est activé pour l'environnement actuel en définissant l'attribut personnalisé products.filter.env.enable sur false. (La valeur par défaut est "true".)
(Cloud privé uniquement) Si vous utilisez Edge pour le cloud privé, définissez la propriété org.noncps sur true pour extraire des produits pour les environnements autres que CPS.

Exemple :

<?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>

Filtrer les produits par état de révocation

Les produits d'API ont trois codes d'état : "En attente", "Approuvé" et "Révoqué". Une nouvelle propriété appelée allowProductStatus a été ajoutée à la règle de configuration des variables JWT dans le proxy edgemicro-auth. Pour utiliser cette propriété afin de filtrer les produits de l'API listés dans le jeton JWT:

Ouvrez le proxy edgemicro-auth dans l'éditeur de proxy Apigee.

Ajoutez la propriété allowProductStatus au fichier XML de la règle SetJWTVariables et spécifiez une liste de codes d'état séparés par une virgule à utiliser comme filtre. Par exemple, pour filtrer sur les états En attente et Résilié:

<?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>

Si vous ne souhaitez afficher que les produits approuvés, définissez la propriété comme suit:

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

Enregistrez le proxy.
Si la balise Property n'est pas présente, tous les codes d'état des produits sont listés dans le jeton JWT.

Pour utiliser cette nouvelle propriété, vous devez mettre à niveau le proxy edgemicro-auth.

Configurer la fréquence d'envoi des données analytiques

Utilisez ces paramètres de configuration pour contrôler la fréquence à laquelle la micro passerelle Edge envoie des données analytiques à Apigee:

bufferSize (facultatif): nombre maximal d'enregistrements Analytics que le tampon peut contenir avant de commencer à supprimer les enregistrements les plus anciens. Par défaut: 10 000
batchSize (facultatif): taille maximale d'un lot d'enregistrements d'analyse envoyés à Apigee. Valeur par défaut: 500
flushInterval (facultatif): nombre de millisecondes entre chaque vidage d'un lot d'enregistrements d'analyse envoyés à Apigee. Valeur par défaut: 5 000

Exemple :

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Masquer les données d'analyse

La configuration suivante empêche les informations sur le chemin de la requête d'apparaître dans les données analytiques Edge. Ajoutez les éléments suivants à la configuration de la micro passerelle pour masquer l'URI et/ou le chemin de la requête. Notez que l'URI se compose du nom d'hôte et du chemin d'accès de la requête.

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

Ségréguer les appels d'API dans Edge Analytics

Vous pouvez configurer le plug-in d'analyse pour séparer un chemin d'API spécifique afin qu'il apparaisse comme un proxy distinct dans les tableaux de bord Edge Analytics. Par exemple, vous pouvez séparer une API de vérification de l'état dans le tableau de bord pour éviter de la confondre avec des appels de proxy d'API réels. Dans le tableau de bord Analytics, les proxys ségrégués suivent ce modèle de dénomination:

edgemicro_proxyname-health

L'image suivante montre deux proxys distincts dans le tableau de bord Analytics: edgemicro_hello-health et edgemicro_mock-health:

Utilisez ces paramètres pour séparer les chemins d'accès relatifs et absolus dans le tableau de bord Analytics en tant que proxys distincts:

relativePath (facultatif): spécifie un chemin d'accès relatif à ségréguer dans le tableau de bord Analytics. Par exemple, si vous spécifiez /healthcheck, tous les appels d'API contenant le chemin d'accès /healthcheck s'afficheront dans le tableau de bord sous la forme edgemicro_proxyname-health. Notez que cet indicateur ignore le chemin d'accès de base du proxy. Pour effectuer une ségrégation en fonction d'un chemin d'accès complet, y compris le chemin d'accès de base, utilisez l'indicateur proxyPath.
proxyPath (facultatif): spécifie un chemin d'accès complet au proxy d'API, y compris le chemin de base du proxy, à ségréguer dans le tableau de bord d'analyse. Par exemple, si vous spécifiez /mocktarget/healthcheck, où /mocktarget est le chemin de base du proxy, tous les appels d'API avec le chemin /mocktarget/healthcheck s'affichent dans le tableau de bord sous la forme edgemicro_proxyname-health.

Par exemple, dans la configuration suivante, tout chemin d'API contenant /healthcheck sera séparé par le plug-in d'analyse. Cela signifie que /foo/healthcheck et /foo/bar/healthcheck seront dissociés en tant que proxy distinct appelé edgemicro_proxyname-health dans le tableau de bord d'analyse.

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

Dans la configuration suivante, toute API avec le chemin d'accès au proxy /mocktarget/healthcheck sera séparée en tant que proxy distinct appelé edgemicro_proxyname-health dans le tableau de bord d'analyse.

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

Configurer Edge Microgateway derrière un pare-feu d'entreprise

Utiliser un proxy HTTP pour communiquer avec Apigee Edge

Ajouté dans la version 3.1.2.

Pour utiliser un proxy HTTP pour la communication entre la micro passerelle Edge et Apigee Edge, procédez comme suit:

Définissez les variables d'environnement HTTP_PROXY, HTTPS_PROXY et NO_PROXY. Ces variables contrôlent les hôtes de chaque proxy HTTP que vous souhaitez utiliser pour la communication avec Apigee Edge, ou les hôtes qui ne doivent pas gérer la communication avec Apigee Edge. Exemple :
```
export HTTP_PROXY='http://localhost:3786'
export HTTPS_PROXY='https://localhost:3786'
export NO_PROXY='localhost,localhost:8080'
```
Notez que NO_PROXY peut être une liste de domaines (séparés par une virgule) vers lesquels la micro passerelle Edge ne doit pas utiliser de proxy.

Pour en savoir plus sur ces variables, consultez https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables.
Redémarrez Edge Microgateway.

Utiliser un proxy HTTP pour la communication cible

Ajouté dans la version 3.1.2.

Pour utiliser un proxy HTTP pour la communication entre la micro passerelle Edge et les cibles backend, procédez comme suit:

Ajoutez la configuration suivante au fichier de configuration de la micro passerelle:
```
edgemicro:
  proxy:
    tunnel: true | false
    url: proxy_url
    bypass: target_host # target hosts to bypass the proxy.
    enabled: true | false
```
Où :
- tunnel: (facultatif) Lorsque cette valeur est définie sur "true", la micro passerelle Edge utilise la méthode HTTP CONNECT pour tunneliser les requêtes HTTP via une seule connexion TCP. (Il en va de même si les variables d'environnement, comme indiqué ci-dessous, pour configurer le proxy sont activées TLS.) Par défaut : false
- url: URL du proxy HTTP.
- bypass (facultatif) : spécifie une ou plusieurs URL d'hôte cible séparées par une virgule qui doivent contourner le proxy HTTP. Si cette propriété n'est pas définie, utilisez la variable d'environnement NO_PROXY pour spécifier les URL cibles à ignorer.
- enabled: si la valeur est "true" et que proxy.url est défini, utilisez la valeur proxy.url pour le proxy HTTP. Si la valeur est "true" et que proxy.url n'est pas défini, utilisez les proxys spécifiés dans les variables d'environnement de proxy HTTP HTTP_PROXY et HTTPS_PROXY, comme décrit dans la section Utiliser un proxy HTTP pour la communication avec Apigee Edge.
Exemple :
```
edgemicro:
  proxy:
    tunnel: true
    url: 'http://localhost:3786'
    bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy.
    enabled: true
```
REMARQUE : Si edgemicro.proxy est omis du fichier de configuration ou si edgemicro.proxy.enabled est défini sur "false", la micro-passerelle Edge n'utilisera pas de proxy HTTP pour la communication cible.
Redémarrez Edge Microgateway.

Utiliser des caractères génériques dans les proxys compatibles avec Microgateway

Vous pouvez utiliser un ou plusieurs caractères génériques "*" dans le chemin d'accès de base d'un proxy edgemicro_* (compatible avec la micro-passerelle). Par exemple, un chemin de base de /team/*/members permet aux clients d'appeler https://[host]/team/blue/members et https://[host]/team/green/members sans que vous ayez besoin de créer de proxys d'API pour gérer les nouvelles équipes. Notez que /**/ n'est pas accepté.

Important:Apigee n'accepte PAS le caractère générique "*" en tant que premier élément d'un chemin de base. Par exemple, ceci n'est PAS accepté: recherche /*/.

Rotation des clés JWT

Comment Edge Microgateway utilise les jetons JWT

Les jetons Web JSON (JWT) sont une norme de jetons décrite dans la RFC7519. Le jeton JWT permet de signer un ensemble de revendications, qui peuvent être vérifiées de manière fiable par le destinataire du jeton JWT.

Vous pouvez générer un jeton JWT à l'aide de la CLI et l'utiliser dans l'en-tête d'autorisation des appels d'API au lieu d'une clé API. Exemple :

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

Pour en savoir plus sur la génération de JWT avec la CLI, consultez la section Générer un jeton.

Qu'est-ce que la rotation des clés ?

Après la génération initiale d'un jeton JWT, vous pouvez être amené à modifier la paire de clés publique/privée stockée dans la KVM chiffrée Edge. Ce processus de génération d'une nouvelle paire de clés est appelé rotation des clés. Lorsque vous effectuez une rotation des clés, une nouvelle paire de clés privée/publique est générée et stockée dans la KVM "microgateway" de votre organisation/environnement Apigee Edge. De plus, l'ancienne clé publique est conservée avec son ID de clé d'origine.

Pour générer un JWT, Edge utilise les informations stockées dans le KVM chiffré. Un KVM appelé microgateway a été créé et rempli de clés lorsque vous avez configuré Edge Microgateway pour la première fois. Les clés du KVM sont utilisées pour signer et chiffrer un jeton JWT.

Les touches KVM incluent les suivantes:

private_key : dernière clé privée RSA utilisée pour signer les jetons JWT (créée le plus récemment).
public_key : dernier certificat (créé le plus récemment) utilisé pour valider les jetons JWT signés avec la clé privée.
private_key_kid : ID de clé privée le plus récent (créé le plus récemment). Cet ID de clé est associé à la valeur private_key et permet de gérer la rotation des clés.
public_key1_kid : ID de clé publique le plus récent (créé le plus récemment). Cette clé est associée à la valeur public_key1 et permet de prendre en charge la rotation des clés. Cette valeur est identique à la clé privée kid.
public_key1 : dernière clé publique (créée le plus récemment).

Lorsque vous effectuez une rotation de clés, les valeurs de clé existantes sont remplacées dans le mappage et de nouvelles clés sont ajoutées pour conserver les anciennes clés publiques. Exemple :

public_key2_kid : ancien ID de clé publique. Cette clé est associée à la valeur public_key2 et permet de prendre en charge la rotation des clés.
public_key2 : ancienne clé publique.

Les jetons JWT présentés pour validation seront validés à l'aide de la nouvelle clé publique. Si la validation échoue, l'ancienne clé publique est utilisée jusqu'à l'expiration du JWT (après l'intervalle token_expiry*, par défaut 30 minutes). Vous pouvez ainsi "faire pivoter" les clés sans perturber immédiatement le trafic de l'API.

Effectuer une rotation de clés

Cette section explique comment effectuer une rotation des clés.

Pour mettre à niveau KVM, utilisez la commande edgemicro upgradekvm. Pour en savoir plus sur l'exécution de cette commande, consultez la section Mettre à niveau le KVM. Cette action ne doit être effectuée qu'une seule fois.
Pour mettre à niveau le proxy edgemicro-oauth, utilisez la commande edgemicro upgradeauth. Pour en savoir plus sur l'exécution de cette commande, consultez Mettre à niveau le proxy edgemicro-auth. Cette action ne doit être effectuée qu'une seule fois.
Ajoutez la ligne suivante à votre fichier ~/.edgemicro/org-env-config.yaml, dans lequel vous devez spécifier la même organisation et le même environnement que ceux que vous avez configurés pour la micropasserelle:
```
jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'
```

Exécutez la commande de rotation des clés pour les faire pivoter. Pour en savoir plus sur cette commande, consultez la section Alterner les clés.

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

Exemple :

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

Après la rotation des clés, Edge renvoie plusieurs clés à Edge Microgateway. Notez que dans l'exemple suivant, chaque clé a une valeur "kid" (ID de clé) unique. La micro passerelle utilise ensuite ces clés pour valider les jetons d'autorisation. Si la validation du jeton échoue, la micro-passerelle vérifie si une clé plus ancienne est présente dans l'ensemble de clés et l'essaie. Le format des clés renvoyées est la clé JSON Web (JWK). Pour en savoir plus sur ce format, consultez la 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"
    }
  ]
}

Configurer un délai "avant le"

Pour les versions 3.1.5 et antérieures, la nouvelle clé privée générée par la commande rotatekey prenait effet immédiatement, et les nouveaux jetons générés étaient signés avec la nouvelle clé privée. Toutefois, la nouvelle clé publique n'était disponible que toutes les 10 minutes (par défaut) pour les instances de micro passerelle Edge lorsque la configuration de la micro passerelle était actualisée. En raison de ce décalage entre la signature du jeton et l'actualisation de l'instance de la micro passerelle, les jetons signés avec la dernière clé sont rejetés jusqu'à ce que toutes les instances aient reçu la dernière clé publique.

Lorsque plusieurs instances de micro passerelle existent, le décalage de la clé publique entraînait parfois des erreurs d'exécution intermittentes avec l'état 403, car la validation du jeton passait sur une instance, mais échouait sur une autre jusqu'à ce que toutes les instances soient actualisées.

À partir de la version 3.1.6, un nouvel indicateur de la commande rotatekey vous permet de spécifier un délai pour que la nouvelle clé privée devienne effective, ce qui permet à toutes les instances de micro passerelle d'être actualisées et de recevoir la nouvelle clé publique. Le nouvel indicateur est --nbf, qui signifie "pas avant". Cet indicateur prend une valeur entière, le nombre de minutes de retard.

Dans l'exemple suivant, le délai est défini sur 15 minutes:

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

Notez qu'il est recommandé de définir le délai sur une valeur supérieure au paramètre de configuration config_change_poll_internal, qui est de 10 minutes par défaut. Consultez également les attributs edgemicro.

Filtrer les proxys téléchargés

Par défaut, Edge Microgateway télécharge tous les proxys de votre organisation Edge qui commencent par le préfixe de dénomination "edgemicro_". Vous pouvez modifier cette valeur par défaut pour télécharger des proxys dont les noms correspondent à un format.

Ouvrez votre fichier de configuration Edge Micro: ~/.edgemicro/org-env-config.yaml
Ajoutez l'élément proxyPattern sous edge_config. Par exemple, le modèle suivant téléchargera des proxys tels que edgemicro_foo, edgemicro_fast et edgemicro_first.
```
edge_config:
…
proxyPattern: edgemicro_f*
```

Spécifier des produits sans proxys d'API

Dans Apigee Edge, vous pouvez créer un produit d'API qui ne contient aucun proxy d'API. Cette configuration de produit permet à une clé API associée à ce produit de fonctionner avec n'importe quel proxy déployé dans votre organisation. À partir de la version 2.5.4, Edge Microgateway est compatible avec cette configuration de produit.

Débogage et dépannage

Se connecter à un débogueur

Vous pouvez exécuter Edge Microgateway avec un débogueur, tel que node-inspector. Cela est utile pour le dépannage et le débogage des plug-ins personnalisés.

Redémarrez Edge Microgateway en mode débogage. Pour ce faire, ajoutez DEBUG=* au début de la commande start:
```
DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET
```
REMARQUE : Sous Windows, utilisez SET DEBUG=*.

Pour rediriger la sortie de débogage vers un fichier, vous pouvez utiliser la commande suivante:
```
export DEBUG=* nohup edgemicro start \
-o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log
```
Démarrez votre débogueur et configurez-le pour qu'il écoute le numéro de port du processus de débogage.
Vous pouvez maintenant parcourir le code d'Edge Microgateway, définir des points d'arrêt, surveiller des expressions, etc.

Vous pouvez spécifier des options Node.js standards liées au mode débogage. Par exemple, --nolazy aide à déboguer le code asynchrone.

Vérifier les fichiers journaux

En cas de problème, veillez à examiner les fichiers journaux pour obtenir des informations détaillées sur l'exécution et les erreurs. Pour en savoir plus, consultez Gérer les fichiers journaux.

Utiliser la sécurité des clés API

Les clés API fournissent un mécanisme simple pour authentifier les clients qui envoient des requêtes à Edge Microgateway. Vous pouvez obtenir une clé API en copiant la valeur de la clé client (également appelée ID client) à partir d'un produit Apigee Edge qui inclut le proxy d'authentification de la micro passerelle Edge.

Mise en cache des clés

Les clés API sont échangées contre des jetons porteurs, qui sont mis en cache. Vous pouvez désactiver la mise en cache en définissant l'en-tête Cache-Control: no-cache sur les requêtes entrantes vers la micro-passerelle Edge.

Utiliser une clé API

Vous pouvez transmettre la clé API dans une requête API en tant que paramètre de requête ou dans un en-tête. Par défaut, le nom de l'en-tête et du paramètre de requête sont tous deux x-api-key.

Exemple de paramètre de requête:

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

Exemple d'en-tête :

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

Configurer le nom de la clé API

Par défaut, x-api-key est le nom utilisé à la fois pour l'en-tête de clé API et le paramètre de requête. Vous pouvez modifier cette valeur par défaut dans le fichier de configuration, comme expliqué dans la section Modifier la configuration. Par exemple, pour modifier le nom en apiKey:

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

Dans cet exemple, le paramètre de requête et le nom de l'en-tête sont remplacés par apiKey. Le nom x-api-key ne fonctionnera plus dans les deux cas. Consultez également la section Modifier une configuration.

Exemple :

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

Pour en savoir plus sur l'utilisation de clés API avec des requêtes proxy, consultez la section Sécuriser Edge Microgateway.

Activer les codes de réponse en amont

Par défaut, le plug-in oauth ne renvoie que des codes d'état d'erreur 4xx si la réponse n'est pas un état 200. Vous pouvez modifier ce comportement afin qu'il renvoie toujours le code 4xx ou 5xx exact, en fonction de l'erreur.

Pour activer cette fonctionnalité, ajoutez la propriété oauth.useUpstreamResponse: true à la configuration de votre Edge Microgateway. Exemple :

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

Utiliser la sécurité des jetons OAuth2

Cette section explique comment obtenir des jetons d'accès et des jetons d'actualisation OAuth2. Les jetons d'accès permettent d'effectuer des appels d'API sécurisés via la micro-passerelle. Les jetons d'actualisation permettent d'obtenir de nouveaux jetons d'accès.

Obtenir un jeton d'accès

Cette section explique comment utiliser le proxy edgemicro-auth pour obtenir un jeton d'accès.

Vous pouvez également obtenir un jeton d'accès à l'aide de la commande edgemicro token de la CLI. Pour en savoir plus sur la CLI, consultez Gérer les jetons.

API 1: Envoyer des identifiants en tant que paramètres de corps

Remplacez les noms de votre organisation et de votre environnement dans l'URL, et remplacez les valeurs de l'ID client et du secret client obtenues à partir d'une application de développeur sur Apigee Edge par les paramètres de corps client_id et 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: envoyer des identifiants dans un en-tête d'authentification de base

Envoyez les identifiants client en tant qu'en-tête d'authentification de base et le grant_type en tant que paramètre de formulaire. Ce formulaire de commande est également abordé dans la RFC 6749 : The OAuth 2.0 Authorization Framework (RFC 6749 : Le framework d'autorisation OAuth 2.0).

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"

Exemple de résultat

L'API renvoie une réponse JSON. Notez qu'il n'y a aucune différence entre les propriétés token et access_token. Vous pouvez utiliser l'une ou l'autre. Notez que expires_in est une valeur entière spécifiée en secondes.

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

Obtenir un jeton d'actualisation

Pour obtenir un jeton d'actualisation, effectuez un appel d'API au point de terminaison /token du proxy edgemicro-auth. Vous devez effectuer cet appel d'API avec le type d'autorisation password. Les étapes suivantes vous guident tout au long du processus.

Obtenez un jeton d'accès et d'actualisation avec l'API /token. Notez que le type d'autorisation est 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 renvoie un jeton d'accès et un jeton d'actualisation. La réponse ressemble à ceci : Notez que les valeurs expires_in sont des entiers et sont spécifiées en secondes.

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

Vous pouvez désormais utiliser le jeton d'actualisation pour obtenir un nouveau jeton d'accès en appelant le point de terminaison /refresh de la même API. Exemple :

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 renvoie un nouveau jeton d'accès. La réponse se présente comme suit:

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

Surveillance permanente

Supprimé: cette fonctionnalité de la CLI a été supprimée dans la version 3.3.3 de la micro passerelle Edge. Vous pouvez remplacer forever-monitor par PM2. Pour en savoir plus, consultez ce post de la communauté Apigee: Edgemicro + PM2: Démarrer edgemicro en tant que service. Consultez également les notes de version d'Edge Microgateway 3.3.3.

Spécifier un point de terminaison de fichier de configuration

Si vous exécutez plusieurs instances de micro passerelle Edge, vous pouvez gérer leurs configurations à partir d'un seul emplacement. Pour ce faire, spécifiez un point de terminaison HTTP à partir duquel Edge Micro peut télécharger son fichier de configuration. Vous pouvez spécifier ce point de terminaison lorsque vous démarrez Edge Micro à l'aide de l'indicateur -u.

Exemple :

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

où le point de terminaison mgconfig renvoie le contenu de votre fichier de configuration. Il s'agit du fichier qui, par défaut, se trouve dans ~/.edgemicro et qui suit la convention d'attribution de noms : org-env-config.yaml.

Désactivation de la mise en mémoire tampon des données de connexion TCP

Vous pouvez utiliser l'attribut de configuration nodelay pour désactiver le tamponnage de données pour les connexions TCP utilisées par Edge Microgateway.

Par défaut, les connexions TCP utilisent l'algorithme Nagle pour mettre en mémoire tampon les données avant de les envoyer. Définir nodelay sur true désactive ce comportement (les données sont immédiatement envoyées chaque fois que socket.write() est appelé). Pour en savoir plus, consultez également la documentation Node.js.

Pour activer nodelay, modifiez le fichier de configuration Edge Micro comme suit:

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

Exécuter Edge Microgateway en mode autonome

Vous pouvez exécuter Edge Microgateway complètement déconnecté de toute dépendance Apigee Edge. Ce scénario, appelé mode autonome, vous permet d'exécuter et de tester la micro-passerelle Edge sans connexion Internet.

En mode autonome, les fonctionnalités suivantes ne fonctionnent pas, car elles nécessitent une connexion à Apigee Edge:

OAuth et clé API
Quota
Analytics

En revanche, les plug-ins personnalisés et la limitation des pics fonctionnent normalement, car ils ne nécessitent pas de connexion à Apigee Edge. De plus, un nouveau plug-in appelé extauth vous permet d'autoriser les appels d'API à la micro-passerelle avec un jeton JWT en mode autonome.

Configurer et démarrer la passerelle

Pour exécuter Edge Microgateway en mode autonome:

Créez un fichier de configuration nommé comme suit: $HOME/.edgemicro/$ORG-$ENV-config.yaml
Vous pouvez utiliser les valeurs de votre choix pour $ORG et $ENV dans le nom de fichier. La combinaison org/env est simplement une convention qui permet à Edge Microgateway de trouver le fichier au démarrage.

Exemple :
```
vi $HOME/.edgemicro/foo-bar-config.yaml
```
Collez le code suivant dans le fichier :
```
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
```
Le fichier de configuration contient un plug-in spécial et facultatif appelé extauth. Ce plug-in vérifie un jeton JWT valide transmis à la micro-passerelle. À une étape ultérieure, vous apprendrez à obtenir et à utiliser le jeton. Notez également que le plug-in spikearrest est inclus, car il ne dépend pas de la connectivité avec Edge. Les plug-ins quota, oauth et analytics sont exclus, car ils reposent sur la connectivité avec Edge et ne fonctionneront pas en mode déconnecté. Les plug-ins personnalisés sont autorisés et fonctionneront comme prévu.
Exportez la variable d'environnement suivante avec la valeur "1":
```
export EDGEMICRO_LOCAL=1
```
Exécutez la commande start suivante, dans laquelle vous fournissez des valeurs pour instancier le proxy local:
```
edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
  -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH
```
Où :
- $ORG correspond au nom "org" que vous avez utilisé dans le nom du fichier de configuration.
- $ENV est le nom "env" que vous avez utilisé dans le nom du fichier de configuration.
- $LOCAL_PROXY_NAME est le nom du proxy local qui sera créé. Vous pouvez utiliser n'importe quel nom.
- $LOCAL_PROXY_VERSION correspond au numéro de version du proxy.
- $TARGET_URL est l'URL de la cible du proxy. (La cible est le service appelé par le proxy.)
- $BASE_PATH est le chemin de base du proxy. Cette valeur doit commencer par une barre oblique. Pour un chemin d'accès racine, spécifiez simplement une barre oblique, par exemple "/".
Exemple :
```
edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
```
Tester la configuration
```
curl http://localhost:8000/echo  { "error" : "missing_authorization" }
```
Étant donné que le plug-in extauth se trouve dans le fichier foo-bar-config.yaml, une erreur "missing_authorization" s'affiche. Ce plug-in valide un jeton JWT qui doit être présent dans l'en-tête d'autorisation de l'appel d'API. Dans la section suivante, vous obtiendrez un jeton JWT qui permettra aux appels d'API de passer sans erreur.

Exemple: Obtenir un jeton d'autorisation

L'exemple suivant montre comment obtenir un JWT à partir du point de terminaison JWT de la micro passerelle Edge sur Apigee Edge (edgemicro-auth/jwkPublicKeys). Ce point de terminaison est déployé lorsque vous effectuez une configuration standard de la micro passerelle Edge. Pour obtenir le JWT à partir du point de terminaison Apigee, vous devez d'abord configurer la micro-passerelle Edge standard et être connecté à Internet. Le point de terminaison Apigee est utilisé ici à titre d'exemple uniquement et n'est pas obligatoire. Si vous le souhaitez, vous pouvez utiliser un autre point de terminaison de jeton JWT. Si c'est le cas, vous devrez obtenir le jeton JWT à l'aide de l'API fournie pour ce point de terminaison.

L'inclusion du plug-in extauth dans la configuration de votre micro-passerelle est facultative, mais si vous l'incluez, vous devrez fournir un jeton JWT valide dans l'en-tête d'autorisation pour les appels d'API.

Les étapes suivantes expliquent comment obtenir un jeton à l'aide du point de terminaison edgemicro-auth/jwkPublicKeys :

Vous devez effectuer une configuration standard d'Edge Microgateway pour déployer le proxy edgemicro-auth dans votre organisation/environnement sur Apigee Edge. Si vous avez déjà effectué cette étape, vous n'avez pas besoin de la répéter.
Si vous avez déployé la micro passerelle Edge dans Apigee Cloud, vous devez être connecté à Internet pour pouvoir obtenir un JWT à partir de ce point de terminaison.
Arrêtez Edge Microgateway:
```
edgemicro stop
```
Dans le fichier de configuration que vous avez créé précédemment ($HOME/.edgemicro/org-env-config.yaml), pointez l'attribut extauth:publickey_url vers le point de terminaison edgemicro-auth/jwkPublicKeys de votre organisation/environnement Apigee Edge. Exemple :
```
extauth:
  publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
```
Redémarrez Edge Microgateway comme vous l'avez fait précédemment, en utilisant les noms d'organisation/d'environnement que vous avez utilisés dans le nom du fichier de configuration. Exemple :
```
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
```
Obtenez un jeton JWT à partir du point de terminaison d'autorisation. Étant donné que vous utilisez le point de terminaison edgemicro-auth/jwkPublicKeys, vous pouvez utiliser cette commande CLI :
Pour cette étape, vous aurez besoin d'une connexion Internet. La commande suivante extrait un jeton d'Apigee Edge. Pour effectuer cette étape, vous devez disposer d'une organisation Apigee dans laquelle vous avez effectué une configuration et une configuration standard d'Edge Microgateway. Une fois cette étape effectuée, vous n'avez plus besoin d'être connecté à Internet. Le jeton continuera de fonctionner en mode autonome jusqu'à son expiration.

Vous pouvez générer un jeton JWT pour Edge Microgateway à l'aide de la commande edgemicro token ou d'une API. Exemple :

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

Où :

your_org est le nom de votre organisation Apigee pour laquelle vous avez précédemment configuré Edge Microgateway.
your_env est un environnement de l'organisation.
L'option i spécifie la clé client d'une application de développeur dont le produit inclut le proxy edgemicro-auth.
L'option s spécifie le secret client d'une application de développeur dont le produit inclut le proxy edgemicro-auth.

Cette commande demande à Apigee Edge de générer un jeton JWT qui peut ensuite être utilisé pour valider les appels d'API.

Consultez également Générer un jeton.

Tester la configuration autonome

Pour tester la configuration, appelez l'API avec le jeton ajouté dans l'en-tête "Authorization" comme suit:

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

Exemple :

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

Exemple de résultat :

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

Utiliser le mode proxy local

En mode proxy local, Edge Microgateway ne nécessite pas de proxy compatible avec la microgateway à déployer sur Apigee Edge. Vous devez plutôt configurer un "proxy local" en fournissant un nom de proxy local, un chemin de base et une URL cible lorsque vous démarrez la micro passerelle. Les appels d'API à la micro passerelle sont ensuite envoyés à l'URL cible du proxy local. À tous les autres égards, le mode proxy local fonctionne exactement de la même manière que l'exécution de la micro passerelle Edge en mode normal. L'authentification fonctionne de la même manière, tout comme l'arrêt des pics et l'application des quotas, les plug-ins personnalisés, etc.

Les deux différences importantes entre le mode local et la configuration Edge Microgateway standard sont les suivantes: (1) en mode local, vous n'avez pas besoin de créer de proxy compatible avec la microgateway sur Apigee Edge et (2) lorsque vous créez un produit d'API sur Edge, vous ne devez y ajouter qu'un seul proxy, le proxy edgemicro-auth. Vous n'avez pas besoin d'ajouter d'autres proxys au produit.

Cas d'utilisation et exemple

Le mode proxy local est utile lorsque vous n'avez besoin d'associer qu'un seul proxy à une instance de micro passerelle Edge. Par exemple, vous pouvez injecter Edge Microgateway dans Kubernetes en tant que proxy side-car, où une micro passerelle et un service s'exécutent chacun dans un seul pod, et où la micro passerelle gère le trafic vers et depuis son service associé. La figure suivante illustre cette architecture, dans laquelle Edge Microgateway fonctionne comme un proxy sidecar dans un cluster Kubernetes. Chaque instance de micro passerelle ne communique qu'avec un seul point de terminaison sur son service associé:

Edgemicro en tant que side-car

L'un des avantages de ce style d'architecture est qu'Edge Microgateway fournit une gestion des API pour les services individuels déployés dans un environnement de conteneur, tel qu'un cluster Kubernetes.

Configurer le mode proxy local

Pour configurer la micro-passerelle Edge pour qu'elle s'exécute en mode proxy local, procédez comme suit:

Exécutez edgemicro init pour configurer votre environnement de configuration local, exactement comme vous le feriez dans une configuration Edge Microgateway typique. Consultez également la section Configurer Edge Microgateway.
Exécutez edgemicro configure, comme vous le feriez dans une procédure de configuration Edge Microgateway typique. Exemple :
```
edgemicro configure -o your_org -e your_env -u your_apigee_username
```
Cette commande déploie la règle edgemicro-auth sur Edge et renvoie une clé et un secret dont vous aurez besoin pour démarrer la micro passerelle. Si vous avez besoin d'aide, consultez la section Configurer Edge Microgateway.
Sur Apigee Edge, créez un produit d'API avec les exigences de configuration obligatoires suivantes (vous pouvez gérer toutes les autres configurations comme vous le souhaitez) :
- Vous devez ajouter le proxy edgemicro-auth au produit. Ce proxy a été déployé automatiquement lorsque vous avez exécuté edgemicro configure.
- Vous devez fournir un chemin d'accès aux ressources. Apigee recommande d'ajouter ce chemin d'accès au produit: /**. Pour en savoir plus, consultez Configurer le comportement du chemin de ressource. Consultez également Créer des produits d'API dans la documentation Edge.
Sur Apigee Edge, créez un développeur ou utilisez-en un existant si vous le souhaitez. Pour obtenir de l'aide, consultez Ajouter des développeurs à l'aide de l'UI de gestion Edge.
Sur Apigee Edge, créez une application de développeur. Vous devez ajouter le produit d'API que vous venez de créer à l'application. Pour obtenir de l'aide, consultez la section Enregistrer une application dans l'UI de gestion Edge.
Sur la machine où la micro passerelle Edge est installée, exportez la variable d'environnement suivante avec la valeur "1".
```
export EDGEMICRO_LOCAL_PROXY=1
```
Exécutez la commande start suivante :
```
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
```
Où :
- your_org est votre organisation Apigee.
- your_environment est un environnement de votre organisation.
- your_key est la clé renvoyée lorsque vous avez exécuté edgemicro configure.
- your_secret est le secret renvoyé lorsque vous avez exécuté edgemicro configure.
- local_proxy_name est le nom du proxy local qui sera créé.
- local_proxy_version correspond au numéro de version du proxy.
- target_url est l'URL de la cible du proxy (le service que le proxy appellera).
- base_path est le chemin de base du proxy. Cette valeur doit commencer par une barre oblique. Pour un chemin d'accès racine, spécifiez simplement une barre oblique, par exemple "/".
Exemple :
```
edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
  -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
  -t http://mocktarget.apigee.net -b /echo
```

Tester la configuration

Vous pouvez tester la configuration du proxy local en appelant le point de terminaison du proxy. Par exemple, si vous avez spécifié un chemin de base /echo, vous pouvez appeler le proxy comme suit:

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

Cet appel d'API initial a généré une erreur, car vous n'avez pas fourni de clé API valide. Vous trouverez la clé dans l'application de développement que vous avez créée précédemment. Ouvrez l'application dans l'UI Edge, copiez la clé client, puis utilisez-la comme suit:

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

Exemple :

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

Exemple de résultat :

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

Utiliser le synchroniseur

Cette section explique comment utiliser le synchroniseur, une fonctionnalité facultative qui améliore la résilience d'Edge Microgateway en lui permettant de récupérer des données de configuration à partir d'Apigee Edge et de les écrire dans une base de données Redis locale. Lorsqu'une instance de synchroniseur est en cours d'exécution, les autres instances de micro-passerelle Edge exécutées sur différents nœuds peuvent récupérer leur configuration directement à partir de cette base de données.

La fonctionnalité de synchroniseur est actuellement compatible avec Redis 5.0.x.

Qu'est-ce que le synchronisateur ?

Le synchroniseur offre un niveau de résilience pour Edge Microgateway. Il permet de s'assurer que chaque instance d'Edge Microgateway utilise la même configuration et que, en cas d'interruption d'Internet, les instances d'Edge Microgateway peuvent démarrer et s'exécuter correctement.

Par défaut, les instances Edge Microgateway doivent pouvoir communiquer avec Apigee Edge pour récupérer et actualiser leurs données de configuration, telles que les configurations de proxy d'API et de produits d'API. Si la connexion Internet avec Edge est interrompue, les instances de micro-passerelle peuvent continuer à fonctionner, car les dernières données de configuration sont mises en cache. Toutefois, les nouvelles instances de micro-passerelle ne peuvent pas démarrer sans une connexion claire. De plus, une interruption d'Internet peut entraîner l'exécution d'une ou de plusieurs instances de micro-passerelle avec des informations de configuration qui ne sont pas synchronisées avec les autres instances.

Le synchroniseur Edge Microgateway fournit un mécanisme alternatif permettant aux instances Edge Microgateway de récupérer les données de configuration dont elles ont besoin pour démarrer et traiter le trafic de proxy d'API. Les données de configuration récupérées à partir des appels à Apigee Edge incluent l'appel jwk_public_keys, l'appel jwt_public_key, l'appel de démarrage et l'appel des produits d'API. Le synchroniseur permet à toutes les instances Edge Microgateway exécutées sur différents nœuds de démarrer correctement et de rester synchronisées, même si la connexion Internet entre Edge Microgateway et Apigee Edge est interrompue.

Le synchroniseur est une instance d'Edge Microgateway spécialement configurée. Son seul but est d'interroger Apigee Edge (le timing est configurable), de récupérer les données de configuration et de les écrire dans une base de données Redis locale. L'instance du synchroniseur elle-même ne peut pas traiter le trafic du proxy d'API. D'autres instances de micro passerelle Edge exécutées sur différents nœuds peuvent être configurées pour récupérer des données de configuration à partir de la base de données Redis plutôt que d'Apigee Edge. Étant donné que toutes les instances de micro passerelle extraient leurs données de configuration à partir de la base de données locale, elles peuvent démarrer et traiter les requêtes d'API même en cas d'interruption d'Internet.

Configurer une instance de synchronisateur

Ajoutez la configuration suivante au fichier org-env/config.yaml pour l'installation Edge Microgateway que vous souhaitez utiliser comme synchroniseur:

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

Exemple :

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

Option	Description
`redisHost`	Hôte sur lequel votre instance Redis s'exécute. Valeur par défaut: 127.0.0.1
`redisPort`	Port de l'instance Redis. Valeur par défaut: 6379
`redisDb`	Base de données Redis à utiliser. Valeur par défaut : 0
`redisPassword`	Votre mot de passe de base de données.

Vous pouvez utiliser la variable d'environnement EDGEMICRO_REDIS_PASSWORD pour remplacer le paramètre edgemicro.redisPassword. Consultez également Définir des attributs de configuration avec des valeurs de variable d'environnement.

Enfin, enregistrez le fichier de configuration et démarrez l'instance Edge Microgateway. Il commence à interroger Apigee Edge et à stocker les données de configuration téléchargées dans la base de données Redis.

Configurer des instances Edge Microgateway standards

Lorsque le synchroniseur est en cours d'exécution, vous pouvez configurer des nœuds de micro passerelle Edge supplémentaires pour exécuter des instances de micro passerelles standards qui traitent le trafic de proxy d'API. Toutefois, vous devez configurer ces instances pour qu'elles obtiennent leurs données de configuration à partir de la base de données Redis plutôt que d'Apigee Edge.

Ajoutez la configuration suivante au fichier org-env/config.yaml de chaque nœud de micro passerelle Edge supplémentaire. Notez que la propriété synchronizerMode est définie sur 0. Cette propriété définit l'instance pour qu'elle fonctionne comme une instance Microgateway Edge normale qui traite le trafic de proxy d'API. L'instance obtiendra ses données de configuration à partir de la base de données Redis.

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

Exemple :

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

Propriétés de configuration

Les propriétés de configuration suivantes ont été ajoutées pour prendre en charge l'utilisation du synchroniseur:

Attribut Valeurs Description

Attribut	Valeurs	Description
`edge_config.synchronizerMode`	0 ou 1	Si la valeur est 0 (par défaut), Edge Microgateway fonctionne en mode standard. Si la valeur est 1, démarrez l'instance Edge Microgateway pour qu'elle fonctionne en tant que synchroniseur. Dans ce mode, l'instance extrait les données de configuration d'Apigee Edge et les stocke dans une base de données Redis locale. Cette instance n'est pas en mesure de traiter les requêtes de proxy d'API. Son seul but est d'interroger Apigee Edge pour obtenir des données de configuration et de les écrire dans la base de données locale. Vous devez ensuite configurer d'autres instances de micro passerelle pour qu'elles lisent à partir de la base de données.
`edge_config.redisBasedConfigCache`	True ou False	Si la valeur est "true", l'instance Edge Microgateway extrait ses données de configuration à partir de la base de données Redis plutôt que d'Apigee Edge. La base de données Redis doit être la même que celle sur laquelle le synchroniseur est configuré pour écrire. Si la base de données Redis n'est pas disponible ou si elle est vide, la micropasserelle recherche un fichier `cache-config.yaml` existant pour sa configuration. Si la valeur est "false" (valeur par défaut), l'instance Edge Microgateway extrait les données de configuration d'Apigee Edge comme d'habitude.
`edgemicro.config_change_poll_interval`	Intervalle de temps, en secondes	Indique l'intervalle d'interrogation pour que le synchronisateur extrait les données d'Apigee Edge.

edge_config.synchronizerMode

0 ou 1

Si la valeur est 0 (par défaut), Edge Microgateway fonctionne en mode standard.

Si la valeur est 1, démarrez l'instance Edge Microgateway pour qu'elle fonctionne en tant que synchroniseur. Dans ce mode, l'instance extrait les données de configuration d'Apigee Edge et les stocke dans une base de données Redis locale. Cette instance n'est pas en mesure de traiter les requêtes de proxy d'API. Son seul but est d'interroger Apigee Edge pour obtenir des données de configuration et de les écrire dans la base de données locale. Vous devez ensuite configurer d'autres instances de micro passerelle pour qu'elles lisent à partir de la base de données.

edge_config.redisBasedConfigCache

True ou False

Si la valeur est "true", l'instance Edge Microgateway extrait ses données de configuration à partir de la base de données Redis plutôt que d'Apigee Edge. La base de données Redis doit être la même que celle sur laquelle le synchroniseur est configuré pour écrire. Si la base de données Redis n'est pas disponible ou si elle est vide, la micropasserelle recherche un fichier cache-config.yaml existant pour sa configuration.

Si la valeur est "false" (valeur par défaut), l'instance Edge Microgateway extrait les données de configuration d'Apigee Edge comme d'habitude.

edgemicro.config_change_poll_interval Intervalle de temps, en secondes Indique l'intervalle d'interrogation pour que le synchronisateur extrait les données d'Apigee Edge.

Configurer des URL d'exclusion pour les plug-ins

Vous pouvez configurer la micro passerelle pour ignorer le traitement des plug-ins pour les URL spécifiées. Vous pouvez configurer ces URL "d'exclusion" globalement (pour tous les plug-ins) ou pour des plug-ins spécifiques.

Exemple :

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

Dans cet exemple, les plug-ins ne traiteront pas les appels de proxy d'API entrants avec les chemins /hello ou /proxy_one. De plus, le plug-in json2xml sera ignoré pour les API dont le chemin d'accès contient /hello/xml.

Vous ne pouvez pas exclure le plug-in analytics.

Définir des attributs de configuration avec des valeurs de variable d'environnement

Vous pouvez spécifier des variables d'environnement à l'aide de balises dans le fichier de configuration. Les balises de variable d'environnement spécifiées sont remplacées par les valeurs réelles de la variable d'environnement. Les remplacements sont stockés en mémoire uniquement et non dans les fichiers de configuration ou de cache d'origine.

Remarque : Par défaut, la balise <E> analyse les valeurs des variables en tant que chaînes. Pour spécifier des valeurs booléennes et des entiers positifs, utilisez les balises <n> et <b> internes, comme illustré dans les exemples ci-dessous.

Dans cet exemple, l'attribut key est remplacé par la valeur de la variable d'environnement TARGETS_SSL_CLIENT_KEY, etc.

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

Dans cet exemple, la balise <n> permet d'indiquer une valeur entière. Seuls les entiers positifs sont acceptés.

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

Dans cet exemple, la balise <b> est utilisée pour indiquer une valeur booléenne (c'est-à-dire "true" ou "false").

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