Exposer un service SOAP en tant que proxy d'API

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

Cette rubrique explique comment créer des proxys d'API pour les services Web basés sur SOAP. Vous pouvez créer deux types de proxys SOAP dans Edge. L'un génère une interface RESTful pour le service SOAP de backend, tandis que l'autre effectue un "relais" du message SOAP vers le backend. Ces deux techniques sont décrites dans cette rubrique.

Cette vidéo présente une démonstration de bout en bout de la transformation d'un service SOAP en service REST avec Apigee Edge à l'aide de l'assistant de proxy d'API. Toutefois, si vous souhaitez mieux contrôler la transformation SOAP en REST, vous pouvez créer un proxy à l'aide de règles. Pour en savoir plus, consultez Tutoriel : Créer manuellement un proxy d'API SOAP vers REST dans Apigee Edge.

Créer un proxy d'API RESTful pour un service basé sur SOAP

Cette section explique comment créer un proxy d'API SOAP RESTful avec l'option REST vers SOAP vers REST de l'assistant Créer un proxy.

Présentation

L'option REST to SOAP to REST (REST vers SOAP vers REST) traite le fichier WSDL pour générer un proxy d'API RESTful. Edge détermine à partir du WSDL les opérations, les paramètres d'entrée, etc. acceptés par le service. Edge "devine" la méthode HTTP à utiliser pour chaque opération. En règle générale, Edge traduit les opérations en requêtes GET, qui ont l'avantage d'être mises en cache. Edge configure également le point de terminaison cible du backend, qui peut varier selon l'opération SOAP.

Pour ce type de proxy, Edge génère automatiquement une spécification OpenAPI que vous pouvez utiliser pour créer la documentation de l'API.

Procédure générale

Edge

