Utiliser des plug-ins

Vous consultez la documentation Apigee Edge.
Accédez à la documentation**Apigee X**. info

Edge Microgateway v. 3.0.x

Audience

Cet article est destiné aux opérateurs d'Edge Microgateway qui souhaitent utiliser les plug-ins existants qui sont installés avec le microgateway. Il aborde également en détail les plug-ins d'arrêt des pics et de quota (tous deux inclus dans l'installation). Si vous êtes un développeur qui souhaite développer de nouveaux plug-ins, consultez la section Développer des plug-ins personnalisés.

Qu'est-ce qu'un plug-in Edge Microgateway ?

Un plug-in est un module Node.js qui ajoute des fonctionnalités à Edge Microgateway. Les modules de plug-in suivent un modèle cohérent et sont stockés dans un emplacement connu d'Edge Microgateway, ce qui permet au microgateway de les détecter et de les charger automatiquement. Edge Microgateway inclut plusieurs plug-ins existants . Vous pouvez également créer des plug-ins personnalisés, comme expliqué dans la section Développer des plug-ins personnalisés.

Plug-ins existants fournis avec Edge Microgateway

Plusieurs plug-ins existants sont fournis avec Edge Microgateway lors de l'installation. Par exemple :

Où trouver les plug-ins existants

Les plug-ins existants fournis avec Edge Microgateway se trouvent ici, où [prefix] est le npm répertoire de préfixe. Consultez la section Où est installé Edge Microgateway si vous ne trouvez pas ce répertoire.

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

Ajouter et configurer des plug-ins

Suivez ce modèle pour ajouter et configurer des plug-ins :

1. Arrêtez Edge Microgateway.
2. Ouvrez un fichier de configuration Edge Microgateway. Pour en savoir plus, consultez la section Apporter des modifications de configuration pour les options.
3. Ajoutez le plug-in à l'élément plugins:sequence du fichier de configuration, comme suit. Les plug-ins sont exécutés dans l'ordre dans lequel ils apparaissent dans cette liste.

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
     level: info
     dir: /var/tmp
     stats_log_interval: 60
  plugins:
     dir: ../plugins
     sequence:   
     - oauth
     - plugin-name

4. Configurez le plug-in. Certains plug-ins comportent des paramètres facultatifs que vous pouvez configurer dans le fichier de configuration. Par exemple, vous pouvez ajouter la strophe suivante pour configurer le plug-in d'arrêt des pics. Pour en savoir plus, consultez la section Utiliser le plug-in d'arrêt des pics.

   edgemicro:
     home: ../gateway
     port: 8000
     max_connections: -1
     max_connections_hard: -1
     logging:
       level: info
       dir: /var/tmp
       stats_log_interval: 60
     plugins:
       dir: ../plugins
       sequence:
         - oauth
         - spikearrest
   spikearrest:
      timeUnit: minute
      allow: 10

5. Enregistrez le fichier.
6. Redémarrez ou rechargez Edge Microgateway, selon le fichier de configuration que vous avez modifié.

Configuration spécifique à un plug-in

Vous pouvez remplacer les paramètres de plug-in spécifiés dans le fichier de configuration en créant une configuration spécifique à un plug-in dans le répertoire suivant :

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

où [prefix] est le répertoire de préfixe npm. Consultez la section Où est installé Edge Microgateway si vous ne trouvez pas ce répertoire.

plugins/<plugin_name>/config/default.yaml. Par exemple, vous pouvez placer ce bloc dans plugins/spikearrest/config/default.yaml, et il remplacera tous les autres paramètres de configuration.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Utiliser le plug-in d'arrêt des pics

Le plug-in d'arrêt des pics protège contre les pics de trafic. Il limite le nombre de requêtes traitées par une instance Edge Microgateway.

Ajouter le plug-in d'arrêt des pics

Consultez la section Ajouter et configurer des plug-ins.

Exemple de configuration pour l'arrêt des pics

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
   bufferSize: 5

Options de configuration pour l'arrêt des pics

• timeUnit : fréquence à laquelle la fenêtre d'exécution de l'arrêt des pics est réinitialisée. Les valeurs valides sont "second" ou "minute".
• allow : nombre maximal de requêtes à autoriser pendant la période timeUnit. Consultez également la section Si vous exécutez plusieurs processus Edge Micro processes.
• bufferSize : (facultatif, valeur par défaut = 0) si bufferSize > 0, l'arrêt des pics stocke ce nombre de requêtes dans un tampon. Dès que la fenêtre d'exécution suivante se produit, les requêtes mises en mémoire tampon sont traitées en premier. Consultez également la section Ajouter un tampon.

Comment fonctionne l'arrêt des pics ?

Considérez l'arrêt des pics comme un moyen de protection générale contre les pics de trafic plutôt que comme un moyen de limiter le trafic à un nombre spécifique de demandes. Vos API et votre backend peuvent gérer une certaine quantité de trafic, tandis que la règle d'arrêt des pics vous aide à fluidifier le trafic en fonction des volumes généraux que vous souhaitez.

Le comportement à l'exécution de l'arrêt des pics diffère de ce que l'on pourrait attendre des valeurs littérales par minute ou par seconde que vous entrez.

Par exemple, supposons que vous spécifiez un débit de 30 requêtes par minute, comme suit :

spikearrest:
   timeUnit: minute
   allow: 30

Lors des tests, vous pouvez penser que vous pouvez envoyer 30 requêtes en 1 seconde, à condition qu'elles soient envoyées en une minute. Mais ce n'est pas ainsi que la règle applique le paramètre. Si vous y réfléchissez, 30 requêtes sur une période d'une seconde peuvent être considérées comme un mini-pic dans certains environnements.

Que se passe-t-il donc réellement ? Pour éviter les situations de pics, l'arrêt des pics lisse le trafic autorisé en divisant vos paramètres en intervalles plus petits, comme suit :

Débits par minute

Les débits par minute sont lissés pour obtenir un nombre de requêtes autorisées par intervalles exprimés en secondes. Par exemple, un débit de 30 requêtes par minute est lissé comme suit :

60 secondes (une minute) / 30 = 2 secondes, soit environ une requête autorisée toutes les deux secondes. Une deuxième requête dans un intervalle de 2 secondes échouera. De même, une 31e requête en une minute échouera.

Débits par seconde

Les débits par seconde sont lissés pour obtenir un nombre de requêtes autorisées par intervalles exprimés en millisecondes. Par exemple, un débit de 10 requêtes/seconde est lissé comme suit :

1 000 millisecondes (1 seconde) / 10 = 100 millisecondes d'intervalles, soit environ une requête autorisée toutes les 100 millisecondes . Une deuxième requête dans un intervalle de 100 ms échouera. De même, une 11e requête en une seconde échouera.

Lorsque la limite est dépassée

Si le nombre de requêtes dépasse la limite dans l'intervalle de temps spécifié, l'arrêt des pics renvoie le message d'erreur suivant avec un état HTTP 503 :

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

Ajouter un tampon

Vous avez la possibilité d'ajouter un tampon à la règle. Supposons que vous définissez le tampon sur 10. Vous constaterez que l'API ne renvoie pas d'erreur immédiatement lorsque vous dépassez la limite d'arrêt des pics. Au lieu de cela, les requêtes sont mises en mémoire tampon (jusqu'au nombre spécifié), et les requêtes mises en mémoire tampon sont traitées dès que la fenêtre d'exécution appropriée suivante est disponible. La valeur par défaut de bufferSize est 0.

Si vous exécutez plusieurs processus Edge Micro

Le nombre de requêtes autorisées dépend du nombre de processus de nœud de calcul Edge Micro en cours d'exécution. L'arrêt des pics calcule le nombre de requêtes autorisées par processus de nœud de calcul. Par défaut, le nombre de processus Edge Micro est égal au nombre de processeurs sur la machine où Edge Micro est installé. Toutefois, vous pouvez configurer le nombre de processus de nœud de calcul lorsque vous démarrez Edge Micro à l'aide de l'option --processes de la commande start. Par exemple, si vous souhaitez que l'arrêt des pics se déclenche à 100 requêtes sur une période donnée et que vous démarrez Edge Microgateway avec l'option --processes 4, définissez allow: 25 dans la configuration d'arrêt des pics. En résumé, la règle générale consiste à définir le allow paramètre de configuration sur la valeur "nombre d'arrêts des pics souhaité / nombre de processus".

Utiliser le plug-in de quota

Un quota spécifie le nombre de messages de requêtes qu'une application est autorisée à envoyer à une API au cours d'une heure, d'une journée, d'une semaine ou d'un mois. Lorsqu'une application atteint sa limite de quota, les appels d'API suivants sont rejetés. Consultez également la section Quelle est la différence entre l'arrêt des pics et le quota ?

Ajouter le plug-in de quota

Consultez la section Ajouter et configurer des plug-ins.

Configuration du produit dans Apigee Edge

Vous configurez les quotas dans l'interface utilisateur Apigee Edge, où vous configurez les produits d'API. Vous devez savoir quel produit contient le proxy compatible avec le microgateway que vous souhaitez limiter avec un quota. Ce produit doit être ajouté à une application de développeur. Lorsque vous effectuez des appels d'API authentifiés à l'aide de clés dans l'application de développeur, le quota est appliqué à ces appels d'API.

1. Connectez-vous à votre compte d'organisation Apigee Edge.
2. Dans l'interface utilisateur Edge, ouvrez le produit associé au proxy compatible avec le microgateway auquel vous souhaitez appliquer le quota.
   1. Dans l'interface utilisateur, sélectionnez Produits dans le menu "Publier".
   2. Ouvrez le produit contenant l'API à laquelle vous souhaitez appliquer le quota.
   3. Cliquez sur Modifier.
   4. Dans le champ "Quota", spécifiez l'intervalle de quota. Par exemple, 100 requêtes toutes les minutes. Ou 50 000 requêtes toutes les deux heures.
      
      

3. Cliquez sur Enregistrer.
4. Assurez-vous que le produit est ajouté à une application de développeur. Vous aurez besoin des clés de cette application pour effectuer des appels d'API authentifiés.

Exemple de configuration pour le quota

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota

Options de configuration pour le quota

Pour configurer le plug-in de quota, ajoutez l'élément quotas à votre fichier de configuration, comme illustré dans l'exemple suivant :

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota
quotas:
  bufferSize:
    hour: 20000
    minute: 500
    month: 1
    default: 10000
  useDebugMpId: true
  failOpen: true
  useRedis: true
  redisHost: localhost
  redisPort: 6379
  redisDb: 1
...

edgemicro:
...
quotas:
  failOpen: true

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

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}

Comprendre la portée du quota

Le nombre de quotas est limité à un produit d'API. Si une application de développeur comporte plusieurs produits, le quota est limité à chacun d'eux individuellement. Pour atteindre cette portée, Edge Microgateway crée un identifiant de quota qui combine "appName + productName".

Tester le plug-in de quota

Lorsque le quota est dépassé, un état HTTP 403 est renvoyé au client, ainsi que le message suivant :

{"error": "exceeded quota"}

Quelle est la différence entre l'arrêt des pics et le quota ?

Il est important de choisir le bon outil pour la tâche à accomplir. Les règles de quota configurent le nombre de messages de requête qu'une application cliente est autorisée à envoyer à une API pendant une heure, un jour, une semaine ou un mois. La règle de quota applique des limites de consommation aux applications clientes en alimentant un compteur distribué du nombre de requêtes entrantes.

Utilisez une règle de quota pour appliquer des contrats d'entreprise ou des contrats de niveau de service vis-à-vis de développeurs et de partenaires, plutôt que pour la gestion du trafic opérationnel. Par exemple, un quota peut être utilisé pour limiter le trafic à un service sans frais, tout en autorisant l'accès complet aux clients payants.

Utilisez l'arrêt des pics comme protection contre les pics soudains du trafic de l'API. En règle générale, l'arrêt des pics est utilisé pour éviter d'éventuelles attaques DDoS ou d'autres attaques malveillantes.