Exposer un service SOAP en tant que proxy d'API

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

Cet article 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 vers le service SOAP de backend, et l'autre effectue un "pass through" du message SOAP vers le backend. Les deux techniques sont décrites dans cette section.

Cette vidéo fournit une démonstration de bout en bout de la conversion 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 vers REST, vous pouvez créer un proxy à l'aide de règles. Pour en savoir plus, consultez tutoriel: Création manuelle d'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 to SOAP to REST (REST vers SOAP vers REST) dans l'assistant de création d'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 fichier WSDL les opérations compatibles du service, les paramètres d'entrée, etc. 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 enregistrables 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 pour un service basé sur SOAP à l'aide de l'UI 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 "Proxy details" (Détails du proxy), fournissez le fichier WSDL.
    Champ Description
    Fournir un fichier WSDL

    Sélectionnez la source du fichier WSDL.

    • À partir d'une adresse Web (URL) : saisissez ou collez l'URL du fichier WSDL.
    • Depuis mon ordinateur : importez un fichier WSDL à partir de votre répertoire local. Vous pouvez importer plusieurs fichiers en cas de 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é.

    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 (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 Ajouter 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 to SOAP to REST (REST vers SOAP vers REST).

    Un tableau s'affiche, listant les opérations que 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 de 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 est 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.

Edge classique (cloud privé)

Pour créer un proxy d'API RESTful pour 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 de création de 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 fichier WSDL.

    • URL : saisissez l'URL du fichier WSDL que vous souhaitez utiliser.
    • Fichier : sélectionnez un fichier WSDL dans votre système de fichiers. S'il existe d'autres fichiers dépendants, vous pouvez tous les sélectionner.
    • Exemple d'URL : sélectionnez une URL dans une liste de fichiers WSDL pour les services Web publics. Ils 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 (REST vers SOAP vers REST).

    Un tableau s'affiche, listant les opérations que 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 to SOAP to REST, et 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 de 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 effectue une "meilleure estimation" pour déterminer la méthode HTTP à utiliser pour chaque opération. GET est généralement privilégié, car les requêtes GET peuvent être mises en cache.
  11. Vous pouvez modifier le chemin de l'API REST pour une opération. Le chemin d'accès est utilisé comme nom de ressource dans l'URL du proxy d'API.
  12. Suivez les étapes restantes de l'assistant pour ajouter la sécurité, sélectionner des hôtes virtuels et définir 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 d'après le 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étectées dans le fichier WSDL.

    Sur la page "Vue d'ensemble" 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. Il vous suffit de développer une ressource pour afficher sa description et ses informations de chemin d'accès.

À propos du proxy final

Lorsque Edge génère un proxy d'API basé sur un fichier WSDL, le proxy obtenu est en réalité 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 généré 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. Côté réponse, les règles s'exécutent pour transformer la réponse 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 de passthrough vers un service basé sur SOAP

Cette section explique comment créer un proxy de passthrough avec l'option Proxy de passthrough dans la boîte de dialogue "Créer un proxy".

Présentation

L'option "Proxy de passthrough" vous permet de créer un proxy qui transmet le message SOAP dans une requête au service de backend "inchangé", ce qui facilite grandement la création d'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. Par exemple, si la requête est au format JSON, Edge prend les mesures nécessaires 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 convertit à nouveau en 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 y donner accès. L'adresse de ce fichier WSDL hébergé par 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 détails du fichier WSDL.
    Champ Description
    WSDL

    Sélectionnez la source du fichier WSDL.

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

    Nom du proxy d'API.
    Chemin de base

    Fragment d'URI après l'adresse http(s)://[host] de votre 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 le chapitre 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 celui d'un autre proxy d'API, ce proxy d'API est automatiquement désinstallé 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 "Name" (Nom) converti en minuscules, sauf si vous modifiez explicitement le contenu du champ "Base Path" (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 SOAP pass-through.

  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 de 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 la section À propos des hôtes virtuels.
  12. 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é.
  13. Cliquez sur Modifier le proxy pour afficher la page d'informations du proxy d'API.

Edge classique (cloud privé)

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 de création de 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 fichier WSDL.

    • URL : saisissez l'URL du fichier WSDL que vous souhaitez utiliser.
    • Fichier : sélectionnez un fichier WSDL dans votre système de fichiers. Si des fichiers dépendants supplémentaires sont disponibles, vous pouvez les sélectionner tous.
    • Exemple d'URL : sélectionnez une URL dans une liste de fichiers WSDL pour les services Web publics. Ils 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 d'accès 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 grand public.

    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 SOAP pass-through.

    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 SOAP de passthrough, et une liste d'opérations telles que GetQuote 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 de port définissent les opérations que vous pouvez appeler sur un service Web.
  11. Suivez les étapes restantes de l'assistant pour ajouter la sécurité, sélectionner des hôtes virtuels et définir 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 d'après le fichier WSDL.

À propos du proxy final

Lorsque Edge génère un proxy de passthrough, 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é le proxy de passthrough, examinez le flux généré 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 de passthrough. Côté requête, une règle AssignMessage est utilisée pour définir l'URL cible. Côté réponse, les règles s'exécutent pour transformer la réponse 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.

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

WSDL hébergé par Edge: pour afficher le fichier WSDL hébergé par 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 décrit 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 vers 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 le tutoriel: Création manuelle d'un proxy d'API SOAP vers REST dans Apigee Edge.