Crea un proxy API da una specifica OpenAPI | Apigee Edge

In questo tutorial imparerai a creare un proxy API Edge da una specifica OpenAPI utilizzando la UI di gestione di Apigee Edge. Quando chiami il proxy API con un client HTTP, ad esempio cURL, il proxy API invia la richiesta al servizio target di simulazione di Apigee.

Informazioni sull'Open API Initiative

"L'Open API Initiative (OAI) si concentra sulla creazione, l'evoluzione e la promozione di un formato di descrizione API indipendente dal fornitore basato sulla specifica Swagger." Per saperne di più sull'Open API Initiative, visita la pagina 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 comprendere per le persone. La specifica descrive elementi di un API come il percorso di base, i percorsi e i verbi, le intestazioni, i parametri di query, le operazioni, i tipi di contenuti, descrizioni delle risposte e altro ancora. Inoltre, una specifica OpenAPI viene comunemente utilizzata per generare la documentazione dell'API.

Informazioni sul servizio target di simulazione di Apigee

Il servizio target di simulazione di Apigee utilizzato in questo tutorial è ospitato su Apigee e restituisce dati semplici. Non richiede una chiave API o un token di accesso. Infatti, puoi accedervi in un browser web. Provalo facendo clic su:

http://mocktarget.apigee.net

Il servizio target restituisce il saluto Hello, guest!

Per informazioni sull'insieme completo di API supportate dal servizio target di simulazione, fai clic su: quanto segue:

http://mocktarget.apigee.net/help

Che cosa ti serve

Un account Apigee Edge. Se non hai un account, puoi registrarti seguendo le istruzioni riportate in Creazione di un account Apigee Edge account.
Una specifica OpenAPI. In questo tutorial utilizzerai la specifica OpenAPI mocktarget.yaml che descrive il servizio target di simulazione di Apigee, http://mocktarget.apigee.net. Per saperne di più, visita la pagina https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
cURL installato sulla tua macchina per effettuare chiamate API dalla riga di comando o un browser web.

Creare il proxy API

Edge

Per creare il proxy API da una specifica OpenAPI utilizzando la UI di Edge:

Accedi a https://apigee.com/edge.
Fai clic su Proxy API nella finestra principale.
In alternativa, puoi selezionare Sviluppa > Proxy API nella barra di navigazione a sinistra.
Fai clic su + Proxy.
Nella procedura guidata Crea proxy, fai clic su Utilizza specifica OpenAPI per il modello Proxy inverso (più comune).
Fai clic su Importa da URL e inserisci le seguenti informazioni:
- URL specifica OpenAPI: percorso del contenuto non elaborato su GitHub per la specifica OpenAPI nel campo URL:
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- Nome specifica: nome della specifica OpenAPI, ad esempio Target di simulazione.
  Questo nome viene utilizzato per archiviare la specifica OpenAPI nello store delle specifiche. Vedi Gestire le specifiche.

Fai clic su Importa.

Viene visualizzata la pagina dei dettagli della procedura guidata Crea proxy. I campi vengono precompilati utilizzando i valori definiti nella specifica OpenAPI, come mostrato di seguito

La seguente tabella descrive i valori predefiniti che vengono precompilati utilizzando le proprietà della specifica OpenAPI. Dopo la tabella viene mostrato un estratto della specifica OpenAPI che illustra le proprietà utilizzate.

Campo	Descrizione	Predefinito
Nome	Nome del proxy API. Ad esempio: `Mock-Target-API`.	Proprietà `title` della specifica OpenAPI con gli spazi sostituiti da trattini
Percorso di base	Componente del percorso che identifica in modo univoco questo proxy API all'interno dell'organizzazione. L'URL pubblico di questo proxy API è composto dal nome dell'organizzazione, da un ambiente in cui è stato eseguito il deployment del proxy API e da questo percorso di base. Ad esempio: `http://myorg-test.apigee.net/mock-target-api`	Contenuto del campo Nome convertito in minuscolo
Descrizione	Descrizione del proxy API.	Proprietà `description` della specifica OpenAPI
Target (API esistente)	URL di destinazione richiamato per conto di questo proxy API. È possibile utilizzare qualsiasi URL accessibile tramite internet aperto. Ad esempio: `http://mocktarget.apigee.net`	Proprietà `servers` della specifica OpenAPI

