Exposer un service SOAP en tant que proxy d'API

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X.
en savoir plus

Cette rubrique explique comment créer des proxys d'API pour les services Web basés sur le protocole SAML. Vous pouvez créer deux types de proxys SOAP dans Edge. L'une génère une interface RESTful vers le service SAML de backend, et l'autre effectue un "passthrough" du message SAML au backend. Les deux techniques sont décrites dans cet article.

Cette vidéo fournit une démonstration de bout en bout de la transformation d'un service SAML en service REST avec Apigee Edge à l'aide de l'assistant de proxy d'API. Toutefois, si vous souhaitez avoir davantage de contrôle sur la transformation de type TLS à REST, vous pouvez créer un proxy à l'aide de règles. Pour plus d'informations, consultez le Tutoriel: Construction manuelle d'un proxy d'API SOAP-REST dans Apigee Edge.

Créer un proxy d'API RESTful vers un service basé sur SAML

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

Présentation

L'option REST toSOAP to REST traite le fichier WSDL pour générer un proxy d'API RESTful. Edge détermine à partir du WSDL les opérations prises en charge, les paramètres d'entrée, etc. du 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 de pouvoir être mises en cache. Edge configure également le point de terminaison cible du backend, qui peut varier selon l'opération SAML.

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

Périphérie

