Étape 5 : Ajoutez une règle

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

Consultez la documentation d'Apigee Edge.

Maintenant que vous avez modifié le point de terminaison cible, vous êtes prêt à ajouter une règle à votre proxy.

Une règle est un composant Apigee que vous pouvez associer à différents stades du flux de messages à l'aide de vos proxys d'API. Les règles peuvent transformer les formats de messages, appliquer un contrôle d'accès, appeler des services distants, autoriser des utilisateurs, examiner le contenu des messages pour détecter les menaces potentielles, et effectuer bien d'autres actions.

Dans ce tutoriel, vous allez ajouter la stratégie XMLtoJSON à votre proxy. Cette règle convertit la charge utile d'un message XML au format JSON. Il modifie également l'en-tête Content-Type de la réponse.

Vous pouvez associer une règle à un flux dans le proxy. Les flux contrôlent l'exécution des règles. Dans cet exemple, vous allez ajouter la règle à un flux spécial, appelé PreFlow (Flux préliminaire). Les règles du PreFlow sont exécutées avant toute autre règle dans le proxy. Bien que vous n'ayez pas besoin de comprendre les flux en détail pour lire cet exemple, vous pouvez en apprendre plus sur ces flux dans la section Contrôler des proxys d'API avec des flux.

Documentation complémentaire

Vous pouvez ajouter des dizaines de règles prêtes à l'emploi à vos proxys, parmi lesquelles :

• Règle AssignMessage
• Règle RaiseFault
• Règle JavaScript
• Règle SpikeArrest
• Règle ExtractVariables

Pour obtenir la liste complète des règles, consultez la documentation de référence sur les règles.

Remarque : Apigee introduit une nouvelle version de l'éditeur de proxys, qui facilite la gestion des proxys.

Les instructions des deux premiers onglets ci-dessous expliquent comment utiliser le nouvel éditeur de proxys ou l'éditeur de proxys classique.

Nouvel éditeur de proxys

Pour ajouter la règle XMLtoJSON à votre proxy, procédez comme suit :

• Créez une instance de la règle.
• Associez la règle à une étape du PreFlow.

Créer une instance de la règle

Pour utiliser une règle, vous devez d'abord créer une instance de celle-ci à partir du modèle de règle comme suit :

1. Si vous utilisez l'interface utilisateur d'Apigee dans la console Cloud : sélectionnez Développement de proxys > Proxys d'API.

   Si vous utilisez la version classique de l'interface utilisateur d'Apigee : sélectionnez Développer > Proxys d'API, puis dans le volet Proxys, sélectionnez l'environnement du proxy.

2. Dans la liste des proxys, sélectionnez le proxy auquel vous souhaitez ajouter la stratégie.

3. Cliquez sur l'onglet Développer :

4. Dans le volet de gauche, cliquez sur le bouton + à côté du dossier Policies (Règles).

5. Dans la boîte de dialogue Create policy (Créer une règle), cliquez dans le champ Select policy type (Sélectionner un type de règle) et faites défiler la page jusqu'à Mediation (Médiation), puis sélectionnez XML To JSON.

6. Vous pouvez éventuellement modifier les champs Name (Nom) et Display name (Nom à afficher) de la règle. Par défaut, Apigee fournit un préfixe court pour le nom de la règle (X2J- dans le cas présent). Vous pouvez ajouter une séquence de mots descriptifs, séparés par des tirets, après le préfixe. Consultez les conventions d'attribution de noms.

   Remarque : Si vous êtes un utilisateur du paiement à l'usage ou un utilisateur de l'abonnement 2024, vous pouvez les trier par type de règle standard et extensible. Les autres utilisateurs ne verront pas les types de règles.

   

   Lorsque vous avez terminé, cliquez sur Créer pour créer la règle.

La règle "XML To JSON" s'affiche désormais dans le volet de droite de la vue Développer :

La partie inférieure du volet affiche le code XML de la règle.

