Crea un proxy API da una specifica OpenAPI | Apigee Edge

In questo tutorial imparerai a creare un proxy API Edge da una soluzione OpenAPI Specifica mediante l'interfaccia utente di gestione Apigee Edge. Quando chiami il proxy API con un Client HTTP, come cURL, il proxy API invia la richiesta al target fittizio di Apigee completamente gestito di Google Cloud.

Informazioni sull'iniziativa Open API

"L'iniziativa Open API Initiative (OAI) si concentra su Creare, sviluppare e promuovere un formato di descrizione dell'API indipendente dal fornitore basato sul modello Swagger specifica." Per ulteriori informazioni sull'iniziativa OpenAPI, 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 dalle macchine, ma anche per gli esseri umani. La specifica descrive tali elementi API come percorso di base, percorsi e verbi, intestazioni, parametri di ricerca, operazioni, 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 di destinazione simulato Apigee

Il servizio di destinazione fittizio di Apigee utilizzato in questo tutorial è ospitato su Apigee e restituisce semplici dati. Non richiede chiavi API o token di accesso. Infatti, puoi accedervi da un sito web del browser. Provalo facendo clic di seguito:

http://mocktarget.apigee.net

Il servizio di destinazione restituisce il saluto Hello, guest!

Per informazioni sul set completo di API supportate dal servizio di destinazione fittizio, fai clic sull'icona seguenti:

http://mocktarget.apigee.net/help

Che cosa ti serve

Un account Apigee Edge. Se non disponi di un account, puoi registrarti seguendo le istruzioni in Creazione di un modello Apigee Edge Google Cloud.
Una specifica OpenAPI. In questo tutorial, utilizzerai mocktarget.yaml Specifica OpenAPI che descrive il target fittizio di Apigee servizio http://mocktarget.apigee.net. Per ulteriori informazioni, vedi 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.

Crea il proxy API

Edge

Per creare il proxy API da una specifica OpenAPI utilizzando l'interfaccia utente Edge:

Accedi a https://apigee.com/edge.
Fai clic su Proxy API nella finestra principale.
In alternativa, puoi selezionare Sviluppo > Proxy API nella barra di navigazione a sinistra.
Fai clic su + Proxy.
Nella procedura guidata di creazione del proxy, fai clic su Utilizza specifiche OpenAPI per il modello Inverti proxy (più comune).
Fai clic su Importa da URL e inserisci le informazioni seguenti:
- URL specifica OpenAPI: percorso dei contenuti non elaborati 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 Destinazione fittizia.
  Questo nome viene utilizzato per archiviare la specifica OpenAPI nell'archivio specifiche. Consulta la sezione Gestire le specifiche.

Fai clic su Importa.

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

La tabella seguente descrive i valori predefiniti precompilati utilizzando nella specifica OpenAPI. Un estratto della specifica OpenAPI che illustra le proprietà utilizzate è riportata di seguito.

Campo	Descrizione	Predefinito
Nome	Nome del proxy API. Ad esempio: `Mock-Target-API`.	Proprietà `title` della specifica OpenAPI con spazi sostituiti per trattini
Percorso 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 della tua organizzazione, da un dell'ambiente in cui viene eseguito il deployment del proxy API e del percorso di base. Per esempio: `http://myorg-test.apigee.net/mock-target-api`	Contenuti del campo Nome convertiti in lettere minuscole
Descrizione	Descrizione del proxy API.	`description` della specifica OpenAPI
Target (API esistente)	URL di destinazione richiamato per conto di questo proxy API. Qualsiasi URL accessibile tramite è possibile usare internet. Ad esempio: `http://mocktarget.apigee.net`	`servers` della specifica OpenAPI

Di seguito viene fornito un estratto della specifica OpenAPI che mostra 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 Criteri comuni, in Sicurezza: autorizzazione assicurati che sia selezionata l'opzione Pass through (nessun autorizzazione) e fai clic su Avanti:
Nella pagina Flussi, assicurati che tutte le operazioni siano selezionate.
Suggerimento: i flussi condizionali vengono generati automaticamente le operazioni definite all'interno dell'oggetto paths nell'API OpenAPI Specifiche. I flussi condizionali indicano a Edge: "Quando lo vedi, esegui questa logica". Ad esempio, quando una chiamata API è un GET sulla risorsa /xml (la condizione), trasformare la risposta in JSON (tramite un criterio collegato al flusso condizionale). Solo viene eseguito un flusso per transazione: il primo flusso la cui condizione valuta vero.
Fai clic su Avanti.
Nella pagina Host virtuali, seleziona predefinita e protetto e fai clic su Avanti.
Nella pagina Riepilogo, assicurati che l'ambiente Test sia in Deployment facoltativo e fai clic su Crea e deploy:

Apigee crea il tuo nuovo proxy API e ne esegue il deployment nel tuo ambiente di test:
Fai clic su Modifica proxy per visualizzare la pagina Panoramica dell'API. proxy.

