Esposizione di un servizio SOAP come proxy API

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. info

Questo argomento spiega come creare proxy API per i servizi web basati su SOAP. In Edge puoi creare due tipi di proxy SOAP. Uno genera un'interfaccia RESTful per il servizio SOAP di backend e l'altro esegue un "passthrough" del messaggio SOAP al backend. Entrambe le tecniche sono descritte in questo argomento.

Questo video fornisce una demo end-to-end della trasformazione di un servizio SOAP in un servizio REST con Apigee Edge utilizzando la procedura guidata per i proxy API. Tuttavia, se vuoi un maggiore controllo sulla trasformazione SOAP-to-REST, puoi creare un proxy utilizzando i criteri. Per ulteriori informazioni, consulta Tutorial: creazione manuale di un proxy API SOAP-to-REST in Apigee Edge.

Creazione di un proxy API RESTful per un servizio basato su SOAP

Questa sezione spiega come creare un proxy API SOAP RESTful con l'opzione REST to SOAP to REST nella procedura guidata Crea un proxy.

Panoramica

L'opzione REST to SOAP to REST elabora il file WSDL per generare un proxy API RESTful. Edge determina dal WSDL le operazioni supportate del servizio, i parametri di input e così via. Edge "indovina" quale metodo HTTP utilizzare per ogni operazione. In genere, Edge traduce le operazioni in richieste GET, che hanno il vantaggio di poter essere memorizzate nella cache. Edge configura anche l'endpoint target del backend, che può variare in base all'operazione SOAP.

Per questo tipo di proxy, Edge genera automaticamente una specifica OpenAPI, che puoi utilizzare per creare la documentazione dell'API.

Passaggi di base

Edge