Di seguito è riportato un estratto della specifica OpenAPI che mostra le proprietà utilizzate per precompilare i campi.

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
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

Modifica il campo Descrizione come segue: API proxy for the Apigee mock target service endpoint.
Fai clic su Avanti.
Nella pagina Policy comuni, in Sicurezza: autorizzazione, assicurati che sia selezionata l'opzione Pass-through (nessuna autorizzazione) e fai clic su Avanti:
Nella pagina Flussi, assicurati che siano selezionate tutte le operazioni.
Suggerimento: i flussi condizionali vengono generati automaticamente dalle operazioni definite nell'oggetto paths della specifica OpenAPI. I flussi condizionali indicano a Edge: "Quando vedi questo, esegui questa logica". Ad esempio, quando una chiamata API è un GET sulla risorsa /xml (la condizione), trasforma la risposta in JSON (tramite una policy collegata al flusso condizionale). Viene eseguito un solo flusso per transazione: il primo flusso la cui condizione restituisce true.
Fai clic su Avanti.
Nella pagina Host virtuali , seleziona default e secure e fai clic su Avanti.
Nella pagina Riepil1ogo, assicurati che l'ambiente Test sia selezionato in Deployment facoltativo e fai clic su Crea ed esegui il deployment:

Apigee crea il nuovo proxy API ed esegue il deployment nell'ambiente di test:
Fai clic su Modifica proxy per visualizzare la pagina Panoramica del proxy API proxy.

Classic Edge (Private Cloud)

Per creare il proxy API da una specifica OpenAPI utilizzando la UI di Classic Edge:

Accedi a https://apigee.com/edge.
Fai clic su Proxy API nella finestra principale.
In alternativa, puoi selezionare Sviluppa > Proxy API nella barra di navigazione a sinistra.
Fai clic su + Proxy.
Nella procedura guidata Crea proxy, seleziona Proxy inverso (più comune) e fai clic su Utilizza OpenAPI.
Fai clic su Importa da un URL, inserisci un nome per la specifica OpenAPI e il percorso del contenuto non elaborato su GitHub per la specifica OpenAPI nel campo URL:

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
Fai clic su Seleziona.

Fai clic su Avanti.

Viene visualizzata la pagina dei dettagli della procedura guidata Crea proxy. I campi vengono precompilati utilizzando i valori definiti nella specifica OpenAPI, come mostrato nella figura seguente.

La seguente tabella descrive i valori predefiniti che vengono precompilati utilizzando le proprietà della specifica OpenAPI. Dopo la tabella viene mostrato un estratto della specifica OpenAPI che illustra le proprietà utilizzate.

Campo	Descrizione	Predefinito
Nome proxy	Nome del proxy API. Ad esempio: `Mock-Target-API`.	Proprietà `title` della specifica OpenAPI con gli spazi sostituiti da trattini
Percorso di base del proxy	Componente del percorso che identifica in modo univoco questo proxy API all'interno dell'organizzazione. L'URL pubblico di questo proxy API è composto dal nome dell'organizzazione, da un ambiente in cui è stato eseguito il deployment del proxy API e da questo percorso di base. Ad esempio: `http://myorg-test.apigee.net/mock-target-api`	Contenuto del campo Nome convertito in minuscolo
API esistente	URL di destinazione richiamato per conto di questo proxy API. È possibile utilizzare qualsiasi URL accessibile tramite internet aperto. Ad esempio: `http://mocktarget.apigee.net`	Proprietà `servers` della specifica OpenAPI
Descrizione	Descrizione del proxy API.	Proprietà `description` della specifica OpenAPI

Di seguito è riportato un estratto della specifica OpenAPI che mostra le proprietà utilizzate per precompilare i campi.

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
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

