Esposizione di un servizio SOAP come proxy API

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

Questo argomento spiega come creare proxy API per i servizi web basati su SOAP. Puoi creare due tipi di proxy SOAP in Edge. 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 su come trasformare un servizio SOAP in un servizio REST con Apigee Edge utilizzando la procedura guidata proxy API. Tuttavia, per avere un maggiore controllo sulla trasformazione da SOAP a REST, puoi creare un proxy utilizzando i criteri. Per maggiori informazioni, consulta Tutorial: creazione manuale di un proxy API da SOAP a 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 WSDL per generare un proxy API RESTful. Edge determina in base al WSDL le operazioni supportate, i parametri di input e così via del servizio. Edge "prevede" quale metodo HTTP utilizzare per ogni operazione. In genere, Edge converte le operazioni in richieste GET, che hanno il vantaggio di essere memorizzabili nella cache. Edge configura anche l'endpoint di destinazione del backend, che può variare in base alle operazioni SOAP.

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

Passaggi di base

Perimetrale

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

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

    Seleziona l'origine del file WSDL.

    • Da indirizzo web (URL): inserisci o incolla l'URL della pagina WSDL.
    • Dal mio computer: carica un file WSDL dalla directory locale. Puoi caricare più file in caso di dipendenze.
  6. Fai clic su Convalida per convalidare il codice WSDL.
  7. Inserisci i seguenti dettagli 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 instradare i messaggi di richiesta in entrata al proxy API appropriato.

    NOTA: per impostazione predefinita, il percorso di base del proxy API utilizza il valore specificato per il campo Name convertito in lettere minuscole.

    Seguendo il percorso di base sono presenti eventuali URL di risorse aggiuntivi. Di seguito è riportata la struttura completa dell'URL che i client utilizzeranno per chiamare il tuo proxy API:

    https://[host]/base_path/conditional_flow_path

    NOTA: il percorso di base deve essere univoco. Non puoi eseguire il deployment di 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 caratteri jolly nei percorsi di base

    Utilizza uno o più caratteri jolly /*/ nei percorsi di base dei proxy API per rendere i tuoi proxy API a prova di futuro. 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 che tu debba creare nuovi proxy API per supportare i 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 per l'autorizzazione di sicurezza in Sicurezza: autorizzazione. Vedi Aggiungere la sicurezza.
    • Supporto per la condivisione delle risorse tra origini (CORS) in Sicurezza: browser. Vedi Aggiunta del supporto per CORS.
    • Quote per proteggere il tuo servizio di backend dal traffico elevato entro i limiti di quota. Vedi Quote. Non disponibile se è selezionata l'opzione Autorizzazione passthrough.
  10. Nella pagina Operazioni WSDL, seleziona il tipo di proxy API da REST a SOAP a REST.

    Viene visualizzata una tabella con l'elenco delle operazioni che Edge ha "rilevato" nel file WSDL. Puoi selezionare e configurare le operazioni che vuoi incorporare nel proxy API. La tabella è mostrata nella figura che segue.

  11. Seleziona un Tipo di porta dal menu a discesa per specificare il gruppo di operazioni che vuoi utilizzare. In WSDL, gli elementi del tipo di porta definiscono le operazioni che puoi chiamare su un servizio web.
  12. Facoltativamente, modifica il Percorso dell'API REST per un'operazione. Il percorso verrà utilizzato come nome della risorsa nell'URL del proxy API.
  13. Facoltativamente, 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 si collegherà il proxy API al momento del deployment. Per saperne di più, consulta Informazioni sugli host virtuali.
  16. Fai clic su Avanti.
  17. Seleziona gli ambienti di deployment e fai clic su Crea ed esegui il deployment.
    Viene creato il nuovo proxy API e ne viene eseguito il deployment nell'ambiente selezionato.
  18. Fai clic su Modifica proxy per visualizzare la pagina dei dettagli del proxy API.

Classic Edge (private cloud)

Per creare un proxy API RESTful per un servizio basato su SOAP utilizzando la UI classica di Edge:

  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 il 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 questo

    Seleziona l'origine del file WSDL.

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

    Questo è il nome del proxy che stai creando.
    Percorso di 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 instradare i messaggi di richiesta in entrata al proxy API appropriato.

    Nota: per impostazione predefinita, il percorso di base del proxy API utilizza il valore specificato per il campo Name convertito in lettere minuscole.

    Seguendo il percorso di base sono presenti eventuali URL di risorse aggiuntivi. Di seguito è riportata la struttura completa dell'URL che i client utilizzeranno per chiamare il tuo proxy API:

    https://[host]/base_path/conditional_flow_path

    Nota: il percorso di base deve essere univoco. Non puoi eseguire il deployment di 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 caratteri jolly nei percorsi di base

    Utilizza uno o più caratteri jolly /*/ nei percorsi di base dei proxy API per rendere i tuoi proxy API a prova di futuro. 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 che tu debba creare nuovi proxy API per supportare i 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 da REST a SOAP a REST.

    Viene visualizzata una tabella con l'elenco delle operazioni che Edge ha "rilevato" nel file WSDL. Puoi selezionare e configurare le operazioni che vuoi incorporare nel proxy API. La tabella è mostrata nella figura che segue.

    Nella pagina Operazioni WSDL, il tipo di proxy API è impostato su REST, SOAP e REST; 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 del tipo di porta definiscono le operazioni che puoi chiamare su un servizio web.
  10. Facoltativamente, modifica il metodo HTTP associato all'operazione.

    Nota: Edge fa una "ipotesi 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. Facoltativamente, modifica il percorso dell'API REST per un'operazione. Il percorso verrà utilizzato come nome della risorsa nell'URL del proxy API.
  12. Fai clic sulle altre parti della procedura guidata per aggiungere sicurezza, selezionare gli host virtuali e l'ambiente di deployment.
  13. Nella pagina Crea, fai clic su Crea ed esegui il deployment. Edge genera ed esegue il deployment del nuovo proxy API in base al protocollo 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. Questa rappresentazione può essere considerata come la documentazione di riferimento dell'API. Edge genera automaticamente questa visualizzazione del modello API. È sufficiente espandere una risorsa per visualizzarne la descrizione e le informazioni sul percorso.

