Crea un semplice proxy API

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

Apigee Edge ti consente di esporre rapidamente i servizi di backend sotto forma di API. A tale scopo, crea un proxy API che fornisce un'interfaccia per il servizio di backend che vuoi esporre. Devi solo fornire l'indirizzo di rete per il servizio di backend, insieme ad alcune informazioni che Edge utilizza per creare il proxy API esposto agli sviluppatori.

Il proxy API disaccoppia l'implementazione del servizio di backend dall'API utilizzata dagli sviluppatori. Questo protegge gli sviluppatori da future modifiche ai servizi di backend. Man mano che aggiorni i servizi di backend, gli sviluppatori, isolati da queste modifiche, possono continuare a chiamare l'API senza interruzioni.

Guarda questo video per una panoramica della procedura di creazione di un proxy API.

Creazione di un proxy API mediante l'interfaccia utente

Il modo più semplice per creare un proxy API è utilizzare la procedura guidata Crea proxy.

Perimetrale

Per accedere alla procedura guidata Crea proxy 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.

La procedura guidata Crea proxy visualizza e guida i passaggi per generare e aggiungere funzionalità minime a un proxy API.

Prima pagina della procedura guidata Crea proxy in cui viene richiesto di selezionare il proxy inverso, il servizio SOAP, Nessun target o il bundle proxy per personalizzare il flusso della procedura guidata.

Classic Edge (private cloud)

Per accedere alla procedura guidata Crea proxy utilizzando l'interfaccia utente 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.

La procedura guidata Crea proxy visualizza e guida i passaggi per generare e aggiungere funzionalità minime a un proxy API.

Prima pagina della procedura guidata Crea proxy in cui viene richiesto di selezionare il proxy inverso, il servizio SOAP, Nessun target o il bundle proxy per personalizzare il flusso della procedura guidata.

La prima pagina della procedura guidata consente di creare un proxy API dalle seguenti origini:

Tipo Descrizione
Proxy inverso (più comune)

Un proxy API che indirizza le richieste in entrata ai servizi di backend HTTP esistenti. Può essere un'API JSON o XML. Consulta la sezione Creazione di un proxy inverso per un servizio HTTP più avanti in questa sezione.

Fai clic su Use OpenAPI Spec (Utilizza specifiche OpenAPI) per generare il proxy da una specifica OpenAPI valida. Per ulteriori informazioni su questa opzione, consulta la sezione Utilizzo delle specifiche OpenAPI per generare proxy più avanti in questa sezione.

Servizio SOAP Un proxy API generato da un file WSDL. Vedi Esposizione di un servizio web basato su SOAP come proxy API.
Nessun target

Un proxy API senza backend API ("nessuna destinazione"). Come per la creazione di un proxy inverso per un servizio HTTP descritto in precedenza, tranne per il fatto che non dovrai specificare un'API esistente durante la definizione dei dettagli del proxy API.

Fai clic su Use OpenAPI Spec (Utilizza specifiche OpenAPI) per generare il proxy da una specifica OpenAPI valida. Per ulteriori informazioni su questa opzione, consulta la sezione Utilizzo delle specifiche OpenAPI per generare proxy più avanti in questa sezione.

Target ospitato

Un proxy API che esegue il routing a un'applicazione Node.js di cui viene eseguito il deployment nell'ambiente destinazioni ospitate. Consulta la panoramica dei target ospitati.

Carica bundle proxy Un bundle di proxy API esistente (ad esempio uno dei proxy API di esempio disponibili in GitHub). Consulta Importazione di un proxy API da un bundle proxy API.

Le seguenti sezioni descrivono come creare un proxy API utilizzando ciascuna origine.

Creazione di un proxy inverso per un servizio HTTP

Edge genera proxy inversi basati su due informazioni:

  • URL del servizio di backend
  • Percorso URI che identifica in modo univoco l'API che verrà esposta dal proxy API alle app consumer

L'URL del servizio di backend in genere rappresenta un'applicazione abilitata per il servizio di proprietà della tua organizzazione. Può anche puntare a un'API disponibile pubblicamente. L'API o il servizio possono essere sotto il tuo controllo (ad esempio, un'applicazione HR interna o un'applicazione Rails nel cloud) oppure può essere un'API o un servizio di terze parti (ad esempio, Twitter o Instagram).