Modifica il campo Descrizione come segue: API proxy for the Apigee mock target service endpoint.
Fai clic su Avanti.
Nella pagina Flussi, assicurati che siano selezionate tutte le operazioni.
Suggerimento: i flussi condizionali vengono generati automaticamente dalle operazioni definite nell'oggetto paths della specifica OpenAPI. I flussi condizionali indicano a Edge: "Quando vedi questo, esegui questa logica". Ad esempio, quando una chiamata API è un GET sulla risorsa /xml (la condizione), trasforma la risposta in JSON (tramite una policy collegata al flusso condizionale). Viene eseguito un solo flusso per transazione: il primo flusso la cui condizione restituisce true.
Fai clic su Avanti.
Nella pagina Sicurezza, seleziona Pass-through (nessuno) come opzione di sicurezza e fai clic su Avanti.
Nella pagina Host virtuali, assicurati che tutti gli host virtuali siano selezionati e fai clic su Avanti.
Nella pagina Crea, assicurati che sia selezionato l'ambiente test e fai clic su Crea ed esegui il deployment.
Nella pagina Riepilogo, viene visualizzata una conferma che il nuovo proxy API è stato creato correttamente e di cui è stato eseguito il deployment nell'ambiente di test.
Fai clic su Mock-Target-API per visualizzare la pagina Panoramica del proxy API proxy.

Complimenti! Hai creato un proxy API da una specifica OpenAPI. Ora lo testerai per vedere come funziona.

Testare il proxy API

Puoi testare l'API Mock-Target-API utilizzando cURL o un browser web.

In una finestra del terminale, esegui il seguente comando cURL. Sostituisci il nome dell'organizzazione in the URL.

curl http://<org_name>-test.apigee.net/mock-target-api

Risposta

Dovresti vedere la seguente risposta:

Hello, Guest!

Complimenti! Hai creato un semplice proxy API da una specifica OpenAPI e l'hai testato it.

Aggiungere una policy da XML a JSON

Ora aggiungerai la policy da XML a JSON al flusso condizionale Visualizza risposta XML generato automaticamente quando hai creato il proxy API dalla specifica OpenAPI. La policy convertirà la risposta XML del target in una risposta JSON response.

Innanzitutto, chiama l'API in modo da poter confrontare i risultati con quelli ricevuti dopo aver aggiunto la policy. In una finestra del terminale, esegui il seguente comando cURL. Stai chiamando la risorsa /xml del servizio target, che restituisce in modo nativo un semplice blocco di XML. Sostituisci il nome dell'organizzazione nell'URL.

curl http://<org_name>-test.apigee.net/mock-target-api/xml

Risposta

Dovresti vedere la seguente risposta:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

Ora facciamo qualcosa che converta la risposta XML in JSON. Aggiungi la policy da XML a JSON al flusso condizionale Visualizza risposta XML nel proxy API.

Fai clic sulla scheda Sviluppa nell'angolo in alto a destra della pagina Panoramica di Mock-Target-API nella UI di Edge.
Nel riquadro di navigazione a sinistra, in Endpoint proxy > default, fai clic sul flusso condizionale Visualizza risposta XML.
Fai clic sul pulsante +Passaggio in basso, corrispondente alla Risposta del flusso.

Viene visualizzata la finestra di dialogo Aggiungi passaggio con un elenco categorizzato di tutte le policy che puoi aggiungere.
Scorri fino alla categoria Mediazione e seleziona XML to JSON.
Mantieni i valori predefiniti per Nome visualizzato e Nome.
Fai clic su Aggiungi. La policy da XML a JSON viene applicata alla risposta.
Fai clic su Salva.

Ora che hai aggiunto la policy, chiama di nuovo l'API utilizzando cURL. Tieni presente che stai ancora chiamando la stessa /xml risorsa. Il servizio target restituisce ancora il blocco di XML, ma ora la policy nel proxy API convertirà la risposta in JSON. Esegui questa chiamata:

curl http://<org_name>-test.apigee.net/mock-target-api/xml

Tieni presente che la risposta XML viene convertita in JSON:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

Complimenti! Hai testato correttamente l'esecuzione di una policy aggiunta a un flusso condizionale.