Vous consultez la documentation sur Apigee Edge.
Consultez la documentation sur Apigee X.
Edge Microgateway version 3.3.x
Audience
Cet article est destiné aux opérateurs Edge Microgateway et qui souhaitent utiliser les plug-ins existants installés avec la micropasserelle. Il présente également en détail les plug-ins d'arrêt des pics et de quota (tous deux inclus dans l'installation). Si vous êtes développeur et que vous souhaitez développer de nouveaux plug-ins, consultez 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 schéma cohérent et sont stockés à un emplacement connu par Edge Microgateway, ce qui permet à la micropassera de les détecter et de les charger automatiquement. Edge Microgateway inclut plusieurs plug-ins existants et 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
Un certain nombre de plug-ins sont fournis avec Edge Microgateway lors de l'installation. Le tableau suivant décrit certains des plug-ins les plus couramment utilisés.
Plugin | 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. Consultez la section Configurer et configurer Edge Microgateway. |
quota | Non | Applique un quota sur les requêtes envoyées à Edge Microgateway. Utilise Apigee Edge pour stocker et gérer les quotas. Consultez Utiliser le plug-in de quota. |
pic | Non | Protège contre les pics de trafic et les attaques DoS. Consultez Utiliser le plug-in d'arrêt des pics. |
majuscule | Non | Exemple de proxy commenté et destiné à aider les développeurs à écrire des plug-ins personnalisés Consultez l' exemple de plug-in Edge Microgateway. |
accumulate-request | Non | Accumule les données de requête dans un seul objet avant de les transmettre au gestionnaire suivant de la chaîne de plug-ins. Utile pour l'écriture de plug-ins de transformation qui doivent fonctionner sur un seul objet de contenu de requête accumulé. |
réponse-accumulée | Non | Accumule les données de réponse dans un seul objet avant de les transmettre au gestionnaire suivant de la chaîne de plug-ins. Utile pour l'écriture de plug-ins de transformation qui doivent fonctionner sur un seul objet de contenu de réponse accumulé. |
transformer en majuscules | Non | Transforme les données de requête ou de réponse. Ce plug-in représente une bonne mise en œuvre d'un plug-in de transformation. L'exemple du plug-in effectue une transformation simple (convertit les données de requête ou de réponse en majuscules). Toutefois, il peut facilement être adapté pour effectuer d'autres types de transformations, tels que XML en JSON. |
json2xm | Non | Transforme les données de requête ou de réponse en fonction des en-têtes d'acceptation ou de contenu. Pour en savoir plus, consultez la documentation du plug-in sur GitHub. |
quota-memory (mémoire-quota) | Non | Applique un quota sur les requêtes envoyées à Edge Microgateway. Stocke et gère les quotas en mémoire locale. |
vérification d'état | Non | Renvoie des informations sur le processus Edge Micromicro (utilisation de la mémoire, utilisation du processeur, etc.). Pour utiliser le plug-in, appelez l'URL /healthcheck sur votre instance Edge Microgateway. Ce plug-in est destiné à être un exemple permettant de mettre en œuvre votre propre plug-in de vérification d'état. |
Où trouver les plug-ins existants
Les plug-ins existants regroupés avec Edge Microgateway se trouvent ici, où [prefix]
correspond au répertoire de préfixes npm
. Si vous ne parvenez pas à trouver ce répertoire, consultez
Où est installé Edge Microgateway.
[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins
Ajouter et configurer des plug-ins
Suivez cette procédure pour ajouter et configurer des plug-ins:
- Arrêtez Edge Microgateway.
- Ouvrez un fichier de configuration Edge Microgateway. Pour en savoir plus, consultez Modifier la configuration pour connaître les options.
- 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
- 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 phase suivante pour configurer le plug-in d'arrêt des pics. Pour en savoir plus, consultez Utiliser le plug-in d'arrêt de 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
- Enregistrez le fichier.
- Redémarrez ou actualisez Edge Microgateway, en fonction du fichier de configuration que vous avez modifié.
Configuration spécifique au 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 au plug-in dans ce répertoire:
[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins/config
où [prefix]
est le répertoire de préfixes npm
. Si vous ne parvenez pas à trouver ce répertoire, consultez
Où est installé Edge Microgateway.
plugins/<plugin_name>/config/default.yaml
. Par exemple, vous pouvez placer ce bloc dans plugins/spikearrest/config/default.yaml
. Il remplacera alors tous les autres paramètres de configuration.
spikearrest: timeUnit: hour allow: 10000 buffersize: 0
Utiliser le plug-in d'arrêt de pic
Le plug-in d'arrêt de pics d'activité vous protège contre les pics de trafic. Elle limite le nombre de requêtes traitées par une instance Edge Microgateway.
Ajouter le plug-in d'arrêt de pic d'activité
Consultez 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 de réinitialisation de la fenêtre d'exécution de pics d'arrêt. Les valeurs valides sont les secondes ou les minutes.
- allow: nombre maximal de requêtes autorisées pendant l'unité de temps. Consultez également la section Si vous exécutez plusieurs processus Edge Micro.
- bufferSize (facultatif, par défaut = 0) si tamponSize > 0, le pic d'arrêt stocke ce nombre de requêtes dans un tampon. Dès que la "fenêtre" d'exécution suivante se produit, les requêtes en mémoire tampon sont traitées en premier. Consultez également la section Ajouter un tampon.
Comment fonctionne un pic d'arrestation ?
Considérez l'arrêt des pics comme un moyen de vous protéger généralement des 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 un certain volume de trafic. En outre, les règles d'arrêt des pics vous aident à fluidifier le trafic aux quantités générales souhaitées.
Le comportement d'arrêt du pic d'exécution est différent de ce que vous pouvez attendre des valeurs littérales par minute ou par seconde que vous saisissez.
Par exemple, imaginons que vous spécifiez un taux de 30 requêtes par minute, comme suit:
spikearrest: timeUnit: minute allow: 30
Lors des tests, vous pensez peut-être pouvoir envoyer 30 requêtes en une seconde, à condition qu'elles se fassent dans la minute. Cependant, ce n'est pas ainsi que la règle applique le paramètre. Si vous y réfléchissez bien, 30 requêtes effectuées 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 tout pic d'activité, vous devez limiter le trafic autorisé en divisant vos paramètres en intervalles plus courts, comme suit:
Tarifs par minute
Les taux par minute sont lissés en intervalles de secondes autorisés pour les requêtes. Par exemple, 30 requêtes par minute sont lissées comme suit:
60 secondes (1 minute) / 30 = intervalles de deux secondes, soit environ 1 requête autorisée toutes les 2 secondes. Une seconde requête en moins de deux secondes échouera. De plus, une 31e requête en une minute échoue.
Tarifs par seconde
Les taux par seconde sont lissés en requêtes autorisées par intervalles de millisecondes. Par exemple, 10 requêtes/seconde sont lissées comme suit:
1 000 millisecondes (1 seconde) / 10 = 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. De plus, une 11e requête dans une seconde échoue.
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 de pic renvoie ce message d'erreur avec l'état HTTP 503:
{"error": "spike arrest policy violated"}
Ajouter un tampon
Vous avez la possibilité d'ajouter un tampon à la règle. Imaginons que vous définissiez le tampon sur 10. Vous verrez que l'API ne renvoie pas d'erreur immédiatement lorsque vous dépassez la limite d'arrêt de pics. Les requêtes sont mises en mémoire tampon (jusqu'au nombre spécifié), et elles sont traitées dès que la période 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œuds de calcul Edge Micro en cours d'exécution. L'arrêt de pics calcule le nombre autorisé de requêtes par processus de nœud de calcul. Par défaut, le nombre de processus Edge Micro correspond au nombre de processeurs sur la machine sur laquelle Edge Micro est installé. Toutefois, vous pouvez configurer le nombre de processus de nœud de calcul au démarrage d'Edge Micro à l'aide de l'option --processes
de la commande start
. Par exemple, si vous souhaitez que l'arrêt de pic 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 de pic. En résumé, la règle de base consiste à définir le paramètre allow
sur la valeur "nombre d'arrêts de pointes souhaités / nombre de processus".
Utiliser le plug-in de quota
Un quota indique le nombre de messages de requête qu'une application est autorisée à envoyer à une API en une heure, un jour, une semaine ou 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 Ajouter et configurer des plug-ins.
Configuration du produit dans Apigee Edge
Vous configurez les quotas dans l'interface utilisateur d'Apigee Edge, où vous configurez les produits d'API. Vous devez savoir quel produit contient le proxy compatible avec la micropasserelle que vous souhaitez limiter à l'aide d'un quota. Ce produit doit être ajouté à l'application d'un développeur. Lorsque vous effectuez des appels d'API authentifiés à l'aide de clés dans l'application de développement, le quota est appliqué à ces appels d'API.
- Connectez-vous à votre compte d'organisation Apigee Edge.
- Dans l'interface utilisateur Edge, ouvrez le produit associé au proxy de micro-passerelle auquel vous souhaitez appliquer le quota.
- Dans l'interface utilisateur, sélectionnez Produits dans le menu "Publier".
- Ouvrez le produit contenant l'API à laquelle vous souhaitez appliquer le quota.
- Cliquez sur Modifier.
- 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 2 heures.
- Cliquez sur Enregistrer.
- 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 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 le quota
Pour configurer le plug-in de quota, ajoutez l'élément quotas
à votre fichier de configuration, comme indiqué 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 isHTTPStatusTooManyRequestEnabled: true ...
Option | Description |
---|---|
bufferSize |
(Nombre entier) La configuration quotas: bufferSize: minute: 500 default: 10000 useDebugMpId: true failOpen: true Par défaut, la micropasserelle synchronise son compteur de quotas avec Apigee Edge toutes les cinq 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 d'API sur "minute", Edge Microgateway se synchronise avec Edge pour obtenir le nombre de quotas actuel toutes les 500 requêtes ou après 5 secondes, selon la première éventualité. Pour en savoir plus, consultez Comprendre le calcul des quotas.
Les unités de temps autorisées sont les suivantes: |
isHTTPStatusTooManyRequestEnabled |
Configure le plug-in de quota pour qu'il renvoie un état de réponse HTTP 429 au lieu de l'état 403 en cas de violation du quota.
Valeur par défaut :
Si l'option est définie sur
Pour définir l'état du retour HTTP par défaut sur edgemicro: ... quotas: isHTTPStatusTooManyRequestEnabled: true... |
failOpen |
Lorsque cette fonctionnalité est activée, si une erreur de traitement des quotas se produit ou si la requête "application de quotas" échoue à Edge pour mettre à jour les compteurs de quotas à distance, le quota ne sera traité en fonction du nombre local que jusqu'à la prochaine synchronisation de quotas à distance. Dans les deux cas, un indicateur quota-failed-open est défini dans l'objet de la requête.
Pour activer la fonctionnalité "Échec de l'ouverture" du quota, définissez la configuration suivante: edgemicro: ... quotas: failOpen: true... |
useDebugMpId |
Définissez cette option sur true pour activer la journalisation de l'ID de MP (messagerie) dans les réponses aux quotas.
Pour utiliser cette fonctionnalité, vous devez définir la configuration suivante : edgemicro: ... quotas: useDebugMpId: true ...
Lorsque { "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 stockage de quotas.
Pour en savoir plus, consultez la section Utiliser un datastore de sauvegarde Redis. |
Compréhension de la méthode de comptabilisation des quotas
Par défaut, la micropasserelle synchronise son compteur de quotas avec Apigee Edge toutes les cinq secondes si l'intervalle de quota est défini sur "minute". Si l'intervalle est défini sur un niveau supérieur à "minute", comme "semaine" ou "mois", la période d'actualisation par défaut est d'une minute.
Il est important de noter que vous spécifiez des intervalles de quota dans les produits d'API définis sur Apigee Edge. Les intervalles de quotas indiquent le nombre de requêtes autorisées par minute, heure, jour, semaine ou mois. Par exemple, le produit A peut avoir un intervalle de quota de 100 requêtes par minute,et le produit B peut avoir un intervalle de quota de 10 000 requêtes par heure.
La configuration YAML du plug-in Edge Microgateway quota
ne définit pas l'intervalle de quota. Elle permet plutôt d'ajuster la fréquence à laquelle une instance locale Edge Microgateway synchronise son nombre de quotas avec Apigee Edge.
Par exemple, supposons qu'il existe trois produits d'API définis dans Apigee Edge avec les intervalles de quota suivants spécifiés:
- Le produit A a un quota de 100 requêtes par minute.
- Le produit B a un quota de 5 000 requêtes par heure
- Le produit C a un quota de 1 000 000 requêtes par mois
Compte tenu de ces paramètres de quota, comment devez-vous configurer le plug-in Edge Microgateway quota
? La bonne pratique consiste à configurer Edge Microgateway avec des intervalles de synchronisation 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 l'intervalle "minute". Edge Microgateway se synchronisera avec Edge toutes les 50 requêtes ou toutes les 5 secondes, selon la première éventualité.
- Le produit B est défini sur l'intervalle "heure". Edge Microgateway se synchronise avec Edge après chaque 2 000e requête ou toutes les minutes, selon la première éventualité.
- Le produit C est défini sur l'intervalle "mois". Edge Microgateway se synchronise avec Edge après chaque requête ou toutes les minutes, selon la première éventualité.
Chaque fois qu'une instance de micropasserelle se synchronise avec Edge, le quota de la micropassera est défini sur le nombre de quotas récupéré.
Les paramètres bufferSize
vous permettent d'ajuster la synchronisation du compteur de quotas avec Edge. En cas de trafic élevé, les paramètres bufferSize
permettent de synchroniser le compteur de tampons avant le déclenchement de la synchronisation temporelle par défaut.
Comprendre le champ d'application des quotas
Le quota est limité à un environnement d'une organisation. Pour atteindre ce champ d'application, 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 pour le quota, utilisez la même configuration que celle utilisée pour le synchronisateur. Voici la configuration de base requise pour utiliser Redis pour le stockage des quotas:
edgemicro: redisHost: localhost redisPort: 6379 redisDb: 2 redisPassword: codemaster quotas: useRedis: truePour en savoir plus sur les paramètres
edgemicro.redis*
, consultez la section Utiliser le synchroniseur.
Tester le plug-in de quota
Lorsque le quota est dépassé, l'état HTTP 403 est renvoyé au client, avec 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 l'outil adapté au travail à effectuer. Les stratégies de quota configurent le nombre de messages de requête qu'une application cliente est autorisée à envoyer à une API en une heure, un jour, une semaine ou un mois. La règle de quota applique des limites de consommation au niveau des applications clientes en conservant un compteur distribué qui comptabilise les requêtes entrantes.
Utilisez une règle de quota pour appliquer des contrats commerciaux ou des contrats de niveau de service avec les développeurs et les partenaires, plutôt 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 accordant un accès complet aux clients payants.
Utilisez l'arrêt des pics pour vous protéger des pics soudains de trafic d'API. En général, l'arrêt des pics est utilisé pour éliminer les éventuels attaques DDoS ou d'autres attaques malveillantes.