Perimetrale

  1. Accedi alla procedura guidata Crea proxy, descritta in Creazione di un proxy API utilizzando l'interfaccia utente precedentemente in questa sezione.
  2. Nella procedura guidata Crea proxy, fai clic su Inverti proxy (più comune). Per generare il proxy da una specifica OpenAPI valida esistente, fai clic su Utilizza le specifiche OpenAPI. Per maggiori dettagli su questa opzione, consulta la sezione Utilizzo delle specifiche OpenAPI per generare proxy di seguito.
  3. Nella pagina Dettagli della procedura guidata, inserisci le seguenti informazioni.
    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.
    Target (API esistente) URL del servizio di backend richiamato da questo proxy API.
  4. Nella pagina Criteri comuni della procedura guidata, configura quanto segue:
    • Requisiti per l'autorizzazione di sicurezza in Sicurezza: autorizzazione. Consulta Aggiungere la sicurezza più avanti in questa sezione.
    • Supporto per la condivisione delle risorse tra origini (CORS) in Sicurezza: browser. Consulta Aggiunta del supporto per CORS più avanti in questa sezione.
    • 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.
    • Applicazione dei limiti di monetizzazione per le organizzazioni abilitate alla monetizzazione nella sezione Monetizzazione. Vedi Applicare i limiti di monetizzazione sui proxy API.
  5. 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.
  6. Nella pagina Riepilogo, seleziona gli ambienti di deployment, se vuoi, e fai clic su Crea ed esegui il deployment.

    È stato creato il nuovo proxy API e ne è stato eseguito il deployment nell'ambiente selezionato.

  7. Fai clic su Modifica proxy per visualizzare la pagina dei dettagli del proxy API.

Classic Edge (private cloud)

  1. Accedi alla procedura guidata Crea proxy, descritta in Creazione di un proxy API utilizzando l'interfaccia utente precedentemente in questa sezione.
  2. Nella procedura guidata Crea un proxy, seleziona Inverti proxy (più comune). Per generare il proxy da una specifica OpenAPI valida esistente, fai clic su Use OpenAPI (Utilizza OpenAPI). Per maggiori dettagli su questa opzione, consulta la sezione Utilizzo delle specifiche OpenAPI per generare proxy di seguito.
  3. Fai clic su Avanti.
  4. Nella pagina Dettagli della procedura guidata, inserisci le seguenti informazioni.
    Campo Descrizione
    Nome proxy Il nome visualizzato per l'API.
    Percorso base proxy

    Il percorso base del proxy è un frammento URI dopo l'indirizzo http(s)://[host] del proxy API. Edge utilizza l'URI del percorso di base per abbinare e indirizzare 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 utilizza 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.

    API esistente L'URL richiamato da API Platform per conto delle app che chiamano la tua API tramite l'URL del proxy API.
    Descrizione La descrizione dell'API.
  5. Nella pagina Sicurezza della procedura guidata, configura quanto segue:
  6. 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.
  7. Seleziona gli ambienti di deployment e fai clic su Crea e implementa
    Viene inviata una conferma che conferma l'avvenuta creazione e deployment del nuovo proxy API nell'ambiente selezionato.
  8. Fai clic su Visualizza il proxy <nome proxy> nell'editor per visualizzare la pagina dei dettagli del proxy API.

Importazione di un proxy API da un bundle proxy API

Spesso definisci i proxy API come una raccolta di file XML, insieme ad altri file di supporto. Se definisci i proxy API come un insieme di file esterni a Edge, puoi gestirli in un sistema di controllo del codice sorgente e quindi importarli in Edge per i test e il deployment.

Guarda questo video per scoprire come creare e importare un proxy API da un bundle proxy API.

Perimetrale

Per importare i proxy API da un bundle proxy API:

  1. Accedi alla procedura guidata Crea proxy, descritta in Creazione di un proxy API utilizzando l'interfaccia utente precedentemente in questa sezione.
  2. Fai clic su Carica bundle proxy.
  3. Nella pagina Carica bundle proxy della procedura guidata proxy, inserisci le seguenti informazioni.

    Campo Descrizione
    Pacchetto ZIP ZIP contenente la configurazione del proxy API. Trascina o fai clic per accedere al file.
    Nome Nome visualizzato per l'API. Il valore predefinito è il nome del file ZIP senza l'estensione.
  4. Fai clic su Avanti.
  5. Nella pagina Riepilogo, seleziona gli ambienti di deployment, se vuoi, e fai clic su Crea ed esegui il deployment.
    Viene visualizzata una conferma che conferma l'avvenuta creazione del nuovo proxy API.
  6. Fai clic su Modifica proxy per visualizzare la pagina dei dettagli del proxy API.