Pour en savoir plus sur la règle, sélectionnez l'icône d'informations à côté du nom de la règle, puis cliquez sur la règle XML To JSON. La page de référence de la règle s'affiche.

Remarque : L'exemple ci-dessus utilise le nom de règle par défaut X2J-. Consultez la section Modifier le nom de la règle pour savoir comment modifier ce nom par défaut.

Modifier le nom de la règle

Procédez comme suit pour modifier le nom d'une règle :

1. Sélectionnez la règle sous Règles, dans le volet de gauche.
2. Dans l'élément <DisplayName> du code XML de la règle, ajoutez une expression descriptive, par exemple change-xml-to-json, après l'abréviation du nom de la règle :

   

   Le nom de la règle affiché sous Règles est automatiquement mis à jour.

   Consultez les conventions d'attribution de noms.

Associer la règle à une étape dans le PreFlow

Maintenant que vous avez créé la règle XML To JSON, vous pouvez l'associer à une étape du PreFlow :

1. Sélectionnez Proxy Endpoints > default > PreFlow (Points de terminaison du proxy > Par défaut > PreFlow) dans le volet de gauche :

   

   Remarque : Vous devrez peut-être développer l'éditeur visuel dans le volet de droite pour afficher tous les éléments. Pour ce faire, cliquez sur le séparateur et faites-le glisser entre l'éditeur visuel et l'éditeur de texte.

2. Cliquez sur le bouton + à côté de PreFlow dans le volet Réponse en bas à droite de l'éditeur visuel :

   

3. Dans la boîte de dialogue Ajouter une étape de règle, sélectionnez la règle X2J-change-xml-to-json.

4. Cliquez sur Ajouter pour associer la règle.

   La règle X2J-change-xml-to-json s'affiche désormais dans le volet Réponse :

   

5. Cliquez sur Save (Enregistrer) pour enregistrer vos modifications dans la révision actuelle.
6. Pour déployer vos modifications sur la révision, cliquez sur Déployer et suivez les instructions de la section Déployer un proxy d'API.

Éditeur de proxy classique

Pour ajouter la règle XMLtoJSON à votre proxy, procédez comme suit :

