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.

Cet article présente les types de règles et leur utilisation dans Apigee. Pour en savoir plus sur des règles spécifiques, consultez la présentation de la documentation de référence sur les règles.

Types et catégories de règles

Techniquement, une règle est un fichier de configuration au format XML. La structure de chaque 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 règles Apigee sont regroupées dans les catégories fonctionnelles suivantes. Les règles disponibles pour chaque catégorie de règles sont listées dans la présentation de la documentation de référence sur les règles.

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.

Associer des règles

Pour qu'une règle s'applique à votre proxy d'API, vous devez l'associer au proxy dans un flux. Pour en savoir plus, consultez les autres rubriques de cette section, y compris Associer et configurer des règles dans l'interface utilisateur et Associer et configurer des règles dans des fichiers XML.

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 une configuration de Quota, définissez un quota (une requête par minute, par exemple), puis 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 :

SpikeArrest
XMLThreatProtection ou JSONThreatProtection
Validation des clés API
Quota
ResponseCache

Flux de réponses ProxyEndpoint :

ResponseCache

Transformation de base : JSON vers XML

Processus de demande d'annonce :

SpikeArrest
JSONThreatProtection
Validation des clés API
Quota
JSONToXML

Flux de réponses :

XMLToJSON
ResponseCache