Utiliser des plug-ins

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X.
En savoir plus

Edge Microgateway version 3.1.5 et ultérieure

Audience

Cette rubrique est destinée aux opérateurs Edge Microgateway qui souhaitent utiliser des plug-ins existants qui sont installées avec la micropasserelle. Il aborde également l'arrêt des pics et les plug-ins de quota dans (les deux sont incluses dans l'installation). Si vous êtes développeur et souhaitez développer 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. Modules de plug-ins suivent un schéma cohérent et sont stockés dans un emplacement connu d'Edge Microgateway, microgateway afin de les détecter et de les charger automatiquement. Edge Microgateway inclut plusieurs Vous pouvez aussi créer des plug-ins personnalisés, comme expliqué dans l'article Développer des plug-ins personnalisés.

Plug-ins existants fournis avec Edge Micropasserelle

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

Plug-in Activé par défaut Description
analytics Oui Envoie des données d'analyse d'Edge Microgateway à Apigee Edge.
oauth Oui Ajout de la validation du jeton OAuth et de la clé API à Edge Microgateway Reportez-vous à la section Paramètre et configurer Edge Microgateway.
quota Non Applique des quotas sur les requêtes envoyées à Edge Microgateway. Utilise Apigee Edge pour stocker et gérer les quotas. Consultez la section Utiliser le plug-in de quota.
spikearrest Non Protège contre les pics de trafic et les attaques DoS. Consultez la section Utiliser le plug-in d'arrêt des pics.
en-tête en majuscules Non Exemple de proxy commenté, conçu comme un guide pour aider les développeurs à créer des plug-ins personnalisés. Voir <ph type="x-smartling-placeholder"></ph> Exemple de plug-in Edge Microgateway
accumulate-request Non Les données de requête sont agrégées dans un seul objet avant de les transmettre au dans la chaîne de plug-ins. Utile pour écrire des plug-ins de transformation qui doivent fonctionner sur un objet de contenu de requête unique et cumulé.
accumulate-response Non Les données de réponse sont accumulées dans un seul objet avant de les transmettre au dans la chaîne de plug-ins. Utile pour écrire des plug-ins de transformation qui doivent fonctionner sur un objet de contenu de réponse unique et cumulé.
transform-uppercase Non Transforme les données de requête ou de réponse. Ce plug-in est une bonne pratique l'implémentation d'un plug-in de transformation. L'exemple de plug-in effectue une transformation simple (convertit les données de requête ou de réponse en majuscules) ; mais il peut facilement être adapté effectuer d'autres types de transformations, telles que XML vers JSON.
json2xm Non Transforme les données de requête ou de réponse en fonction d'en-têtes d'acceptation ou de type de contenu. Pour plus de détails, reportez-vous à la documentation dans GitHub.
quota-memory Non Applique des quotas sur les requêtes envoyées à Edge Microgateway. Stocke et gère les quotas en local mémoire.
vérification de l'état Non Renvoie des informations sur le processus Edge Microgateway : utilisation de la mémoire, utilisation du CPU, etc. Pour utiliser le plug-in, appelez l'URL /healthcheck sur votre appareil Edge. Instance Microgateway. Ce plug-in est destiné à être un exemple que vous pouvez utiliser pour implémenter votre propre plug-in de vérification de l'état.

Où trouver les plug-ins existants ?

Les plug-ins existants fournis avec Edge Microgateway se trouvent ici, où [prefix] est le répertoire avec préfixe npm. Voir <ph type="x-smartling-placeholder"></ph> Où Edge Microgateway est-il installé si vous ne trouvez pas ce répertoire.

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

Ajouter et configurer des plug-ins

Suivez le schéma ci-dessous pour ajouter et configurer des plug-ins:

  1. Arrêtez Edge Microgateway.
  2. Ouvrez un fichier de configuration Edge Microgateway. Pour plus d'informations, voir 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
  1. 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 bloc suivant pour configurer l'arrêt des pics . Consultez la section Utiliser le plug-in d'arrêt des pics. pour en savoir plus.
    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
    
  1. Enregistrez le fichier.
  2. Redémarrez ou actualisez Edge Microgateway, en fonction du fichier de configuration que vous avez modifié.