Pour créer un proxy d'API RESTful vers un service basé sur SOAP à l'aide de l'interface utilisateur Edge :

  1. Connectez-vous à apigee.com/edge.
  2. Sélectionnez Développer > Proxys API dans la barre de navigation de gauche.
  3. Cliquez sur +Proxy.
  4. Cliquez sur Service SOAP.
  5. Sur la page "Détails du proxy", fournissez le fichier WSDL.
    Champ Description
    Fournir un fichier WSDL

    Sélectionnez la source du WSDL.

    • À partir d'une adresse Web (URL) : saisissez ou collez l'URL du WSDL.
    • Depuis mon ordinateur : importez un fichier WSDL depuis votre répertoire local. Vous pouvez importer plusieurs fichiers s'il existe des dépendances.
  6. Cliquez sur Valider pour valider le fichier WSDL.
  7. Saisissez les informations suivantes sur le proxy :
    Champ Description
    Nom Nom affiché pour votre API. Indiquez des caractères alphanumériques, des tirets (-) ou des traits de soulignement (_).
    Chemin de base

    Fragment d'URI qui apparaît après l'adresse http(s)://[host] du proxy d'API. Edge utilise l'URI de chemin de base pour faire correspondre et acheminer les messages de requête entrantes vers le proxy d'API approprié.

    NOTE : Le chemin de base du proxy d'API utilise par défaut la valeur spécifiée pour le champ Name converti en minuscules.

    Le chemin de base est suivi des URL de ressource. Voici la structure d'URL complète que les clients utiliseront pour appeler votre proxy d'API:

    https://[host]/base_path/conditional_flow_path

    NOTE : Le chemin de base doit être unique. Vous ne pouvez pas déployer deux proxys d'API avec le même chemin de base. Si vous modifiez un proxy d'API déployé et que vous définissez le chemin de base sur la même valeur que le chemin de base d'un autre proxy d'API, Edge annule automatiquement le déploiement du proxy d'API lorsque vous l'enregistrez. Pour pouvoir redéployer le proxy d'API, vous devez modifier le chemin d'accès de base afin qu'il soit unique.

    Utiliser des caractères génériques dans les chemins de base

    Utilisez un ou plusieurs caractères génériques /*/ dans les chemins d'accès de base du proxy d'API pour assurer la pérennité de vos proxys d'API. Par exemple, un chemin de base de /team/*/members permet aux clients d'appeler https://[host]/team/blue/members et https://[host]/team/green/members sans que vous ayez besoin de créer de proxys d'API pour gérer les nouvelles équipes. Notez que /**/ n'est pas accepté.
    Description (Facultatif) Description de l'API.
  8. Cliquez sur Suivant.
  9. Sur la page Règles communes de l'assistant, configurez les éléments suivants :
    • Exigences d'autorisations de sécurité sous Sécurité: Autorisation. Consultez la section Ajout de sécurité.
    • Compatibilité du partage des ressources entre origines multiples (CORS, Cross-Origin Resource Sharing) sous Sécurité : navigateur. Consultez Assurer la compatibilité avec CORS.
    • Quotas visant à protéger votre service de backend contre le trafic élevé sous Quota. Consultez la section Quotas. (Non disponible si l'autorisation directe est sélectionnée).
  10. Sur la page Opérations WSDL, sélectionnez le type de proxy d'API REST vers SOAP vers REST.

    Un tableau s'affiche, listant les opérations qu'Edge a "découvertes" dans le fichier WSDL. Vous pouvez sélectionner et configurer les opérations que vous souhaitez intégrer à votre proxy d'API. Le tableau est illustré dans la figure suivante.

  11. Sélectionnez un type de port dans le menu déroulant pour spécifier l'ensemble d'opérations que vous souhaitez utiliser. Dans WSDL, les éléments de type port définissent les opérations que vous pouvez appeler sur un service Web.
  12. Vous pouvez éventuellement modifier le chemin de l'API REST pour une opération. Le chemin d'accès sera utilisé comme nom de ressource dans l'URL du proxy d'API.
  13. Vous pouvez éventuellement modifier le verbe (méthode HTTP) associé à l'opération.
  14. Cliquez sur Suivant.
  15. Sur la page Hôtes virtuels de l'assistant, sélectionnez les hôtes virtuels qui seront liés au proxy d'API lors du déploiement. Pour plus d'informations, consultez la section À propos des hôtes virtuels.
  16. Cliquez sur Suivant.
  17. Sélectionnez le ou les environnements de déploiement, puis cliquez sur Créer et déployer.
    Votre proxy d'API est créé et déployé dans l'environnement sélectionné.
  18. Cliquez sur Modifier le proxy pour afficher la page d'informations du proxy d'API.

Classic Edge (Private Cloud)

Pour créer un proxy d'API RESTful vers un service basé sur SOAP à l'aide de l'interface utilisateur classique d'Edge :

  1. Connectez-vous à http://ms-ip:9000, où ms-ip est l'adresse IP ou le nom DNS du nœud de serveur de gestion.
  2. Sélectionnez API > Proxies d'API dans la barre de navigation supérieure.
  3. Cliquez sur + Proxy d'API.
  4. Dans l'assistant Créer un proxy, sélectionnez "Service SOAP".
  5. Cliquez sur Suivant.
  6. Sur la page "Détails", effectuez les sélections suivantes. Vous devez cliquer sur Valider après avoir sélectionné un fichier WSDL.
    Dans ce champ procédez comme suit
    WSDL

    Sélectionnez la source du WSDL.

    • URL : saisissez l'URL du fichier WSDL que vous souhaitez utiliser.
    • Fichier : sélectionnez un fichier WSDL dans votre système de fichiers. Dans les cas où il existe des fichiers dépendants supplémentaires, vous pouvez tous les sélectionner.
    • Exemple d'URL : sélectionnez une URL dans la liste des WSDL pour les services Web disponibles publiquement. Elles sont utiles pour tester les fonctionnalités de proxy SOAP/API d'Edge.
    Proxy Name (Nom du proxy)

    Il s'agit du nom du proxy que vous créez.
    Chemin de base du proxy

    Fragment d'URI qui apparaît après l'adresse http(s)://[host] du proxy d'API. Edge utilise l'URI de chemin de base pour faire correspondre et acheminer les messages de requête entrantes vers le proxy d'API approprié.

    Remarque : Le chemin de base du proxy d'API utilise par défaut la valeur spécifiée pour le champ Name converti en minuscules.

    Le chemin de base est suivi des URL de ressource. Voici la structure d'URL complète que les clients utiliseront pour appeler votre proxy d'API:

    https://[host]/base_path/conditional_flow_path

    Remarque : Le chemin de base doit être unique. Vous ne pouvez pas déployer deux proxys d'API avec le même chemin de base. Si vous modifiez un proxy d'API déployé et que vous définissez le chemin de base sur la même valeur que le chemin de base d'un autre proxy d'API, Edge annule automatiquement le déploiement du proxy d'API lorsque vous l'enregistrez. Pour pouvoir redéployer le proxy d'API, vous devez modifier le chemin d'accès de base afin qu'il soit unique.

    Utiliser des caractères génériques dans les chemins de base

    Utilisez un ou plusieurs caractères génériques /*/ dans les chemins d'accès de base du proxy d'API pour assurer la pérennité de vos proxys d'API. Par exemple, un chemin de base de /team/*/members permet aux clients d'appeler https://[host]/team/blue/members et https://[host]/team/green/members sans que vous ayez besoin de créer de proxys d'API pour gérer les nouvelles équipes. Notez que /**/ n'est pas accepté.
    Description Brève description du proxy.
  7. Cliquez sur Suivant.
  8. Sur la page WSDL, sélectionnez le type de proxy d'API REST to SOAP to REST.

    Un tableau s'affiche, listant les opérations qu'Edge a "découvertes" dans le fichier WSDL. Vous pouvez sélectionner et configurer les opérations que vous souhaitez intégrer à votre proxy d'API. Le tableau est illustré dans la figure suivante.

    Sur la page des opérations WSDL, le type de proxy d'API est défini sur "REST vers SOAP vers REST". Un tableau affiche une ligne de résultats avec l'opération d'ajout.

  9. Dans la colonne "Type de port", sélectionnez l'ensemble d'opérations que vous souhaitez utiliser. Dans WSDL, les éléments de type port définissent les opérations que vous pouvez appeler sur un service Web.
  10. Vous pouvez éventuellement modifier la méthode HTTP associée à l'opération.

    Remarque : Edge fait de son mieux pour déterminer la méthode HTTP à utiliser pour chaque opération. GET est généralement préféré, car les requêtes GET peuvent être mises en cache.
  11. Vous pouvez également modifier le chemin de l'API REST pour une opération. Le chemin d'accès sera utilisé comme nom de ressource dans l'URL du proxy d'API.
  12. Parcourez le reste de l'assistant pour ajouter la sécurité, sélectionner les hôtes virtuels et l'environnement de déploiement.
  13. Sur la page "Créer", cliquez sur Créer et déployer. Edge génère et déploie le nouveau proxy d'API en fonction du fichier WSDL.
  14. Accédez à la page récapitulative du nouveau proxy d'API. Notez qu'un ensemble de ressources a été créé en fonction des opérations découvertes dans le fichier WSDL.

    Sur la page "Présentation" du proxy, la liste Ressources fournit une description détaillée de la nouvelle API, de ses opérations et de ses paramètres. Vous pouvez considérer cette représentation comme la documentation de référence de l'API. Edge génère automatiquement cette vue du modèle d'API pour vous. Il vous suffit de développer une ressource pour afficher sa description et les informations sur son chemin d'accès.

À propos du proxy final

Lorsqu'Edge génère un proxy d'API basé sur un fichier WSDL, le proxy obtenu est en fait un flux complexe qui inclut des règles pour transformer les données, extraire et définir des variables, manipuler des messages, etc. Après avoir généré un proxy basé sur un fichier WSDL, examinez le flux obtenu dans la vue "Développer" de l'interface utilisateur de gestion des API. Vous pouvez y voir exactement quelles règles ont été ajoutées.

Par exemple, côté requête, une règle AssignMessage est utilisée pour définir l'URL cible. Du côté de la réponse, les règles s'exécutent pour transformer la réponse de XML en JSON, extraire la partie du corps SOAP de la réponse dans une variable et définir le message de réponse. Ces règles (et d'autres) sont ajoutées automatiquement lorsque vous créez le proxy.

Spécification OpenAPI : pour afficher la spécification OpenAPI générée automatiquement pour ce proxy, accédez à http(s)://[proxy_domain]/[proxy_base_path]/openapi.json. Toutefois, la conversion n'est pas toujours précise, car toutes les règles d'un schéma XML ne peuvent pas être représentées dans une spécification OpenAPI.

Créer un proxy direct vers un service basé sur SOAP

Cette section explique comment créer un proxy direct avec l'option Pass-Through Proxy (Proxy direct) de la boîte de dialogue "Create New Proxy" (Créer un proxy).

Présentation

L'option "Pass-Through Proxy" (Proxy de relais) vous permet de créer un proxy qui transmet le message SOAP d'une requête au service de backend "intact". Il est ainsi très facile de créer un proxy pour un service Web basé sur SOAP. En arrière-plan, Edge gère automatiquement toutes les transformations et autres activités de flux pour vous. Par exemple, si la requête est au format JSON, Edge prend des mesures pour la convertir en message SOAP XML valide avec les espaces de noms appropriés avant de l'envoyer au service. De même, lorsque le service renvoie une réponse SOAP basée sur XML, Edge la traduit de nouveau au format JSON avant de la renvoyer au client. De plus, Edge configure le point de terminaison cible du backend, qui peut varier selon l'opération SOAP.

Pour ce type de proxy, Edge héberge le fichier WSDL et crée un flux dans le proxy pour vous permettre d'y accéder. L'adresse de ce fichier WSDL hébergé sur Edge, http(s)://[proxy_domain]/[proxy_base_path]?wsdl, devient la nouvelle URL du point de terminaison du service pour les clients qui appellent le service SOAP via le proxy.

Procédure générale

Edge

Pour créer un proxy passthrough vers un service basé sur SOAP à l'aide de l'interface utilisateur Edge :

  1. Connectez-vous à apigee.com/edge.
  2. Sélectionnez Développer > Proxys API dans la barre de navigation de gauche.
  3. Cliquez sur +Proxy.
  4. Cliquez sur Service SOAP.
  5. Sur la page "Détails du proxy", fournissez les informations WSDL.
    Champ Description
    WSDL

    Sélectionnez la source du WSDL.

    • À partir d'une adresse Web (URL) : saisissez ou collez l'URL du WSDL.
    • Depuis mon ordinateur : importez un fichier WSDL depuis votre répertoire local. Vous pouvez importer plusieurs fichiers s'il existe des dépendances.
    Nom

    Nom du proxy d'API.
    Chemin de base

    Fragment d'URI après l'adresse http(s)://[host] du proxy d'API. Edge utilise l'URI de chemin de base pour faire correspondre et acheminer les messages de requête entrantes vers le proxy d'API approprié.

    Remarque : Pour les recommandations d'Apigee concernant la gestion des versions d'API, consultez la section Versioning (Gestion des versions) de l'e-book Web API Design: The Missing Link (Conception d'API Web : le chaînon manquant).

    Le chemin de base est suivi des URL de ressource. Voici la structure d'URL complète que les clients utiliseront pour appeler votre proxy d'API :

    https://[host]/base_path/conditional_flow_path

    Remarque : Le chemin de base doit être unique. Si vous modifiez ultérieurement ce proxy et que vous définissez son chemin de base sur la même valeur que celui d'un autre proxy d'API, ce proxy d'API est automatiquement non déployé lorsque vous l'enregistrez. Vous devez modifier le chemin d'accès de base avant de pouvoir le redéployer.

    Utiliser un caractère générique dans les chemins de base

    Vous pouvez utiliser un ou plusieurs caractères génériques /*/ dans les chemins d'accès de base du proxy d'API pour assurer la pérennité de vos proxys. Par exemple, un chemin de base de /team/*/members permet aux clients d'appeler https://[host]/team/blue/members et https://[host]/team/green/members sans que vous ayez besoin de créer de proxys d'API pour gérer les nouvelles équipes. Notez que /**/ n'est pas accepté.

    Remarque : Le chemin de base du proxy d'API utilise par défaut la valeur spécifiée pour le champ "Nom" convertie en minuscules, sauf si vous modifiez explicitement le contenu du champ "Chemin de base".
    Description (Facultatif) Description de l'API.
  6. Cliquez sur Suivant.
  7. Sur la page Règles communes de l'assistant, configurez les éléments suivants :
  8. Sur la page WSDL, sélectionnez le type de proxy d'API Pass-Through SOAP (SOAP direct).

  9. Sélectionnez un type de port dans le menu déroulant pour spécifier l'ensemble d'opérations que vous souhaitez utiliser. Dans WSDL, les éléments de type port définissent les opérations que vous pouvez appeler sur un service Web.
  10. Cliquez sur Suivant.
  11. Sur la page Hôtes virtuels de l'assistant, sélectionnez les hôtes virtuels qui seront liés au proxy d'API lors du déploiement. Pour en savoir plus, consultez À propos des hôtes virtuels.
  12. Sélectionnez un ou plusieurs environnements de déploiement, puis cliquez sur Créer et déployer.
    Votre proxy d'API est créé et déployé dans l'environnement sélectionné.
  13. Cliquez sur Modifier le proxy pour afficher la page d'informations du proxy d'API.

Classic Edge (Private Cloud)

Pour créer un proxy passthrough vers un service basé sur SOAP à l'aide de l'interface utilisateur classique d'Edge :

  1. Connectez-vous à http://ms-ip:9000, où ms-ip est l'adresse IP ou le nom DNS du nœud de serveur de gestion.
  2. Sélectionnez API > Proxies d'API dans la barre de navigation supérieure.
  3. Cliquez sur + Proxy d'API.
  4. Dans l'assistant Créer un proxy, sélectionnez "Service SOAP".
  5. Cliquez sur Suivant.
  6. Sur la page "Détails", effectuez les sélections suivantes. Vous devez cliquer sur Valider après avoir sélectionné un fichier WSDL.
    Dans ce champ procédez comme suit
    WSDL

    Sélectionnez la source du WSDL.

    • URL : saisissez l'URL du fichier WSDL que vous souhaitez utiliser.
    • Fichier : sélectionnez un fichier WSDL dans votre système de fichiers. Dans les cas où il existe des fichiers dépendants supplémentaires, vous pouvez tous les sélectionner.
    • Exemple d'URL : sélectionnez une URL dans la liste des WSDL pour les services Web disponibles publiquement. Elles sont utiles pour tester les fonctionnalités de proxy SOAP/API d'Edge.
    Proxy Name (Nom du proxy)

    Il s'agit du nom du proxy que vous créez.
    Chemin de base du proxy Le chemin de base du proxy est un fragment d'URI qui identifie de manière unique l'API exposée par ce proxy d'API. Les services d'API utilisent l'URI de chemin de base pour faire correspondre et acheminer les messages de requête entrantes vers le proxy d'API approprié. (Le chemin de base est ajouté au domaine de l'API, qui est généré automatiquement en fonction du nom de votre organisation et de l'environnement dans lequel le proxy d'API est déployé.) Il est recommandé d'inclure un numéro de version dans le nom du projet, par exemple /v1/delayedstockquote. Cela déterminera la manière dont votre API est appelée par les applications clientes.

    Remarque : Le chemin de base du proxy utilise par défaut la valeur spécifiée pour le nom du proxy converti en minuscules, sauf si vous modifiez explicitement le contenu du champ "Chemin de base du proxy".
    Description Brève description du proxy.

  8. Cliquez sur Suivant.
  9. Sur la page WSDL, sélectionnez le type de proxy d'API Pass-Through SOAP.

    Remarque : Un tableau s'affiche, listant chaque opération WSDL et sa charge utile SOAP correspondante. Il s'agit de la charge utile "transmise" au service SOAP de backend.

    Sur la page WSDL, le type de proxy d'API est défini sur "Pass-Through SOAP" (SOAP direct), et une liste d'opérations telles que "GetQuote" (Obtenir un devis) est organisée par type de port.
  10. Dans la colonne "Type de port", sélectionnez l'ensemble d'opérations que vous souhaitez utiliser. Dans WSDL, les éléments de type port définissent les opérations que vous pouvez appeler sur un service Web.
  11. Parcourez le reste de l'assistant pour ajouter la sécurité, sélectionner les hôtes virtuels et l'environnement de déploiement.
  12. Sur la page "Créer", cliquez sur Créer et déployer. Edge génère et déploie le nouveau proxy d'API en fonction du fichier WSDL.

À propos du proxy final

Lorsque Edge génère un proxy pass-through, le proxy obtenu est en fait un flux complexe qui inclut des règles pour transformer les données, extraire et définir des variables, manipuler des messages, etc. Une fois le proxy de transfert généré, examinez le flux obtenu dans la vue "Développer" de l'UI de gestion des API. Vous pouvez y voir exactement quelles règles ont été ajoutées.

Par exemple, la figure suivante montre la partie "Preflow du point de terminaison cible" d'un proxy pass-through. Côté requête, une règle AssignMessage est utilisée pour définir l'URL cible. Du côté de la réponse, les règles s'exécutent pour transformer la réponse de XML en JSON, extraire la partie "body" SOAP de la réponse dans une variable et définir le message de réponse. Ces règles (et d'autres) sont ajoutées automatiquement lorsque vous créez le proxy.

Dans la vue "Développer", dans le panneau "Flux", des flèches représentent le flux de la requête à la réponse, et des icônes représentent les règles.

WSDL hébergé sur Edge : pour afficher le WSDL hébergé sur Edge généré pour ce type de proxy, accédez à http(s)://[proxy_domain]/[proxy_base_path]?wsdl.

Développement avancé de proxys SOAP vers REST

Les sections précédentes ont abordé la création d'un proxy d'API SOAP vers REST à l'aide de l'assistant de proxy d'API dans Edge. Toutefois, si vous souhaitez contrôler plus précisément la transformation SOAP en REST, vous pouvez contourner l'automatisation fournie par l'assistant et créer un proxy en ajoutant et en configurant manuellement des règles pour obtenir le comportement souhaité. Pour en savoir plus, consultez Tutoriel : Créer manuellement un proxy d'API SOAP vers REST dans Apigee Edge.