Qu'est-ce qu'une règle ?

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Apigee vous permet de programmer le comportement de l'API sans écrire de code à l'aide de règles. Une règle est comme un module qui met en œuvre une fonction de gestion limitée et spécifique. Les règles vous permettent d'ajouter des types courants de fonctionnalités de gestion à une API de manière simple et fiable. Les règles fournissent des fonctionnalités telles que la sécurité, la limitation du débit, la transformation et la médiation, ce qui vous évite d'avoir à coder et à gérer vous-même cette fonctionnalité.

Vous n'êtes pas limité à l'ensemble de types de règles fourni par Apigee. Vous pouvez également écrire des scripts et du code personnalisés (tels que des applications JavaScript) qui étendent les fonctionnalités du proxy d'API et vous permettent d'innover en plus des fonctionnalités de gestion de base compatibles avec les règles Apigee.

Regardez cette vidéo pour découvrir les rattachements et les applications des règles.

Types de règles

Techniquement, une règle est un fichier de configuration au format XML. La structure de chaque type de règle (par exemple, les éléments de configuration obligatoires et facultatifs) est définie par un schéma XML. Si vous maîtrisez les outils XML, il est utile de vous familiariser avec les schémas de règles disponibles dans les exemples de plate-forme API sur GitHub.

Les types de règles Apigee sont regroupés dans les catégories fonctionnelles suivantes :

Gestion du trafic

Les règles de la catégorie "gestion du trafic" vous permettent de contrôler le flux des messages de requête et de réponse via un proxy d'API. Ces règles sont destinées à faciliter le contrôle tant au niveau opérationnel qu'au niveau gestionnel. Elles vous permettent de contrôler le débit brut et peuvent également contrôler le trafic de chaque application. Les règles de type "gestion du trafic" vous permettent d'appliquer des quotas, mais également de limiter les attaques par déni de service.

Sécurité

Les règles de la catégorie "sécurité" facilitent l'authentification, l'autorisation et la sécurité en fonction du contenu.

Médiation

Les règles de la catégorie "médiation" vous permettent de manipuler activement les messages au fur et à mesure qu'ils transitent par des proxys d'API. Elles vous permettent de convertir des formats de message, de XML à JSON (et inversement), ou de convertir un format XML en un autre format XML. Elles vous permettent également d'analyser des messages, de générer de nouveaux messages et de modifier les valeurs des messages sortants. Les règles de médiation interagissent également avec les services de base diffusés par Apigee, ce qui vous permet de récupérer des données sur les applications, les développeurs, les jetons de sécurité et les produits d'API au moment de l'exécution.

Extension

Les règles de la catégorie "'extension" vous permettent d'exploiter l'extensibilité d'Apigee pour mettre en œuvre un comportement personnalisé dans le langage de programmation de votre choix.

Chaque type de règle est décrit en détail dans la Présentation de la documentation de référence des règles. Cette rubrique présente une interaction générale, montrant comment créer des règles et comment les associer à des flux dans une configuration de proxy d'API.

Déployer des modifications de règles

Pour que les modifications de règles soient prises en compte, vous devez déployer la révision du proxy d'API dans un environnement. Après avoir associé une règle ou modifié une règle existante, utilisez l'interface utilisateur Apigee ou l'API Apigee pour déployer les modifications.

Vérifier l'application des règles

Pour vérifier qu'une règle est appliquée correctement, l'API doit être appelée par un client HTTP. Pour vérifier cette configuration de Quota, envoyez plusieurs requêtes à l'API, en dépassant la limite de quota que vous avez définie dans la règle de quota. (Le chemin d'URI, configuré en tant que paramètre de chemin de base dans ProxyEndpoint, est /weather dans la requête ci-dessous).

http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Une fois que vous avez envoyé plus d'une requête en une minute, vous devriez voir le message d'erreur suivant :

{  
   "fault":{  
      "faultstring":"policies.ratelimit.QuotaViolation",
      "detail":{  
         "errorcode":"policies.ratelimit.QuotaViolation"
      }
   }
}

Ce message indique que la règle Quota est appliquée par Apigee.

Gestion des erreurs basée sur des règles

Notez le format du message d'erreur ci-dessus. Il contient une propriété faultstring et une propriété errorcode. Dans de nombreux cas, vous devez définir un comportement pour gérer ces erreurs. Par exemple, vous pouvez envoyer un message personnalisé à un développeur dont l'application a dépassé le Quota.

Pour en savoir plus sur la gestion des pannes, consultez la page Gérer les pannes.

Bonnes pratiques : ensembles de règles courants

Pour répondre aux exigences de gestion de base, les proxys d'API appliquent généralement les règles suivantes :

Validation de base des clés de l'API

Flux de requêtes ProxyEndpoint :
  1. SpikeArrest
  2. XMLThreatProtection ou JSONThreatProtection
  3. Validation des clés API
  4. Quota
  5. ResponseCache
Flux de réponses ProxyEndpoint :
  1. ResponseCache

Transformation de base : JSON vers XML

Processus de demande d'annonce :
  1. SpikeArrest
  2. JSONThreatProtection
  3. Validation des clés API
  4. Quota
  5. JSONToXML
Flux de réponses :
  1. XMLToJSON
  2. ResponseCache