Configuration spécifique aux plug-ins

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

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

[prefix] est le répertoire avec préfixe npm. Voir <ph type="x-smartling-placeholder"></ph> Où Edge Microgateway est-il installé si vous ne trouvez pas ce répertoire.

plugins/<plugin_name>/config/default.yaml Par exemple, vous pouvez indiquer dans plugins/spikearrest/config/default.yaml, et remplaceront tout autre 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 vous protège contre les pics de trafic. Elle limite le nombre de requêtes 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 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 arrêt des pics

  • timeUnit: fréquence à laquelle la fenêtre d'exécution de l'arrêt des pics se réinitialise. Valeurs valides sont des secondes ou des minutes.
  • allow: nombre maximal de requêtes à autoriser pendant une unité de temps (timeUnit). Voir Si vous utilisez plusieurs appareils Edge Micro processus.
  • bufferSize: (facultatif, valeur par défaut = 0) si bufferSize > 0, 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, le les requêtes mises en mémoire tampon seront traitées en premier. Reportez-vous également à la section Ajouter un tampon.

Comment fonctionne l'arrêt des pics ?

Considérez l'arrêt des pics comme un moyen de se protéger généralement contre les pics de trafic, moyen de limiter le trafic à un nombre spécifique de requêtes. Vos API et votre backend peuvent gérer une certaine la quantité de trafic, et la politique d'arrêt des pics vous aide à fluidifier le trafic vers les montants généraux de votre choix.

Le comportement d'arrêt des pics d'exécution diffère de ce que vous pouvez vous attendre à voir avec le littéral les valeurs par minute ou par seconde que vous saisissez.

Par exemple, supposons que vous spécifiiez une fréquence de 30 requêtes par minute, comme ceci:

spikearrest:
   timeUnit: minute
   allow: 30

Lors des tests, vous pourriez penser que vous pourriez envoyer 30 requêtes en 1 seconde, à condition qu'elles arrivent en l'espace d'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 peut être considérée comme un mini pic dans certains environnements.

Que se passe-t-il donc réellement ? Pour éviter tout comportement ressemblant à des pics, l'arrêt des pics atténue les en divisant vos paramètres en intervalles plus petits, comme suit:

Tarifs à la minute

Les tarifs à la minute sont lissés en intervalles de requêtes autorisés (en secondes). Par exemple, 30 les requêtes par minute sont lissées comme ceci:

60 secondes (1 minute) / 30 = intervalles de deux secondes, soit environ 1 requête autorisée toutes les deux secondes. A une seconde demande en moins de deux secondes échouera. De plus, toute 31e requête dans un délai d'une minute échouera.

Tarifs à la seconde

Les tarifs à la seconde sont lissés aux requêtes autorisées en intervalles de quelques millisecondes. Par exemple : 10 requêtes par seconde sont lissées comme ceci:

1 000 millisecondes (1 seconde) / 10 = intervalles de 100 millisecondes, soit environ 1 requête autorisée toutes les 100 millisecondes . Une deuxième requête dans un intervalle de 100 ms échouera. Par ailleurs, une 11e demande dans 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é, arrêt des pics renvoie ce message d'erreur 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 verrez que l'API ne renvoie pas d'erreur immédiatement lorsque vous dépassez l'arrêt des pics. limite. À la place, les requêtes sont mises en mémoire tampon (dans la limite du nombre spécifié) sont traités dès que la prochaine fenêtre d'exécution appropriée est disponible. La valeur par défaut bufferSize est défini sur 0.

Si vous utilisez plusieurs Edge Micro processus

Le nombre de requêtes autorisées dépend du nombre de processus de nœud de calcul Edge Micro actuellement en cours d'exécution. L'arrêt des pics calcule le nombre autorisé de requêtes 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és. 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 sur la commande start. Par exemple, si vous que l'arrêt des pics se déclenche pour 100 requêtes sur une période donnée, et que si vous démarrez Edge Microgateway avec l'option --processes 4, puis définissez allow: 25 dans Configuration de l'arrêt des pics. En résumé, la règle de base consiste à définir la configuration allow. sur la valeur "nombre d'arrêts des pics souhaité / nombre de processus souhaité".