Per creare un proxy API RESTful per un servizio basato su SOAP utilizzando l'interfaccia utente di Edge:

  1. Accedi ad apigee.com/edge.
  2. Seleziona Sviluppa > Proxy API nella barra di navigazione a sinistra.
  3. Fai clic su +Proxy.
  4. Fai clic su Servizio SOAP.
  5. Nella pagina Dettagli proxy, fornisci il file WSDL.
    Campo Descrizione
    Fornisci il file WSDL

    Seleziona l'origine del file WSDL.

    • Da indirizzo web (URL): inserisci o incolla l'URL del WSDL.
    • Dal mio computer: carica un file WSDL dalla tua directory locale. Puoi caricare più file se sono presenti dipendenze.
  6. Fai clic su Convalida per convalidare il file WSDL.
  7. Inserisci i seguenti dettagli del proxy:
    Campo Descrizione
    Nome Nome visualizzato per l'API. Specifica caratteri alfanumerici, trattini (-) o trattini bassi (_).
    Percorso di base

    Frammento URI visualizzato dopo l'indirizzo http(s)://[host] del proxy API. Edge utilizza l'URI del percorso di base per associare e inoltrare i messaggi di richiesta in arrivo al proxy API appropriato.

    NOTA: il percorso base del proxy dell'API è predefinito come il valore specificato per il campo Name convertito in lettere minuscole.

    Dopo il percorso di base sono presenti eventuali URL di risorse aggiuntive. Ecco la struttura dell'URL completa che i client utilizzeranno per chiamare il proxy API:

    https://[host]/base_path/conditional_flow_path

    NOTA: il percorso di base deve essere univoco. Non puoi implementare due proxy API con lo stesso percorso di base. Se modifichi un proxy API di cui è stato eseguito il deployment e imposti il percorso di base sullo stesso valore del percorso di base di un altro proxy API, Edge annulla automaticamente il deployment del proxy API quando lo salvi. Prima di poter eseguire nuovamente il deployment del proxy API, devi modificare il percorso di base in modo che sia univoco.

    Utilizzare i caratteri jolly nei percorsi di base

    Utilizza uno o più caratteri jolly /*/ nei percorsi di base dei proxy API per garantire la compatibilità futura dei proxy API. Ad esempio, un percorso di base /team/*/members consente ai client di chiamare https://[host]/team/blue/members e https://[host]/team/green/members senza dover creare nuovi proxy API per supportare nuovi team. Tieni presente che /**/ non è supportato.
    Descrizione (Facoltativo) Descrizione dell'API.
  8. Fai clic su Avanti.
  9. Nella pagina Criteri comuni della procedura guidata, configura quanto segue:
    • Requisiti di autorizzazione di sicurezza in Sicurezza: autorizzazione. Consulta Aggiunta di sicurezza.
    • Supporto della condivisione delle risorse tra origini (CORS) in Sicurezza: browser. Consulta Aggiunta del supporto per CORS.
    • Quote per proteggere il servizio di backend dal traffico elevato in Quota. Consulta la sezione Quote. (Non disponibile se è selezionata l'autorizzazione Passthrough).
  10. Nella pagina Operazioni WSDL, seleziona il tipo di proxy API REST to SOAP to REST.

    Viene visualizzata una tabella che elenca le operazioni "scoperte" da Edge nel file WSDL. Puoi selezionare e configurare le operazioni da incorporare nel proxy API. La tabella è mostrata nella figura seguente.

  11. Seleziona un Tipo di porta dal menu a discesa per specificare l'insieme di operazioni che vuoi utilizzare. In WSDL, gli elementi di tipo porta definiscono le operazioni che puoi chiamare in un servizio web.
  12. (Facoltativo) Modifica il percorso dell'API REST per un'operazione. Il percorso verrà utilizzato come nome della risorsa nell'URL del proxy dell'API.
  13. Se vuoi, modifica il Verbo (metodo HTTP) associato all'operazione.
  14. Fai clic su Avanti.
  15. Nella pagina Host virtuali della procedura guidata, seleziona gli host virtuali a cui verrà associato il proxy API al momento del deployment. Per ulteriori informazioni, consulta Informazioni sugli host virtuali.
  16. Fai clic su Avanti.
  17. Seleziona gli ambienti di deployment e fai clic su Crea e esegui il deployment
    Il nuovo proxy API viene creato e di cui viene eseguito il deployment nell'ambiente selezionato.
  18. Fai clic su Modifica proxy per visualizzare la pagina dei dettagli del proxy API.

Edge classico (private cloud)

Per creare un proxy API RESTful per un servizio basato su SOAP utilizzando l'interfaccia utente di Edge classica:

  1. Accedi a http://ms-ip:9000, dove ms-ip è l'indirizzo IP o il nome DNS del nodo del server di gestione.
  2. Seleziona API > Proxy API nella barra di navigazione in alto.
  3. Fai clic su + Proxy API.
  4. Nella procedura guidata Crea un proxy, seleziona Servizio SOAP.
  5. Fai clic su Avanti.
  6. Nella pagina Dettagli, effettua queste selezioni. Devi fare clic su Convalida dopo aver selezionato un WSDL.
    In questo campo Fai così
    WSDL

    Seleziona l'origine del file WSDL.

    • URL: inserisci l'URL del WSDL che vuoi utilizzare.
    • File: scegli un file WSDL nel file system. Se esistono file dipendenti aggiuntivi, puoi selezionarli tutti.
    • URL di esempio: seleziona un elenco di WSDL per i servizi web disponibili pubblicamente. Sono utili per provare le funzionalità di proxy SOAP/API di Edge.
    Nome del proxy

    Questo è il nome del proxy che stai creando.
    Percorso base del proxy

    Frammento URI visualizzato dopo l'indirizzo http(s)://[host] del proxy API. Edge utilizza l'URI del percorso di base per associare e inoltrare i messaggi di richiesta in arrivo al proxy API appropriato.

    Nota: il percorso base del proxy API è impostato per impostazione predefinita sul valore specificato per il campo Name convertito in lettere minuscole.

    Dopo il percorso di base sono presenti eventuali URL di risorse aggiuntive. Ecco la struttura dell'URL completa che i client utilizzeranno per chiamare il proxy API:

    https://[host]/base_path/conditional_flow_path

    Nota: il percorso di base deve essere univoco. Non puoi implementare due proxy API con lo stesso percorso di base. Se modifichi un proxy API di cui è stato eseguito il deployment e imposti il percorso di base sullo stesso valore del percorso di base di un altro proxy API, Edge annulla automaticamente il deployment del proxy API quando lo salvi. Prima di poter eseguire nuovamente il deployment del proxy API, devi modificare il percorso di base in modo che sia univoco.

    Utilizzare i caratteri jolly nei percorsi di base

    Utilizza uno o più caratteri jolly /*/ nei percorsi di base dei proxy API per garantire la compatibilità futura dei proxy API. Ad esempio, un percorso di base /team/*/members consente ai client di chiamare https://[host]/team/blue/members e https://[host]/team/green/members senza dover creare nuovi proxy API per supportare nuovi team. Tieni presente che /**/ non è supportato.
    Descrizione Una breve descrizione del proxy.
  7. Fai clic su Avanti.
  8. Nella pagina WSDL, seleziona il tipo di proxy API REST to SOAP to REST.

    Viene visualizzata una tabella che elenca le operazioni "scoperte" da Edge nel file WSDL. Puoi selezionare e configurare le operazioni da incorporare nel proxy API. La tabella è mostrata nella figura seguente.

    Nella pagina delle operazioni WSDL, il tipo di proxy API è impostato su REST to SOAP to REST e una tabella mostra una riga di risultati con l'operazione di aggiunta.

  9. Nella colonna Tipo di porta, seleziona l'insieme di operazioni che vuoi utilizzare. In WSDL, gli elementi di tipo porta definiscono le operazioni che puoi chiamare in un servizio web.
  10. Se vuoi, modifica il metodo HTTP associato all'operazione.

    Nota: Edge fa una "supposizione migliore" per determinare il metodo HTTP da utilizzare per ogni operazione. In genere è preferibile utilizzare GET perché le richieste GET possono essere memorizzate nella cache.
  11. (Facoltativo) Modifica il percorso dell'API REST per un'operazione. Il percorso verrà utilizzato come nome della risorsa nell'URL del proxy dell'API.
  12. Segui il resto della procedura guidata per aggiungere la sicurezza, selezionare gli host virtuali e l'ambiente di deployment.
  13. Nella pagina Build, fai clic su Esegui build ed esegui il deployment. Edge genera e implementa il nuovo proxy API in base al WSDL.
  14. Vai alla pagina di riepilogo del nuovo proxy API. Tieni presente che è stato creato un insieme di risorse in base alle operazioni rilevate nel file WSDL.

    Nella pagina Panoramica del proxy, l'elenco Risorse fornisce una descrizione dettagliata della nuova API, delle sue operazioni e dei suoi parametri. Puoi considerare questa representation come la documentazione di riferimento dell'API. Edge genera automaticamente questa vista del modello dell'API. Basta espandere una risorsa per visualizzarne la descrizione e le informazioni sul percorso.

Informazioni sul proxy finale

Quando Edge genera un proxy API in base a un WSDL, il proxy risultante è in realtà un flusso complesso che include criteri per la trasformazione dei dati, l'estrazione e l'impostazione di variabili, la manipolazione dei messaggi e altro ancora. Dopo aver generato un proxy in base a un WSDL, esamina il flusso risultante nella visualizzazione Sviluppa dell'interfaccia utente di gestione delle API. Qui puoi vedere esattamente quali norme sono state aggiunte.

Ad esempio, a livello di richiesta, viene utilizzato un criterio AssignMessage per impostare l'URL target. Sul lato della risposta, i criteri vengono eseguiti per trasformare la risposta da XML in JSON, estrarre la parte del corpo SOAP della risposta in una variabile e impostare il messaggio di risposta. Queste norme (e altre) vengono aggiunte automaticamente quando crei il proxy.

Specifica OpenAPI: per visualizzare la specifica OpenAPI generata automaticamente per questo proxy, visita la pagina http(s)://[proxy_domain]/[proxy_base_path]/openapi.json. Tuttavia, la conversione non è sempre accurata, poiché non tutte le regole di uno schema XML possono essere rappresentate in una specifica OpenAPI.

Creazione di un proxy passthrough per un servizio basato su SOAP

Questa sezione spiega come creare un proxy passthrough con l'opzione Proxy passthrough nella finestra di dialogo Crea nuovo proxy.

Panoramica

L'opzione Proxy passthrough ti consente di creare un proxy che trasmette il messaggio SOAP in una richiesta al servizio di backend "inalterato", semplificando notevolmente la creazione di un proxy per un servizio web basato su SOAP. Dietro le quinte, Edge gestisce automaticamente eventuali trasformazioni e altre attività di flusso. Ad esempio, se la richiesta è in formato JSON, Edge adotta misure per convertirla in un messaggio SOAP XML valido con gli spazi dei nomi corretti prima di inviarlo tramite POST al servizio. Analogamente, quando il servizio restituisce una risposta SOAP basata su XML, Edge la ritrasforma in JSON prima di restituirla al client. Inoltre, Edge configura l'endpoint target di backend, che può variare in base all'operazione SOAP.

Per questo tipo di proxy, Edge ospita il WSDL e crea un flusso nel proxy per consentirti di accedervi. L'indirizzo di questo file WSDL ospitato in Edge, http(s)://[proxy_domain]/[proxy_base_path]?wsdl, diventa il nuovo URL dell'endpoint del servizio per i client che chiamano il servizio SOAP tramite il proxy.

Passaggi di base

Edge

Per creare un proxy passthrough per un servizio basato su SOAP utilizzando l'interfaccia utente di Edge:

  1. Accedi ad apigee.com/edge.
  2. Seleziona Sviluppa > Proxy API nella barra di navigazione a sinistra.
  3. Fai clic su +Proxy.
  4. Fai clic su Servizio SOAP.
  5. Nella pagina Dettagli proxy, fornisci i dettagli WSDL.
    Campo Descrizione
    WSDL

    Seleziona l'origine del file WSDL.

    • Da indirizzo web (URL): inserisci o incolla l'URL del WSDL.
    • Dal mio computer: carica un file WSDL dalla tua directory locale. Puoi caricare più file se sono presenti dipendenze.
    Nome

    Nome del proxy API.
    Percorso di base

    Frammento URI dopo l'indirizzo http(s)://[host] del proxy API. Edge utilizza l'URI del percorso di base per associare e inoltrare i messaggi di richiesta in arrivo al proxy API appropriato.

    Nota: per i consigli di Apigee sul controllo delle versioni delle API, consulta Controllo delle versioni nell'ebook Web API Design: The Missing Link.

    Dopo il percorso di base sono presenti eventuali URL di risorse aggiuntive. Ecco la struttura completa dell'URL che i client utilizzeranno per chiamare il proxy API:

    https://[host]/base_path/conditional_flow_path

    Nota: il percorso di base deve essere univoco. Se in un secondo momento modifichi questo proxy e imposti il relativo percorso di base in modo che corrisponda a quello di un altro proxy API, il proxy API viene annullato automaticamente al salvataggio. Devi modificare il percorso di base prima di poter eseguire il nuovo deployment.

    Utilizzare un carattere jolly nei percorsi di base

    Puoi utilizzare uno o più caratteri jolly /*/ nei percorsi di base dei proxy API per garantire la compatibilità futura dei proxy. Ad esempio, un percorso di base di /team/*/members consente ai client di chiamare https://[host]/team/blue/members e https://[host]/team/green/members senza dover creare nuovi proxy API per supportare nuovi team. Tieni presente che /**/ non è supportato.

    Nota: il percorso di base del proxy API è impostato per impostazione predefinita sul valore specificato per il campo Nome convertito in lettere minuscole, a meno che non modifichi esplicitamente i contenuti nel campo Percorso di base.
    Descrizione (Facoltativo) Descrizione dell'API.
  6. Fai clic su Avanti.
  7. Nella pagina Criteri comuni della procedura guidata, configura quanto segue:
  8. Nella pagina WSDL, seleziona il tipo di proxy API Pass-Through SOAP.

  9. Seleziona un Tipo di porta dal menu a discesa per specificare l'insieme di operazioni che vuoi utilizzare. In WSDL, gli elementi di tipo porta definiscono le operazioni che puoi chiamare in un servizio web.
  10. Fai clic su Avanti.
  11. Nella pagina Host virtuali della procedura guidata, seleziona gli host virtuali a cui verrà associato il proxy API al momento del deployment. Per ulteriori informazioni, consulta Informazioni sugli host virtuali.
  12. Seleziona gli ambienti di deployment e fai clic su Crea e esegui il deployment
    Il nuovo proxy API viene creato e di cui viene eseguito il deployment nell'ambiente selezionato.
  13. Fai clic su Modifica proxy per visualizzare la pagina dei dettagli del proxy API.

Edge classico (private cloud)

Per creare un proxy passthrough per un servizio basato su SOAP utilizzando l'interfaccia utente Edge classica:

  1. Accedi a http://ms-ip:9000, dove ms-ip è l'indirizzo IP o il nome DNS del nodo del server di gestione.
  2. Seleziona API > Proxy API nella barra di navigazione in alto.
  3. Fai clic su + Proxy API.
  4. Nella procedura guidata Crea un proxy, seleziona Servizio SOAP.
  5. Fai clic su Avanti.
  6. Nella pagina Dettagli, effettua queste selezioni. Devi fare clic su Convalida dopo aver selezionato un WSDL.
    In questo campo Fai così
    WSDL

    Seleziona l'origine del file WSDL.

    • URL: inserisci l'URL del file WSDL che vuoi utilizzare.
    • File: scegli un file WSDL nel file system. Se esistono file dipendenti aggiuntivi, puoi selezionarli tutti.
    • URL di esempio: seleziona un elenco di WSDL per i servizi web disponibili pubblicamente. Sono utili per provare le funzionalità di proxy SOAP/API di Edge.
    Nome del proxy

    Questo è il nome del proxy che stai creando.
    Percorso base del proxy Il percorso base del proxy è un frammento URI che identifica in modo univoco l'API esposta da questo proxy API. API Services utilizza l'URI del percorso di base per associare e instradare i messaggi di richiesta in arrivo al proxy API appropriato. Il percorso base viene aggiunto al dominio dell'API, che viene generato automaticamente in base al nome della tua organizzazione e all'ambiente in cui è dipiegato il proxy API. È buona prassi includere un numero di versione nel nome del progetto, ad esempio /v1/delayedstockquote. Questo determinerà in che modo la tua API viene invocata dalle app di consumo.

    Nota: il percorso base del proxy è impostato per impostazione predefinita sul valore specificato per il nome del proxy convertito in minuscolo, a meno che non modifichi esplicitamente i contenuti nel campo Percorso base del proxy.
    Descrizione Una breve descrizione del proxy.

  8. Fai clic su Avanti.
  9. Nella pagina WSDL, seleziona il tipo di proxy API Pass-through SOAP.

    Nota:viene visualizzata una tabella che elenca ogni operazione WSDL e il relativo payload SOAP. Si tratta del payload che viene "tramesso" al servizio SOAP di backend.

    Nella pagina WSDL, il tipo di proxy API è impostato su SOAP pass-through e un elenco di operazioni come GetQuote è organizzato per tipo di porta.
  10. Nella colonna Tipo di porta, seleziona l'insieme di operazioni che vuoi utilizzare. In WSDL, gli elementi di tipo porta definiscono le operazioni che puoi chiamare in un servizio web.
  11. Segui il resto della procedura guidata per aggiungere la sicurezza, selezionare gli host virtuali e l'ambiente di deployment.
  12. Nella pagina Build, fai clic su Esegui build ed esegui il deployment. Edge genera e implementa il nuovo proxy API in base al WSDL.

Informazioni sul proxy finale

Quando Edge genera un proxy passthrough, il proxy risultante è in realtà un flusso complesso che include criteri per la trasformazione dei dati, l'estrazione e l'impostazione di variabili, la manipolazione dei messaggi e altro ancora. Dopo aver generato il proxy passthrough, dai un'occhiata al flusso risultante nella visualizzazione Sviluppa dell'interfaccia utente di gestione delle API. Qui puoi vedere esattamente quali norme sono state aggiunte.

Ad esempio, la figura seguente mostra la parte Preflow dell'endpoint di destinazione di un proxy passthrough. A livello di richiesta, viene utilizzato un criterio AssignMessage per impostare l'URL target. Sul lato della risposta, i criteri vengono eseguiti per trasformare la risposta da XML in JSON, estrarre la parte del corpo SOAP della risposta in una variabile e impostare il messaggio di risposta. Questi criteri (e altri) vengono aggiunti automaticamente quando crei il proxy.

Nella visualizzazione Sviluppa, nel riquadro Flusso, le frecce mostrano il flusso dalla richiesta alla risposta e le icone mostrano le norme.

WSDL ospitato in Edge: per visualizzare il WSDL ospitato in Edge generato per questo tipo di proxy, vai a http(s)://[proxy_domain]/[proxy_base_path]?wsdl.

Sviluppo avanzato di proxy SOAP-to-REST

Le sezioni precedenti hanno trattato la creazione di un proxy API SOAP-to-REST utilizzando la procedura guidata Proxy API in Edge. Tuttavia, se vuoi un controllo più granulare sulla trasformazione SOAP-to-REST, puoi bypassare l'automazione fornita dalla procedura guidata e creare un proxy aggiungendo e configurando manualmente i criteri per ottenere il comportamento che preferisci. Per ulteriori informazioni, consulta Tutorial: creazione manuale di un proxy API SOAP-to-REST in Apigee Edge.