Perimetrale classico (Private Cloud)

Per creare il proxy API da una specifica OpenAPI utilizzando l'interfaccia utente Edge Classic:

Accedi a https://apigee.com/edge.
Fai clic su Proxy API nella finestra principale.
In alternativa, puoi selezionare Sviluppo > Proxy API nella barra di navigazione a sinistra.
Fai clic su + Proxy.
Nella procedura guidata di creazione del proxy, seleziona Inverti proxy (più comune) e fai clic su Use 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 OpenAPI. Specifica 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 Dettagli della procedura guidata Crea proxy. I campi sono precompilati utilizzando i valori definiti nella specifica OpenAPI, come mostrato di seguito figura stilizzata.

La tabella seguente descrive i valori predefiniti precompilati utilizzando nella specifica OpenAPI. Un estratto della specifica OpenAPI che illustra le proprietà utilizzate è riportata di seguito.

Campo	Descrizione	Predefinito
Nome proxy	Nome del proxy API. Ad esempio: `Mock-Target-API`.	Proprietà `title` della specifica OpenAPI con spazi sostituiti per trattini
Percorso di base del proxy	Componente del percorso che identifica in modo univoco questo proxy API all'interno dell'organizzazione. L'URL visibile al pubblico di questo proxy API è composto dal nome della tua organizzazione, da un dell'ambiente in cui viene eseguito il deployment del proxy API e del percorso di base. Per esempio: `http://myorg-test.apigee.net/mock-target-api`	Contenuti del campo Nome convertiti in lettere minuscole
API esistente	URL di destinazione richiamato per conto di questo proxy API. Qualsiasi URL accessibile tramite è possibile usare internet. Ad esempio: `http://mocktarget.apigee.net`	`servers` della specifica OpenAPI
Descrizione	Descrizione del proxy API.	`description` della specifica OpenAPI

Di seguito viene fornito un estratto della specifica OpenAPI che mostra 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 tutte le operazioni siano selezionate.
Suggerimento: i flussi condizionali vengono generati automaticamente le operazioni definite all'interno dell'oggetto paths nell'API OpenAPI Specifiche. I flussi condizionali indicano a Edge: "Quando lo vedi, esegui questa logica". Ad esempio, quando una chiamata API è un GET sulla risorsa /xml (la condizione), trasformare la risposta in JSON (tramite un criterio collegato al flusso condizionale). Solo viene eseguito un flusso per transazione: il primo flusso la cui condizione valuta vero.
Fai clic su Avanti.
Nella pagina Sicurezza, seleziona Passthrough (nessuno) come sicurezza e fai clic su Avanti.
Nella pagina Host virtuali, assicurati che siano selezionati tutti gli host virtuali e fai clic su Avanti.
Nella pagina Build (Crea), assicurati che sia selezionato l'ambiente test e fai clic su Crea ed esegui il deployment.
Nella pagina Riepilogo viene visualizzata una conferma di creazione del nuovo proxy API. correttamente e il deployment nel tuo ambiente di test.
Fai clic su Mock-Target-API per visualizzare la pagina Panoramica dell'API. proxy.

Complimenti Hai creato un proxy API da una specifica OpenAPI. Successivamente, testalo per vedere come funziona.

Testa il proxy API

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

In una finestra del terminale, esegui questo comando cURL. Sostituisci il nome della tua organizzazione in l'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 partendo da una specifica OpenAPI e testato li annotino.

Aggiungi un criterio da XML a JSON

In seguito, aggiungerai il criterio da XML a JSON alla sezione Visualizza risposta XML. condizionale generato automaticamente al momento della creazione del proxy API dal specifica OpenAPI. Il criterio convertirà la risposta XML della destinazione in un file JSON la risposta corretta.

Innanzitutto, chiama l'API in modo da poter confrontare i risultati con quelli ricevuti dopo aver aggiunto il criterio. In una finestra del terminale, esegui il seguente comando cURL. Stai chiamando il risorsa /xml del servizio di destinazione, che restituisce in modo nativo un semplice blocco di XML. Sostituisci il nome della tua 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 il criterio da XML a JSON al flusso condizionale Visualizza risposta XML nel proxy API.

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

La finestra di dialogo Aggiungi passaggio mostra un elenco categorizzato di tutti i criteri che puoi aggiungere.
Scorri fino alla categoria Mediazione e seleziona Da XML a JSON.
Mantieni i valori predefiniti per Nome visualizzato e Nome.
Fai clic su Aggiungi. Il criterio da XML a JSON viene applicato alla risposta.
Fai clic su Salva.

Ora che hai aggiunto il criterio, richiama di nuovo l'API utilizzando cURL. Nota che stai ancora chiamando la stessa risorsa /xml. Il servizio di destinazione restituisce comunque il proprio blocco XML, ma ora il criterio nel proxy API convertirà la risposta in JSON. Crea chiama:

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 l'esecuzione di una norma aggiunta a un condizionale.