Informazioni sul proxy finale

Quando Edge genera un proxy API basato su 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 basato su un protocollo WSDL, dai un'occhiata al flusso risultante nella visualizzazione Sviluppo dell'interfaccia utente di gestione delle API. Qui puoi vedere esattamente quali criteri sono stati aggiunti.

Ad esempio, sul lato delle richieste, viene utilizzato un criterio di AssegnaMessage per impostare l'URL di destinazione. Sul lato della risposta, i criteri vengono eseguiti per trasformare la risposta da XML a 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.

Specifiche 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 pass-through nella finestra di dialogo Crea nuovo proxy.

Panoramica

L'opzione proxy pass-through consente di creare un proxy che passa il messaggio SOAP in una richiesta al servizio di backend "intoccato", semplificando la creazione di un proxy per un servizio web basato su SOAP. Dietro le quinte, Edge gestisce automaticamente tutte le trasformazioni e altre attività di flusso. Ad esempio, se la richiesta è in formato JSON, Edge adotta alcuni passaggi per convertirla in un messaggio SOAP XML valido con gli spazi dei nomi corretti prima di POSTARE nel servizio. Analogamente, quando il servizio restituisce una risposta SOAP basata su XML, Edge la traduce nuovamente in JSON prima di restituirla al client. Inoltre, Edge configura l'endpoint di destinazione del backend, che può variare in base alle operazioni SOAP.

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

Passaggi di base

