Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di
Apigee Edge.
Cosa imparerai a fare
In questo tutorial imparerai a:
- Crea un proxy API Apigee da una specifica OpenAPI.
- Chiama il proxy API utilizzando cURL.
- Aggiungi una norma a un flusso condizionale.
- Testa l'invocazione del criterio utilizzando cURL.
Scoprirai come creare un proxy API Apigee da una specifica OpenAPI utilizzando l'interfaccia utente Apigee. Quando chiami il proxy API con un client HTTP, ad esempio cURL, il proxy API invia la richiesta al servizio di destinazione simulato 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 dell'API indipendente dal fornitore basato sulla specifica Swagger." Per ulteriori informazioni sull'iniziativa Open API, consulta la specifica OpenAPI.
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 gli esseri umani. La specifica descrive elementi di un'API come il percorso di base, i percorsi e i verbi, le intestazioni, i parametri di ricerca, le operazioni, i tipi di contenuti, le descrizioni delle risposte e altro ancora. Inoltre, una specifica OpenAPI viene comunemente utilizzata per generare la documentazione API.
Informazioni sul servizio di destinazione simulato di Apigee
Il servizio di destinazione simulato 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. Per provarlo, fai clic su:
Il servizio di destinazione restituisce il saluto Hello, guest!
Per informazioni sull'insieme completo di API supportate dal servizio di destinazione simulato, consulta API di esempio di Apigee.
Che cosa ti serve
- Prima di iniziare, devi completare i passaggi descritti in Panoramica e prerequisiti.
- Una specifica OpenAPI. In questo tutorial utilizzerai la
mocktarget.yaml
specifica OpenAPI che descrive il servizio di destinazione simulato di Apigee,http://mocktarget.apigee.net
. Per saperne di più, vedi apigee/api-platform-samples. - cURL installato sulla tua macchina per effettuare chiamate API dalla riga di comando o un browser web.
Crea il proxy API
Per creare il proxy API da una specifica OpenAPI:
Apigee nella console Cloud
-
Nella console Google Cloud , vai alla pagina Sviluppo proxy > Proxy API.
- Nel riquadro Proxy API, fai clic su + Crea.
- Nel riquadro Crea un proxy, in Modello di proxy > Modello di specifiche OpenAPI, seleziona Proxy inverso (più comune).
- Vai al seguente URL nel browser web:
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
- Fai clic con il tasto destro del mouse sul codice visualizzato e seleziona Salva con nome.
- Fai clic su Salva per salvare il
mocktarget3.0.yaml
nella posizione desiderata. - Nel campo Specifiche OpenAPI, fai clic sul pulsante Sfoglia.
- Vai al file
mocktarget3.0.yaml
e fai clic su Apri. - Fai clic su Avanti.
- Il passaggio Dettagli proxy della procedura guidata Crea proxy compila automaticamente i campi con i valori estratti direttamente dalla specifica OpenAPI.
- Nel passaggio Dettagli proxy, modifica il campo Descrizione come segue:
API proxy for the Apigee mock target service endpoint.
- Fai clic su Avanti.
- Nel passaggio Flussi, assicurati che tutte le operazioni siano selezionate.
- Fai clic su Avanti.
- Nel passaggio Esegui il deployment, seleziona uno o più ambienti e fai clic su Ok.
- Fai clic su Crea.
La seguente tabella descrive i valori predefiniti precompilati utilizzando la specifica OpenAPI:
Campo | Descrizione | Predefinito |
---|---|---|
Nome proxy | Nome del proxy API. Ad esempio: Mock-Target-API . |
Proprietà title della specifica OpenAPI con gli spazi sostituiti
dai trattini |
Base path | Componente del percorso che identifica in modo univoco questo proxy API all'interno dell'organizzazione.
L'URL pubblico di questo proxy API è composto dal tuo nome di dominio esterno o interno e da questo percorso di base. Ad esempio:
http://apitest.acme.com/mock-target-api |
Contenuti del campo Nome convertiti 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 su
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 ...
UI Apigee classica
- Seleziona Sviluppo > Proxy API e nel riquadro Proxy, seleziona l'ambiente per il proxy.
- Fai clic su Proxy API nella finestra principale.
In alternativa, puoi selezionare Sviluppa > Proxy API nella barra di navigazione a sinistra.
Fai clic su Crea nuovo.
-
Nella procedura guidata Crea proxy, fai clic su Utilizza specifica OpenAPI per il modello Proxy inverso (il più comune).
- Fai clic su 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
- Fai clic su Seleziona.
Viene visualizzata la pagina Dettagli proxy nella 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 precompilati utilizzando la specifica OpenAPI:
Campo Descrizione Predefinito Nome Nome del proxy API. Ad esempio: Mock-Target-API
.Proprietà title
della specifica OpenAPI con gli spazi sostituiti dai trattiniBase path Componente del percorso che identifica in modo univoco questo proxy API all'interno dell'organizzazione. L'URL pubblico di questo proxy API è composto dal tuo nome di dominio esterno o interno e da questo percorso di base. Ad esempio: http://apitest.acme.com/mock-target-api
Contenuti del campo Nome convertiti in minuscolo Descrizione Descrizione del proxy API. Proprietà description
della specifica OpenAPITarget (API esistente) URL di destinazione richiamato per conto di questo proxy API. È possibile utilizzare qualsiasi URL accessibile su internet aperto. Ad esempio: http://mocktarget.apigee.net
Proprietà servers
della specifica OpenAPIDi 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 ...
- Nella pagina Dettagli proxy, modifica il campo Descrizione nel seguente modo:
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 tutte le operazioni siano selezionate.
- Fai clic su Avanti.
- Nella pagina Riepilogo, assicurati che sia selezionato un ambiente in Deployment facoltativo e fai clic su Crea ed esegui il deployment:
Apigee crea il nuovo proxy API e lo esegue il deployment nell'ambiente:
- Fai clic su Modifica proxy per visualizzare la pagina Panoramica del proxy API.
Testa il proxy API
Puoi testare l'API Mock-Target-API
utilizzando cURL o un browser web.
curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy
dove YOUR_ENV_GROUP_HOSTNAME
è il nome host del gruppo di ambienti. Vedi
Trovare il nome host del gruppo di ambienti.
Ad esempio:
curl -v -k https://apitest.acme.com/myproxy
Risposta
Dovresti vedere la seguente risposta:
Hello, Guest!
Aggiungere una norma XML to JSON
Successivamente, aggiungerai il criterio XML to JSON al flusso condizionale Visualizza risposta XML generato automaticamente quando hai creato il proxy API dalla specifica OpenAPI. Il criterio convertirà la risposta XML della destinazione in una risposta JSON.
Innanzitutto, chiama l'API in modo da poter confrontare i risultati con quelli ricevuti dopo aver aggiunto
le norme. In una finestra del terminale, esegui il seguente comando cURL. Stai chiamando la risorsa /xml
del servizio di destinazione, che restituisce in modo nativo un semplice blocco di XML.
curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml
dove YOUR ENV_GROUP_HOSTNAME
è il nome host del gruppo di ambienti. Consulta
Trovare il nome host del gruppo di ambienti.
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 XML to JSON al flusso condizionale Visualizza risposta XML nel proxy API.
Apigee nella console Cloud
Fai clic sulla scheda Sviluppa nella pagina Panoramica dell'API di destinazione simulata nell'interfaccia utente Apigee.
- Nel riquadro a sinistra, in Endpoint proxy > default, fai clic sul flusso condizionale Visualizza risposta XML.
- Nel riquadro a sinistra, fai clic sul pulsante + nella riga Criteri.
Nella finestra di dialogo Crea criterio, fai clic sul campo Seleziona tipo di criterio, scorri verso il basso fino a Mediazione e seleziona XMLToJSON. Mantieni i valori predefiniti per Nome visualizzato e Nome.
- Fai clic su Crea per creare la policy.
Fai clic sul pulsante + accanto al flusso Visualizza risposta XML in Risposta.
- Nella finestra di dialogo Aggiungi passaggio norma, fai clic nel campo Seleziona norma esistente e seleziona XML to JSON-1.
Fai clic su Aggiungi. Il criterio XML to JSON viene applicato alla risposta.
Per visualizzare il codice del flusso condizionale Visualizza risposta XML, fai clic su Passa all'editor di codice.
- Fai clic su Salva.
UI Apigee classica
Fai clic sulla scheda Sviluppa nella pagina Panoramica dell'API di destinazione simulata nell'interfaccia utente Apigee.
Nel riquadro di navigazione a sinistra, in Proxy Endpoints > default, fai clic sul flusso condizionale View XML Response.
Fai clic sul pulsante +Passaggio in basso, corrispondente alla Risposta del flusso.
Si apre la finestra di dialogo Aggiungi passaggio, che mostra un elenco classificato di tutte le norme 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. Il criterio XML to JSON viene applicato alla risposta.
- Fai clic su Salva.
Ora che hai aggiunto il criterio, chiama di nuovo l'API utilizzando cURL. Tieni presente che stai ancora
chiamando la stessa risorsa /xml
. Il servizio di destinazione restituisce ancora il blocco di
XML, ma ora il criterio nel proxy API convertirà la risposta in JSON. Effettua questa
chiamata:
curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml
dove YOUR ENV_GROUP_HOSTNAME
è il nome host del gruppo di ambienti. Consulta
Trovare il nome host del gruppo di ambienti.
Tieni presente che la risposta XML viene convertita in JSON:
{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}