Classic Edge (private cloud)

  1. Accedi alla procedura guidata Crea proxy, descritta in Creazione di un proxy API utilizzando l'interfaccia utente precedentemente in questa sezione.
  2. Nella procedura guidata Crea un proxy, seleziona Bundle di proxy.
  3. Fai clic su Avanti.
  4. Nella pagina Dettagli della procedura guidata proxy, inserisci le seguenti informazioni.

    Campo Descrizione
    Pacchetto ZIP Fai clic su Choose File (Scegli file) e vai al file ZIP contenente la configurazione del proxy API.
    Nome proxy Il nome visualizzato per l'API.
  5. Esamina le informazioni sulla build e fai clic su Crea.
    In caso di esito positivo, viene visualizzato un messaggio ed Edge esegue automaticamente il deployment del proxy API importato nell'ambiente selezionato nella tua organizzazione. L'API esposta dal proxy API è disponibile per essere richiamata.
  6. Fai clic su Visualizza il proxy <nome proxy> nell'editor per visualizzare la pagina dei dettagli del proxy API.
  7. Per eseguire il deployment del proxy, fai clic sul menu a discesa Deployment, seleziona l'ambiente in cui eseguire il deployment e rispondi alla richiesta.

Esposizione di un servizio web basato su SOAP come proxy API

Nella procedura guidata Crea proxy, fai clic su Servizio SOAP e segui la procedura guidata per creare un proxy passthrough o basato su REST per un servizio SOAP. Per maggiori dettagli, consulta Esposizione di un servizio SOAP come proxy API.

Maggiore sicurezza

Nella pagina Criteri comuni (Edge) o Sicurezza (Classic Edge) della procedura guidata Crea proxy, seleziona il tipo di autorizzazione di sicurezza che vuoi aggiungere. La seguente tabella riassume le opzioni disponibili:

Autorizzazione di sicurezza Descrizione
Chiave API Aggiunge una semplice verifica della chiave API al proxy API che stai definendo. In risposta, la piattaforma API aggiunge un criterio VerificationAPIKey e un criterio AssegnaMessage al proxy API. Il criterio VerificationAPIKey convalida le chiavi API presentate richiedendo app. Il criterio di AssegnaMessage rimuove la chiave API, fornita come parametro di query, nella chiamata API, dalla richiesta inoltrata al server di backend.
OAuth 2.0 Aggiunge l'autenticazione basata su OAuth 2.0 al proxy API. Apigee Edge aggiunge automaticamente due criteri al tuo proxy API: un criterio per verificare un token di accesso e un altro per rimuovere il token di accesso dal messaggio prima di inoltrarlo al tuo servizio di backend. Per scoprire come ottenere un token di accesso, consulta OAuth.
Pass-through (nessuna autorizzazione) Nessuna autorizzazione richiesta. Le richieste vengono passate al backend senza controlli di sicurezza su Apigee Edge.

Aggiunta del supporto per CORS

CORS (Cross-Origin Resource Sharing) è un meccanismo standard che consente a un browser web di effettuare richieste dirette a un altro dominio. Lo standard CORS definisce un insieme di intestazioni HTTP che i browser web e i server utilizzano per implementare la comunicazione tra domini.

Puoi aggiungere il supporto di CORS all'API selezionando Aggiungi intestazioni CORS nella pagina Criteri comuni (Edge) o Sicurezza (Classic Edge) della procedura guidata Crea proxy.

Per informazioni più dettagliate sul supporto CORS, inclusa l'aggiunta del supporto preflight CORS a un proxy, consulta Aggiunta del supporto CORS a un proxy API.

Utilizzo delle specifiche OpenAPI per generare proxy

Questa sezione illustra l'opzione Utilizza OpenAPI disponibile per generare da una specifica OpenAPI i seguenti tipi di proxy API: inverso, Node.js o nessun target.

Che cos'è una specifica OpenAPI?

Logo Open API Initiative"Open API Initiative (OAI) è incentrata sulla creazione, lo sviluppo e la promozione di un formato di descrizione API indipendente dal fornitore e basato sulla specifica Swagger." Per ulteriori informazioni sull'Open API Initiative, visita il sito https://openapis.org.

Una specifica OpenAPI utilizza un formato standard per descrivere un'API RESTful. Scritta in formato JSON o YAML, una specifica OpenAPI è leggibile dalla macchina, ma è anche facile da leggere e capire per le persone. La specifica descrive questi elementi di un'API come percorso di base, percorsi e verbi, intestazioni, parametri di query, operazioni, tipi di contenuti, descrizioni delle risposte e altro ancora. Inoltre, una specifica OpenAPI viene comunemente utilizzata per generare la documentazione dell'API.