Perimetrale

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

  1. Accedi ad apigee.com/edge.
  2. Seleziona Sviluppo > 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

    Seleziona l'origine del file WSDL.

    • Da indirizzo web (URL): inserisci o incolla l'URL della pagina WSDL.
    • Dal mio computer: carica un file WSDL dalla directory locale. Puoi caricare più file in caso di 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 instradare i messaggi di richiesta in entrata al proxy API appropriato.

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

    Dopo il percorso di base ci sono eventuali URL di risorse aggiuntivi. Di seguito è riportata la struttura completa dell'URL che i client utilizzeranno per chiamare il tuo 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 deployment di questo proxy API viene annullato automaticamente quando lo salvi. Devi modificare il percorso di base prima di poterne eseguire nuovamente il deployment.

    Utilizzo di un carattere jolly nei percorsi di base

    Puoi utilizzare uno o più caratteri jolly /*/ nei percorsi di base dei proxy API per rendere i tuoi proxy a prova di futuro. 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 che tu debba creare nuovi proxy API per supportare i nuovi team. Tieni presente che /**/ non è supportato.

    Nota: per impostazione predefinita, il percorso di base del proxy API utilizza il 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 il gruppo di operazioni che vuoi utilizzare. In WSDL, gli elementi del tipo di porta definiscono le operazioni che puoi chiamare su un servizio web.
  10. Fai clic su Avanti.
  11. Nella pagina Host virtuali della procedura guidata, seleziona gli host virtuali a cui si collegherà il proxy API al momento del deployment. Per maggiori informazioni, consulta Informazioni sugli host virtuali.
  12. Seleziona gli ambienti di deployment e fai clic su Crea ed esegui il deployment.
    Viene creato e eseguito il deployment del nuovo proxy API nell'ambiente selezionato.
  13. Fai clic su Modifica proxy per visualizzare la pagina dei dettagli del proxy API.

Classic Edge (private cloud)

Per creare un proxy passthrough a un servizio basato su SOAP utilizzando la UI Classic Edge:

  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 il 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 questo

    Seleziona l'origine del file WSDL.

    • URL: inserisci l'URL del file WSDL che vuoi utilizzare.
    • File: scegli un file WSDL sul file system. Nei casi in cui ci siano altri file dipendenti, puoi selezionarli tutti.
    • URL di esempio: seleziona da un elenco di WSDL per i servizi web disponibili pubblicamente. Sono utili per provare le funzionalità proxy SOAP/API di Edge.
    Nome proxy

    Questo è il nome del proxy che stai creando.
    Percorso di base del proxy Il percorso base del proxy è un frammento URI che identifica in modo univoco l'API esposta da questo proxy API. I servizi API utilizzano l'URI del percorso di base per associare e indirizzare i messaggi di richiesta in entrata al proxy API appropriato. Il percorso di base viene aggiunto al dominio dell'API, che viene generato automaticamente in base al nome della tua organizzazione e all'ambiente in cui è stato eseguito il deployment del proxy API. Una best practice consiste nell'includere un numero di versione nel nome del progetto, ad esempio /v1/delayedstockquote. Questo determinerà il modo in cui la tua API viene richiamata dalle app consumer.

    Nota: il percorso di base proxy utilizza per impostazione predefinita il valore specificato per il nome del proxy convertito in lettere minuscole, a meno che non modifichi esplicitamente il contenuto nel campo Percorso base 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 rispettivo payload SOAP. Si tratta del payload che viene "trasmesso" al servizio di backend SOAP.

    Nella pagina WSDL, il tipo di proxy API è impostato su SOAP pass-through e un elenco di operazioni come GetQuote è organizzato in base al tipo di porta.
  10. Nella colonna Tipo di porta seleziona l'insieme di operazioni che vuoi utilizzare. In WSDL, gli elementi del tipo di porta definiscono le operazioni che puoi chiamare su un servizio web.
  11. Fai clic sulle altre parti della procedura guidata per aggiungere sicurezza, selezionare gli host virtuali e l'ambiente di deployment.
  12. Nella pagina Crea, fai clic su Crea ed esegui il deployment. Edge genera ed esegue il deployment del nuovo proxy API in base al protocollo 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 Sviluppo dell'interfaccia utente di gestione delle API. Qui puoi vedere esattamente quali criteri sono stati aggiunti.

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

Nella vista Sviluppo, nel riquadro Flusso, le frecce raffigurano il flusso dalla richiesta alla risposta e le icone raffigurano i criteri.

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

Sviluppo avanzato di proxy SOAP-REST

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