Pour créer un proxy d'API RESTful vers un service basé sur SAML à 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 ServiceSOAP.
  5. Sur la page "Détails du proxy", fournissez le fichier WSDL.
    Champ Description
    Fournir le fichier WSDL

    Sélectionnez la source du WSDL.

    • De l'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 s'il existe des dépendances.
  6. Cliquez sur Valider pour valider le WSDL.
  7. Saisissez les informations de proxy suivantes:
    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 du chemin d'accès de base pour faire correspondre et acheminer les messages de requête entrants vers le proxy d'API approprié.

    REMARQUE: Le chemin de base du proxy d'API est défini par défaut sur 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 celle 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 Renforcer la sécurité.
    • Compatibilité du partage des ressources entre origines multiples (CORS, Cross-Origin Resource Sharing) sous Sécurité : navigateur. Consultez la section Ajouter la compatibilité avec le 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 SAML to REST.

    Un tableau s'affiche répertoriant 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 la liste déroulante 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. Si vous le souhaitez, modifiez le chemin de l'API REST pour une opération. Le chemin sera utilisé comme nom de ressource dans l'URL du proxy d'API.
  13. Si vous le souhaitez, modifiez 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 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 (cloud privé)

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

  1. Connectez-vous à http://ms-ip:9000, où ms-ip correspond à l'adresse IP ou au nom DNS du nœud du 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 "Build a Proxy" (Créer un proxy), sélectionnez le service SOAP.
  5. Cliquez sur Suivant.
  6. Sur la page "Détails", effectuez les sélections suivantes. Vous devez cliquer sur Validate (Valider) après avoir sélectionné un WSDL.
    Dans ce champ procédez comme suit
    WSDL

    Sélectionnez la source du WSDL.

    • URL : saisissez l'URL du WSDL que vous souhaitez utiliser.
    • File (Fichier) : sélectionnez un fichier WSDL dans votre système de fichiers. S'il existe des fichiers dépendants supplémentaires, vous pouvez tous les sélectionner.
    • Example URL (Exemple d'URL) : Faites votre choix dans la liste des WSDL pour les services Web accessibles au public. Ceux-ci sont utiles pour tester les fonctionnalités de proxy SAML/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 du chemin d'accès de base pour faire correspondre et acheminer les messages de requête entrants 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 celle 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 toSOAP to REST.

    Un tableau s'affiche répertoriant 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 de l'API est défini sur "REST" à "SOAP vers 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. Si vous le souhaitez, modifiez la méthode HTTP associée à l'opération.

    Remarque:Edge fait l'hypothèse la plus probable pour déterminer la méthode HTTP à utiliser pour chaque opération. GET est généralement préférable, car les requêtes GET peuvent être mises en cache.
  11. Si vous le souhaitez, modifiez le chemin d'accès à l'API REST pour une opération. Le chemin sera utilisé comme nom de ressource dans l'URL du proxy d'API.
  12. Cliquez sur le reste de l'assistant pour renforcer la sécurité, sélectionner des hôtes virtuels et l'environnement de déploiement.
  13. Sur la page "Compiler", cliquez sur Compiler et déployer. Edge génère et déploie le nouveau proxy d'API basé sur le WSDL.
  14. Accédez à la page de résumé 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 de présentation du proxy, la liste des 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 ses informations de chemin d'accès.

À propos du proxy final

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

Par exemple, côté demande, une règle "AssignMessage" est utilisée pour définir l'URL cible. Côté réponse, les stratégies s'exécutent pour transformer la réponse XML en JSON, extraire le corps SOAP de la réponse en 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. Cependant, 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 type passthrough vers un service basé sur SAML

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

Présentation

L'option "Proxy direct" vous permet de créer un proxy qui transmet le message SOAP dans une requête au service de backend "non modifié", ce qui facilite la création d'un proxy pour un service Web basé sur le protocole 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 des mesures pour la convertir en un message RDP XML valide avec les espaces de noms appropriés avant de la publier sur le service. De même, lorsque le service renvoie une réponse SAML basée sur XML, Edge la reconvertit en JSON avant de la renvoyer au client. En outre, Edge configure le point de terminaison cible du backend, qui peut varier selon l'opération SAML.

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

Procédure générale

Périphérie

Pour créer un proxy passthrough vers un service basé sur le protocole 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 ServiceSOAP.
  5. Sur la page "Détails du proxy", fournissez les informations WSDL.
    Champ Description
    WSDL

    Sélectionnez la source du WSDL.

    • De l'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 s'il existe des dépendances.
    Nom

    Nom du proxy de l'API.

    Chemin de base

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

    Remarque: Pour obtenir les recommandations d'Apigee sur la gestion des versions d'API, consultez la section Gestion des versions de l'e-book Web API Design: The Missing Link.

    Après le chemin de base se trouvent les URL de ressources supplémentaires. 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 d'accès de base doit être unique. Si vous modifiez ce proxy par la suite et définissez son chemin de base pour qu'il soit identique à celui d'un autre proxy d'API, son déploiement sera automatiquement annulé lorsque vous l'enregistrerez. 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 des proxys d'API pour pérenniser 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 qu'il soit nécessaire de créer des proxys d'API pour prendre en charge les nouvelles équipes. Notez que /**/ n'est pas accepté.

    Remarque: Le chemin de base du proxy d'API est défini par défaut sur la valeur spécifiée pour le champ "Name" (Nom), converti en minuscules, sauf si vous modifiez explicitement le contenu dans le 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 la liste déroulante 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 plus d'informations, consultez la section À propos des hôtes virtuels.
  12. Sélectionnez 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.

Classic Edge (cloud privé)

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

  1. Connectez-vous à http://ms-ip:9000, où ms-ip correspond à l'adresse IP ou au nom DNS du nœud du 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 "Build a Proxy" (Créer un proxy), sélectionnez le service SOAP.
  5. Cliquez sur Suivant.
  6. Sur la page "Détails", effectuez les sélections suivantes. Vous devez cliquer sur Validate (Valider) après avoir sélectionné un WSDL.
    Dans ce champ procédez comme suit
    WSDL

    Sélectionnez la source du WSDL.

    • URL : saisissez l'URL du WSDL que vous souhaitez utiliser.
    • File (Fichier) : sélectionnez un fichier WSDL dans votre système de fichiers. S'il existe des fichiers dépendants supplémentaires, vous pouvez tous les sélectionner.
    • Example URL (Exemple d'URL) : Faites votre choix dans la liste des WSDL pour les services Web accessibles au public. Ceux-ci sont utiles pour tester les fonctionnalités de proxy SAML/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 du chemin de base pour faire correspondre et acheminer les messages de requête entrants vers le proxy d'API approprié. (Le chemin de base est ajouté au domaine de l'API, qui est automatiquement généré 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 est défini par défaut sur la valeur spécifiée pour le nom du proxy, converti en minuscules, sauf si vous modifiez explicitement le contenu dans le champ "Chemin de base du proxy".

    Description Brève description du proxy.

  7. Cliquez sur Suivant.
  8. Sur la page WSDL, sélectionnez le type de proxy d'API SOAP pass-through.

    Remarque:Un tableau s'affiche répertoriant chaque opération WSDL et la 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 de l'API est défini sur "SAP Pass-through", et une liste d'opérations telles que "GetCitation" est organisée par type de port.
  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. Cliquez sur le reste de l'assistant pour renforcer la sécurité, sélectionner des hôtes virtuels et l'environnement de déploiement.
  11. Sur la page "Compiler", cliquez sur Compiler et déployer. Edge génère et déploie le nouveau proxy d'API basé sur le WSDL.

À propos du proxy final

Lorsque Edge génère un proxy de type passthrough, le proxy obtenu est en fait un flux complexe qui inclut des stratégies de transformation des données, d'extraction et de définition de variables, de manipulation des messages, etc. Une fois le proxy passthrough généré, examinez le flux obtenu dans la vue Développement de l'interface utilisateur de gestion des API. Vous pouvez 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 type passthrough. Côté demande, une règle "AssignMessage" est utilisée pour définir l'URL cible. Du côté de la réponse, les stratégies s'exécutent pour transformer la réponse XML en JSON, extraire le corps SOAP de la réponse en 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 "Develop" (Développer), dans le panneau "Flow" (Flux), des flèches représentent le flux de la requête à la réponse, tandis que 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 SAML vers REST

Les sections précédentes ont couvert la création d'un proxy d'API SAML vers REST à l'aide de l'assistant de proxy d'API dans Edge. Toutefois, si vous souhaitez un contrôle plus précis de la transformation SAML à 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 plus d'informations, consultez le Tutoriel: Construction manuelle d'un proxy d'API SOAP-REST dans Apigee Edge.