Ecco un frammento di una specifica OpenAPI che descrive il servizio target fittizio di Apigee, http://mocktarget.apigee.net. Per ulteriori informazioni, consulta https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

Tramite la procedura guidata Crea proxy puoi importare una specifica OpenAPI e utilizzarla per generare un proxy API. Una volta generato il proxy, puoi utilizzare l'interfaccia utente Edge per svilupparlo ulteriormente aggiungendo criteri, implementando codice personalizzato e così via, proprio come qualsiasi proxy Edge.

Creazione di un proxy API da una specifica OpenAPI

Crea i proxy API da una specifica OpenAPI. In pochi clic sarà disponibile un proxy API con percorsi, parametri, flussi condizionali ed endpoint di destinazione generati automaticamente. Successivamente, puoi aggiungere funzionalità quali la sicurezza OAuth, la limitazione della frequenza e la memorizzazione nella cache.

Nella procedura guidata Crea proxy, fai clic su Utilizza specifiche OpenAPI e segui la procedura guidata per creare un proxy inverso o nessun proxy di destinazione da una specifica OpenAPI. Per maggiori dettagli, consulta Creare un proxy API da una specifica OpenAPI.

Guarda questo video per imparare a creare un proxy API da una specifica OpenAPI.

Aggiornamento dei flussi in un proxy API utilizzando una specifica OpenAPI

Dopo aver creato un proxy API da una specifica OpenAPI, se modifichi la specifica per aggiungere altri percorsi delle risorse, puoi utilizzare la specifica per aggiungere i flussi condizionali associati al proxy API.

Per aggiornare i flussi in un proxy API utilizzando una specifica OpenAPI:

  1. Aggiungi i nuovi percorsi delle risorse alla specifica OpenAPI. Consulta la sezione Modifica di una specifica OpenAPI esistente.
  2. Apri il proxy API nell'interfaccia utente e fai clic sulla scheda Sviluppo.
  3. Nel navigatore, fai clic su + accanto all'endpoint del proxy da aggiornare.
    Viene visualizzata la finestra di dialogo Nuovo flusso condizionale.
  4. Fai clic su From OpenAPI (Da OpenAPI) se non è già selezionato.
    Se nella specifica OpenAPI sono presenti risorse a cui non è associato un flusso condizionale nel proxy API, queste vengono elencate nella finestra di dialogo, come mostrato nella figura seguente. Risorse che non sono rappresentate come flussi nel proxy API attuale. Questo esempio include /loveapis, /ip, /json e /xml.
  5. Seleziona ciascuna delle risorse per cui vuoi aggiungere un flusso condizionale.
  6. Fai clic su Aggiungi.

I flussi condizionali vengono aggiunti al proxy API.

Creazione di una nuova revisione di un proxy API

Crea una nuova revisione di un proxy API, come descritto di seguito.

Perimetrale

Per creare una nuova revisione di un proxy API 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 sul proxy API nell'elenco da copiare.
  4. Seleziona Progetto > Salva come nuova revisione.

Classic Edge (private cloud)

Per creare una nuova revisione di un proxy API utilizzando l'interfaccia utente 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 sul proxy API nell'elenco da copiare.
  4. Seleziona Progetto > Salva come nuova revisione.

Copia di un proxy API

Copia un proxy API esistente in un nuovo proxy API, come descritto di seguito.

Perimetrale

Per copiare un proxy API 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 sul proxy API nell'elenco da copiare.
  4. Seleziona Progetto > Salva come nuovo proxy API.
  5. Nella finestra di dialogo Salva come nuovo proxy, inserisci il nome del nuovo proxy API.
  6. Fai clic su Aggiungi.

Classic Edge (private cloud)

Per copiare un proxy API utilizzando l'interfaccia utente 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 sul proxy API nell'elenco da copiare.
  4. Seleziona Progetto > Salva come nuovo proxy API.
  5. Nella finestra di dialogo Salva come nuovo proxy, inserisci il nome del nuovo proxy API.
  6. Fai clic su Aggiungi.

Backup di un proxy API

Puoi eseguire il backup di un proxy API esistente come insieme di file XML in un bundle proxy API. Una volta esportato in un bundle, puoi importare il proxy API in un nuovo proxy, come descritto in Importazione di un proxy API da un bundle proxy API in precedenza in questa sezione. Per maggiori informazioni, vedi Scaricare i proxy API.

Creazione di un proxy API mediante l'API

Per creare un proxy API utilizzando l'API, vedi API proxy API.