Utiliser le plug-in de quota

Un quota spécifie le nombre de messages de requête 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 ressources suivantes Les appels d'API sont rejetés. Consultez également l'article Quelle est la différence entre l'arrêt des pics et les quotas.

Ajouter le plug-in de quota

Consultez la section Ajouter et configurer des plug-ins.

Configuration du produit dans Apigee Périphérie

La configuration des quotas s'effectue dans l'interface utilisateur d'Apigee Edge, où vous configurez les produits d'API. Vous devez savoir le produit contenant le proxy compatible avec la micropasserelle que vous souhaitez limiter avec un quota. Ce doit être ajouté à une application de développement. Lorsque vous effectuez des appels d'API authentifiés à l'aide de dans l'application de développement, 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 la micropasserelle vers lequel 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 par tranche une minute. soit 50 000 requêtes toutes les deux heures.

  1. Cliquez sur Enregistrer.
  2. Assurez-vous que le produit est ajouté à une application de développement. Vous aurez besoin des clés de cette appli pour créer des appels d'API authentifiés.

Exemple de configuration de 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 les quotas

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
...
Option Description
bufferSize

(Entier) La configuration bufferSize vous permet d'ajuster la fréquence à laquelle Edge Microgateway synchronise son quota avec Apigee Edge. Pour comprendre bufferSize, prenez l'exemple de configuration suivant:

quotas:
 bufferSize:
  minute: 500
  default: 10000
 useDebugMpId: true
 failOpen: true

Par défaut, la micropasserelle synchronise son compteur de quota avec Apigee Edge toutes les 5 secondes si l'intervalle de quota est défini sur "minute". La configuration ci-dessus indique que si l'intervalle de quota est défini dans le produit API pour "minute", Edge Microgateway se synchronisera avec Edge pour obtenir le nombre de quotas actuel après chaque 500 requêtes ou après cinq secondes (selon la première échéance atteinte). Pour plus d'informations, consultez la section Comprendre le calcul des quotas.

Durée autorisée unités possibles: minute, hour, day, week, month et default.

failOpen Lorsque cette fonctionnalité est activée, en cas d'erreur de traitement des quotas ou si le paramètre "quota s'applique" à Edge l'échec de la mise à jour des compteurs de quota distants, le quota seront traités sur la base de décomptes locaux jusqu'au prochain quota distant réussi la synchronisation est effectuée. Dans les deux cas, un indicateur quota-failed-open est défini dans l'objet de la requête.

Pour activer le quota de type "fail open" : définissez la configuration suivante:

edgemicro:
...
quotas:
  failOpen: true
...
useDebugMpId Définissez cet indicateur sur true pour activer la journalisation du MP. ID (processeur de messages) dans les réponses de quota.

Pour utiliser cette fonctionnalité, vous devez définir la configuration suivante:

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

Lorsque useDebugMpId est défini, les réponses de quota d'Edge contiennent l'ID du MP. et sera consignée par Edge Microgateway. Exemple :

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}
useRedis Si la valeur est true, le plug-in utilise Redis pour le magasin de sauvegarde de quota. Pour en savoir plus, consultez la section Utiliser un magasin de sauvegarde Redis pour le quota.

Comprendre comment les quotas sont calculés

Par défaut, la micropasserelle synchronise son compteur de quota avec Apigee Edge toutes les 5 secondes si l'intervalle de quota est défini sur "minute". Si l'intervalle est défini sur un niveau supérieur à "minute" (par exemple, "semaine") ou "mois", la période d'actualisation par défaut est d'une minute.

Notez que vous spécifiez des intervalles de quota dans les produits d'API définis sur Apigee Edge. Les intervalles de quota spécifient le nombre de requêtes autorisées pour une minute, une heure, un jour, une semaine ou un mois. Par exemple, le produit A peut avoir un intervalle de quota de 100 requêtes par minute et le produit B peuvent avoir un intervalle de quota de 10 000 requêtes par heure.

