Esposizione di un servizio SOAP come proxy API

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

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 "pass through" 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 da SOAP a REST, puoi creare un proxy utilizzando i criteri. Per saperne di più, consulta Tutorial: Manual construction of a SOAP-to-REST API proxy 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 Da REST a SOAP a REST nella procedura guidata Crea un proxy.

Panoramica

L'opzione Da REST a SOAP a REST elabora il WSDL per generare un proxy API RESTful. Edge determina dal WSDL le operazioni supportate dal 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 essere memorizzabili nella cache. Edge configura anche l'endpoint di destinazione 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 il servizio basato su SOAP utilizzando la UI Edge:

  1. Accedi a 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 WSDL.

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

    Frammento URI che viene visualizzato dopo l'indirizzo http(s)://[host] del tuo proxy API. Edge utilizza l'URI del percorso di base per abbinare e indirizzare i messaggi di richiesta in entrata al proxy API corretto.

    NOTE: il percorso di base del proxy API corrisponde per impostazione predefinita al valore specificato per il campo Name convertito in lettere minuscole.

    Dopo il percorso di base, seguono gli URL delle risorse aggiuntive. Ecco la struttura completa dell'URL che i client utilizzeranno per chiamare il proxy API:

    https://[host]/base_path/conditional_flow_path

    NOTE: 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 i caratteri jolly nei percorsi di base

    Utilizza uno o più caratteri jolly /*/ nei percorsi di base dei proxy API per preparare i tuoi proxy API per il 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 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. Vedi Aggiunta della sicurezza.
    • Supporto della condivisione delle risorse tra origini (CORS) in Sicurezza: browser. Vedi 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 pass-through.)
  10. Nella pagina Operazioni WSDL, seleziona il tipo di proxy API Da REST a SOAP a REST.

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

  11. Seleziona un Tipo di porta dal menu a discesa per specificare il set di operazioni che vuoi utilizzare. In WSDL, gli elementi di tipo porta definiscono le operazioni che puoi chiamare su 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 API.
  13. (Facoltativo) 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 il proxy API verrà associato al momento del deployment. Per saperne di più, vedi 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.

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 Servizio SOAP.
  5. Fai clic su Avanti.
  6. Nella pagina Dettagli, effettua le seguenti selezioni. Devi fare clic su Convalida dopo aver selezionato un WSDL.
    In questo campo Fai questo
    WSDL

    Seleziona l'origine del WSDL.

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

    Il nome del proxy che stai creando.
    Percorso di base proxy

    Frammento URI che viene visualizzato dopo l'indirizzo http(s)://[host] del tuo proxy API. Edge utilizza l'URI del percorso di base per abbinare e indirizzare i messaggi di richiesta in entrata al proxy API corretto.

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

    Dopo il percorso di base, seguono gli URL delle 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. 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 i caratteri jolly nei percorsi di base

    Utilizza uno o più caratteri jolly /*/ nei percorsi di base dei proxy API per preparare i tuoi proxy API per il 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 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 che Edge ha "scoperto" nel file WSDL. Puoi selezionare e configurare le operazioni che vuoi 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. Seleziona dalla colonna Tipo di porta il set di operazioni che vuoi utilizzare. In WSDL, gli elementi di tipo porta definiscono le operazioni che puoi chiamare su un servizio web.
  10. (Facoltativo) Modifica il metodo HTTP associato all'operazione.

    Nota:Edge fa una "migliore ipotesi" per determinare il metodo HTTP da utilizzare per ogni operazione. In genere è preferibile 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 API.
  12. Completa 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 Build e 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 relative operazioni e dei relativi parametri. Puoi considerare questa rappresentazione come la documentazione di riferimento dell'API. Edge genera automaticamente questa visualizzazione del modello API. Basta 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 di messaggi e altro ancora. Dopo aver generato un proxy basato su un WSDL, esamina il flusso risultante nella visualizzazione Sviluppo dell'UI di gestione delle API. Qui puoi vedere esattamente quali norme sono state aggiunte.

Ad esempio, sul lato della richiesta, viene utilizzata una policy AssignMessage per impostare l'URL di destinazione. Sul lato della risposta, le policy vengono eseguite 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. Queste norme (e altre) vengono aggiunte automaticamente quando crei il proxy.

Specifica OpenAPI: per visualizzare la specifica OpenAPI generata automaticamente per questo proxy, visita 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 pass-through per un servizio basato su SOAP

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

Panoramica