1. Ouvrez l'interface utilisateur d'Apigee dans un navigateur et connectez-vous.
2. Cliquez sur API Proxies (Proxys d'API) dans la fenêtre principale et sélectionnez un proxy. Pour cet exemple, sélectionnez le proxy que vous avez créé à l'étape 2 : Créer un proxy d'API.

3. Cliquez sur l'onglet Develop (Développer) :

   

   Apigee affiche l'éditeur de proxys d'API.

4. Dans le volet Navigateur, cliquez sur Proxy Endpoints > default > PreFlow (Points de terminaison du proxy > par défaut > PreFlow) :

   

   Apigee affiche l'éditeur de flux :

   

   En outre, Apigee affiche la configuration de point de terminaison proxy par défaut dans le volet Code :

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <ProxyEndpoint name="default">
     <Description/>
     <FaultRules/>
     <PreFlow name="PreFlow">
       <Request/>
       <Response/>
     </PreFlow>
     <PostFlow name="PostFlow">
       <Request/>
       <Response/>
     </PostFlow>
     <Flows/>
     <HTTPProxyConnection>
       <BasePath>/myproxy</BasePath>
       <Properties/>
       <VirtualHost>default</VirtualHost>
       <VirtualHost>secure</VirtualHost>
     </HTTPProxyConnection>
     <RouteRule name="default">
       <TargetEndpoint>default</TargetEndpoint>
     </RouteRule>
   </ProxyEndpoint>

5. Pour ajouter une règle à votre proxy, cliquez sur le bouton + Step (+ Étape) dans la réponse PreFlow (la moitié inférieure de l'éditeur de flux) :

   

   Apigee affiche une liste des règles par catégorie dans la boîte de dialogue Ajouter que vous pouvez ajouter à votre flux :

   

6. Faites défiler la page, puis sélectionnez la règle XMLtoJSON dans la catégorie "Médiation".
   CONSEIL : L'éditeur de proxys d'API est également compatible avec le glisser-déposer. Par exemple, après avoir ajouté une ou plusieurs stratégies au proxy, vous pouvez les faire glisser pour les mettre en place depuis le navigateur via l'éditeur de flux.

   

7. Conservez les noms par défaut, puis cliquez sur Add (Ajouter).

   Apigee associe la nouvelle stratégie au PreFlow de la réponse :

   

   Notez que lorsque vous cliquez sur Ajouter, Apigee effectue les opérations suivantes :

   • Ajout de la nouvelle règle sous Stratégies dans le volet Navigateur.
   • Ajout de la règle XMLtoJSON dans le volet Flow (Flux).
   • Affiche le fichier XML de configuration de la stratégie dans le volet Code.
8. Cliquez sur Save (Enregistrer) pour enregistrer vos modifications dans la révision actuelle.
9. Pour déployer vos modifications, cliquez sur l'onglet Overview (Présentation), puis sur le bouton Deploy (Déployer).

Tester la nouvelle règle

Pour tester la nouvelle règle, exécutez la commande curl suivante dans une fenêtre de terminal :

curl https://YOUR_ENV_GROUP_HOSTNAME/myproxy

où YOUR ENV_GROUP_HOSTNAME est le nom d'hôte du groupe d'environnements. Consultez la page Rechercher le nom d'hôte du groupe d'environnements.

Pour en savoir plus, consultez la page Appeler votre proxy d'API.

Vous pouvez également ouvrir la même URL dans un navigateur.

Vous devez obtenir la réponse suivante :

{
  "root": {
    "city": "San Jose",
    "firstName": "John",
    "lastName": "Doe",
    "state": "CA"
  }
}

Si le corps de la réponse ne ressemble pas à ceci, vérifiez les points suivants :

1. Votre point de terminaison cible est https://mocktarget.apigee.net/xml, comme décrit dans la section Étape 4 : Modifier le point de terminaison cible :
   • Si vous obtenez Hello, Guest! en tant que réponse, vous devez ajouter /xml à la fin du point de terminaison cible.
   • Si vous obtenez une erreur 404, vérifiez que vous accédez à apigee.net et non à apigee.com.
2. La dernière révision de votre proxy est déployée. Essayez de redéployer votre proxy d'API, comme décrit dans les sections Déployer un proxy d'API et Annuler le déploiement d'un proxy d'API.

Pour afficher les en-têtes de requête et de réponse HTTP, activez la verbosité dans curl avec l'option -vs (v rend la réponse détaillée, mais s supprime certaines des parties moins intéressantes). L'exemple suivant suppose que le proxy est nommé myproxy :

curl -vs https://YOUR_ENV_GROUP_HOSTNAME/myproxy  | python -m json.tool

Vous devriez obtenir une réponse semblable à celle-ci : Notez que l'en-tête Content-Type dans la réponse est application/json. La stratégie XMLtoJSON modifie l'en-tête avant de renvoyer la réponse.

*   Trying 10.20.30.40...
* TCP_NODELAY set
* Connected to apitest.acme.com (10.20.30.40) port 443 (#0)
...
> GET /myproxy HTTP/1.1
> Host: apitest.acme.com
> User-Agent: curl/7.58.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Fri, 25 May 2018 16:20:00 GMT
< Content-Type: application/json;charset=UTF-8
< Content-Length: 77
< Connection: keep-alive
< X-Powered-By: Apigee
< Access-Control-Allow-Origin: *
...
{ [77 bytes data]
{
  "root": {
    "city": "San Jose",
    "firstName": "John",
    "lastName": "Doe",
    "state": "CA"
  }
}

Étape suivante

Aller plus loin