Fichier YAML du plug-in Edge Microgateway quota la configuration ne définit pas le quota interval; mais plutôt d'ajuster la fréquence à laquelle une passerelle Edge Microgateway locale l'instance synchronise son quota avec Apigee Edge.

Par exemple, supposons que trois produits d'API soient définis dans Apigee Edge avec les éléments suivants : intervalles de quota spécifiés:

  • Le produit A dispose d'un quota de 100 requêtes par minute.
  • Le produit B a un quota de 5 000 requêtes par heure
  • Le produit C dispose d'un quota de 1 000 000 requêtes par mois.

Avec ces paramètres de quota à l'esprit, comment le plug-in Edge Microgateway quota doit-il être configurés ? Il est recommandé de configurer Edge Microgateway avec des intervalles de synchronisation sont inférieurs aux intervalles de quota définis dans les produits d'API. Exemple :

quotas:
    bufferSize:
      hour: 2000
      minute: 50
      month: 1
      default: 10000

Cette configuration définit les intervalles de synchronisation suivants pour les produits d'API décrits précédemment:

  • Le produit A est défini sur la "minute" l'intervalle. Edge Microgateway se synchronisera avec Edge après toutes les 50 requêtes ou toutes les 5 secondes, selon la première échéance atteinte.
  • Le produit B est défini sur "heure" l'intervalle. Edge Microgateway se synchronisera avec Edge après toutes les 2 000 requêtes ou toutes les minutes, selon la première échéance atteinte.
  • Le produit C est défini sur "mois" l'intervalle. Edge Microgateway se synchronisera avec Edge après à chaque requête ou à une minute, selon la première échéance atteinte.

Chaque fois qu'une instance de microgateway se synchronise avec Edge, Le nombre de quotas est défini sur le nombre de quotas récupérés.

Les paramètres bufferSize vous permettent d'ajuster la façon dont le compteur de quotas est synchronisé avec Edge. Dans les situations de trafic élevé, les paramètres bufferSize permet au compteur de tampon de se synchroniser avant que la synchronisation par défaut basée sur l'heure ne soit déclenchée.

Comprendre le champ d'application des quotas

Le nombre de quotas est limité à un environnement au sein d'une organisation. Pour atteindre cette portée, Edge Microgateway crée un identifiant de quota qui combine "org + env + appName + productName".

Utiliser un magasin de sauvegarde Redis pour le quota

Pour utiliser un magasin de sauvegarde Redis en tant que quota, utilisez la même configuration que pour Fonctionnalité de synchronisation. Voici la configuration de base requise pour utiliser Redis pour quota de stockage:

edgemicro:
  redisHost: localhost
  redisPort: 6379
  redisDb: 2
  redisPassword: codemaster

quotas:
  useRedis: true
Pour en savoir plus sur les paramètres edgemicro.redis*, consultez Utiliser le synchronisateur.

Tester le plug-in de quota

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

{"error": "exceeded quota"}

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

Il est important de choisir l'outil adapté à la tâche en cours. Configuration des règles de quota Nombre de messages de requête qu'une application cliente est autorisée à envoyer à une API au cours du cours d'une heure, d'un jour, d'une semaine ou d'un mois. La règle de quota impose des limites de consommation aux applications clientes la maintenance d'un compteur distribué qui compte les requêtes entrantes.

Utiliser des règles de quotas pour faire respecter des contrats commerciaux ou des contrats de niveau de service avec les développeurs et les partenaires que pour la gestion du trafic opérationnel. Par exemple, un quota peut être utilisé pour limiter le trafic pour un service sans frais, tout en offrant un accès complet aux clients payants.

Utilisez l'arrêt des pics pour vous protéger contre les pics soudains de trafic des API. En général, l'arrêt des pics est utilisés pour prévenir d’éventuelles attaques DDoS ou d’autres attaques malveillantes.