L'opzione Proxy passthrough consente di creare un proxy che passa il messaggio SOAP in una richiesta al servizio di backend "intatto", semplificando notevolmente la creazione di un proxy per un servizio web basato su SOAP. Dietro le quinte, Edge gestisce automaticamente tutte le trasformazioni e le altre attività del flusso. Ad esempio, se la richiesta è in formato JSON, Edge esegue la conversione in un messaggio SOAP XML valido con gli spazi dei nomi corretti prima di inviarlo al servizio. Analogamente, quando il servizio restituisce una risposta SOAP basata su XML, Edge la traduce di nuovo in JSON prima di restituirla al client. Inoltre, Edge configura l'endpoint di destinazione 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 WSDL ospitato su 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 pass-through per un servizio basato su SOAP utilizzando l'interfaccia utente Edge:

  1. Accedi a 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 del WSDL.
    Campo Descrizione
    WSDL

    Seleziona l'origine del WSDL.

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

    Nome del proxy API.
    Percorso di base

    Frammento URI dopo l'indirizzo http(s)://[host] del tuo proxy API. Edge utilizza l'URI del percorso di base per abbinare e indirizzare i messaggi di richiesta in entrata al proxy API corretto.

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

    Dopo il percorso di base, sono presenti eventuali URL di risorse aggiuntivi. 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 seguito modifichi questo proxy e imposti il suo percorso di base in modo che sia uguale a quello di un altro proxy API, questo proxy API viene annullato automaticamente quando lo salvi. Devi modificare il percorso di base prima di poterlo eseguire di nuovo.

    Utilizzo di un carattere jolly nei percorsi di base

    Puoi utilizzare uno o più caratteri jolly /*/ nei percorsi di base del proxy API per preparare i proxy per il 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 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 minuscolo, a meno che tu non modifichi esplicitamente il contenuto 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 set di operazioni che vuoi utilizzare. In WSDL, gli elementi di tipo 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 il proxy API verrà associato al momento del deployment. Per saperne di più, vedi Informazioni sugli host virtuali.
  12. Seleziona gli ambienti di deployment e fai clic su Crea e implementa
    Il nuovo proxy API viene creato e implementato 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 pass-through 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 le seguenti selezioni. Devi fare clic su Convalida dopo aver selezionato un WSDL.
    In questo campo Fai questo
    WSDL

    Seleziona l'origine del WSDL.

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

    Il nome del proxy che stai creando.
    Proxy Base Path Il percorso di 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 trovare e indirizzare i messaggi di richiesta in entrata al proxy API corretto. Il percorso di base viene aggiunto al dominio dell'API, che viene generato automaticamente in base al nome dell'organizzazione e all'ambiente in cui viene eseguito il deployment del proxy API. È una best practice includere un numero di versione nel nome del progetto, ad esempio /v1/delayedstockquote. Questo determinerà la modalità di chiamata dell'API da parte delle app consumer.

    Nota: il percorso di base proxy corrisponde per impostazione predefinita al valore specificato per il nome proxy convertito in minuscolo, a meno che tu non modifichi esplicitamente il contenuto nel campo Percorso di 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 relativo payload SOAP. Questo è il payload "passato" al servizio SOAP di backend.

    Nella pagina WSDL, il tipo di proxy API è impostato su Pass-Through SOAP e un elenco di operazioni come GetQuote è organizzato per tipo di porta.
  10. Seleziona dalla colonna Tipo di porta il set di operazioni che vuoi utilizzare. In WSDL, gli elementi di tipo porta definiscono le operazioni che puoi chiamare su un servizio web.
  11. Completa 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 Build e deployment. Edge genera e implementa il nuovo proxy API in base al WSDL.

Informazioni sul proxy finale

Quando Edge genera un proxy pass-through, 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 pass-through, esamina il flusso risultante nella visualizzazione Sviluppo dell'interfaccia utente di gestione delle API. Qui puoi vedere esattamente quali norme sono state aggiunte.

Ad esempio, la figura seguente mostra la parte Target Endpoint Preflow di un proxy pass-through. Sul lato della richiesta, viene utilizzata una policy AssignMessage per impostare l'URL di destinazione. Sul lato della risposta, le norme vengono eseguite 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. Queste norme (e altre) vengono aggiunte automaticamente quando crei il proxy.

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

WSDL ospitato su Edge: per visualizzare il WSDL ospitato su 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 del 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 desideri. Per saperne di più, vedi Tutorial: creazione manuale di un proxy API SOAP-to-REST in Apigee Edge.