Utiliser des plug-ins

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

Edge Microgateway v. 2.4.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 répertoire de préfixe npm. Consultez la section Où est installé Edge Microgateway ?

[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 Modifier la configuration des 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 le stanza suivant 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é, comme expliqué dans Modifier la configuration.

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 ?

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

Cette section traite du plug-in d'arrêt des pics.

À propos de l'arrêt des pics

L'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. Pour en savoir plus, consultez la section Comment fonctionne l'arrêt des pics ? Consultez également la section Quelle est la différence entre l'arrêt des pics et le quota ?.

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

Pour connaître les étapes de base à suivre pour n'importe quel plug-in, 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.
• 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 requêtes. 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 réduit 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 des intervalles de requêtes autorisées exprimés en secondes. Par exemple, 30 requêtes par minute sont lissées 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 des intervalles de requêtes autorisées exprimés en millisecondes. Par exemple, 10 requêtes/seconde sont lissées 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'alerte de pic 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éfinissiez 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 bufferSize est 0.

Utiliser le plug-in de quota

Cette section traite du plug-in de quota.

À propos du 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

Pour connaître les étapes de base à suivre pour n'importe quel plug-in, 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

Il n'existe aucune option de configuration supplémentaire pour le plug-in de quota.

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 au cours d'une heure, d'une journée, d'une semaine ou d'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. Consultez également la section Utiliser le plug-in de quota.

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.