Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Cosa imparerai a fare
Con questo tutorial imparerai a:
- Crea un proxy API che richiede una chiave API.
- Aggiungi un prodotto API.
- Aggiungi uno sviluppatore e registra un'app.
- Chiamare l'API con una chiave API.
È importante proteggere l'API da accessi non autorizzati. Un modo per farlo è utilizzare le chiavi API (dette anche chiavi pubbliche, chiavi consumer o chiavi app).
Quando un'app invia una richiesta all'API, deve fornire una chiave valida. In fase di runtime, il criterio di verifica della chiave API verifica che la chiave API fornita:
- È valido
- Non sono stati revocati.
- Corrisponde alla chiave API per il prodotto API che espone le risorse richieste
Se la chiave è valida, la richiesta è consentita. Se la chiave non è valida, la richiesta restituisce un errore di autorizzazione.
In questo tutorial, creerai un proxy API che richiede una chiave API valida per accedervi.
Che cosa ti serve
- Un account Apigee Edge. Se non ne hai ancora uno, puoi registrarti seguendo le indicazioni nella pagina Creare un account Apigee Edge.
- Un browser web per effettuare una chiamata API.
- (Per la sezione del credito aggiuntivo, non obbligatoria) cURL installato sulla tua macchina per effettuare chiamate API dalla riga di comando.
Crea il proxy API
- Vai ad https://apigee.com/edge e accedi.
Passa all'organizzazione che ti interessa facendo clic sul tuo nome utente nella parte superiore della barra di navigazione laterale per visualizzare il menu del profilo utente, quindi seleziona l'organizzazione dall'elenco.
-
Fai clic su proxy API nella pagina di destinazione per visualizzare l'elenco dei proxy API.
- Fai clic su + Proxy.
- Nella pagina Crea proxy, seleziona Inverti proxy (più comune).
- Nella pagina Dettagli proxy, configura il proxy come segue:
In questo campo fai questo Nome proxy Inserisci: helloworld_apikey
Percorso di base del progetto Cambia in:
/helloapikey
Il percorso di base del progetto fa parte dell'URL utilizzato per effettuare richieste al proxy API.
Nota: per i suggerimenti di Apigee sul controllo delle versioni delle API, vedi Controllo delle versioni nell'ebook Web API Design: The Missing Link.
API esistente Inserisci:
http://mocktarget.apigee.net
Questo definisce l'URL di destinazione che Apigee Edge richiama su una richiesta al proxy API.
Descrizione Inserisci: hello world protected by API key
- Fai clic su Avanti.
- Nella pagina Criteri comuni, in Sicurezza: autorizzazione, seleziona Chiave API, quindi fai clic su Avanti. Verranno aggiunti due criteri al tuo proxy API.
- Nella pagina Host virtuali, seleziona predefinito e protetto, quindi fai clic su Avanti. Se selezioni default, puoi chiamare la tua API con
http://
. Se selezioni Secure, puoi chiamare la tua API conhttps://
. - Nella pagina Riepilogo, assicurati che sia selezionato l'ambiente di deployment test, quindi fai clic su Crea ed esegui il deployment.
- Verrà visualizzata una conferma che il nuovo proxy API e un prodotto API sono stati creati correttamente e che è stato eseguito il deployment del proxy API nell'ambiente di test.
- Fai clic su Modifica proxy per visualizzare la pagina Panoramica relativa al proxy API.
Visualizza le norme
- Nell'editor proxy API, fai clic sulla scheda Sviluppo. Vedrai che sono stati aggiunti due criteri al flusso di richieste del proxy API:
- Verifica chiave API: controlla la chiamata API per verificare che sia presente una chiave API valida (inviata come parametro di ricerca).
- Rimuovi apikey del parametro di query: un criterio di AssegnaMessage che rimuove la chiave API dopo che è stata selezionata, in modo che non venga trasmessa ed esposta inutilmente.
-
Fai clic sull'icona di verifica del criterio della chiave API nella visualizzazione del flusso e osserva la configurazione XML del criterio nella visualizzazione del codice in basso. L'elemento
<APIKey>
indica al criterio dove deve cercare la chiave API quando viene effettuata la chiamata. Per impostazione predefinita, cerca la chiave come parametro di ricerca denominatoapikey
nella richiesta HTTP:<APIKey ref="request.queryparam.apikey" />
Il nome
apikey
è arbitrario e può essere qualsiasi proprietà contenente la chiave API.
Prova a chiamare l'API
In questo passaggio, potrai effettuare una chiamata API riuscita direttamente al servizio di destinazione, quindi effettuerai una chiamata non riuscita al proxy API per verificare come è protetto dai criteri.
-
Operazione riuscita
Da un browser web, vai al seguente indirizzo. Questo è il servizio di destinazione a cui è configurato il proxy API per inoltrare la richiesta, ma per ora lo utilizzerai direttamente:
http://mocktarget.apigee.net
Dovresti ottenere questa risposta corretta:
Hello, Guest!
-
Errore
Ora prova a chiamare il tuo proxy API:
http://ORG_NAME-test.apigee.net/helloapikey
sostituendo
ORG_NAME
con il nome della tua organizzazione Edge.Senza il criterio di verifica della chiave API, questa chiamata restituirà la stessa risposta della chiamata precedente. In questo caso, però, dovresti ricevere la seguente risposta di errore:
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
il che significa, correttamente, che non hai trasmesso una chiave API valida (come parametro di ricerca).
Nei passaggi successivi, aggiungerai un prodotto API.
Aggiungi un prodotto API
Per aggiungere un prodotto API utilizzando l'interfaccia utente di Apigee:
- Seleziona Pubblica > Prodotti API.
- Fai clic su +Prodotto API.
Inserisci i dettagli del prodotto per il prodotto API.
Campo Descrizione Nome Nome interno del prodotto API. Non specificare caratteri speciali nel nome.
Nota: non puoi modificare il nome dopo aver creato il prodotto API. Ad esempio,helloworld_apikey-Product
.Nome visualizzato Nome visualizzato del prodotto API. Il nome visualizzato viene utilizzato nell'interfaccia utente e puoi modificarlo in qualsiasi momento. Se non specificato, verrà utilizzato il valore Name. Questo campo viene compilato automaticamente utilizzando il valore del campo Nome; puoi modificarne o eliminarne i contenuti. Il nome visualizzato può includere caratteri speciali. Ad esempio, helloworld_apikey-Product
.Descrizione Descrizione del prodotto API. Ad esempio, Test product for tutorial
.Ambiente Ambienti a cui il prodotto API consentirà l'accesso. Ad esempio, test
oprod
.Accesso Seleziona Pubblico. Approva automaticamente le richieste di accesso Abilita l'approvazione automatica delle richieste di chiavi per questo prodotto API da qualsiasi app. Quota Ignora per questo tutorial. Ambiti OAuth consentiti Ignora per questo tutorial. - Nella sezione Risorse API, seleziona il proxy API appena creato. Ad esempio,
helloworld_apikey
. - Fai clic su Aggiungi.
- Nella sezione Percorsi, aggiungi il percorso "/".
- Fai clic su Aggiungi.
- Fai clic su Salva.
Nei passaggi successivi, riceverai la chiave API richiesta.
Aggiungi uno sviluppatore e un'app alla tua organizzazione
Ora simuleremo il flusso di lavoro di uno sviluppatore che si registra per utilizzare le tue API. Uno sviluppatore avrà una o più app che chiamano le tue API e ogni app riceve una chiave API univoca. In questo modo, in qualità di provider delle API, avrai un controllo più granulare sull'accesso alle tue API e report più granulari sul traffico delle API per app.
Crea uno sviluppatore
Per creare uno sviluppatore:
- Seleziona Pubblica > Sviluppatori nel menu.
- Fai clic su + Sviluppatore.
Inserisci quanto segue nella finestra Nuovo sviluppatore:
In questo campo invio Nome Keyser
Cognome Soze
Nome utente keyser
Email keyser@example.com
- Fai clic su Crea.
Registra un'app
Per registrare un'app sviluppatore:
- Seleziona Pubblica > App.
- Fai clic su + App.
Inserisci quanto segue nella finestra Nuova app:
pIn questo campo fai questo Nome e Nome visualizzato Inserisci: keyser_app
Società / sviluppatore Seleziona: Developer
Developer Seleziona: Keyser Soze (keyser@example.com)
URL di callback e Note Lascia vuoto - Nella sezione Credenziali, seleziona Mai dal menu Scadenza. Le credenziali per questa app non scadranno mai.
- In Prodotti, fai clic su Aggiungi prodotto.
- Seleziona helloworld_apikey-Product.
- Fai clic su Aggiungi.
- Fai clic su Crea in alto a destra della sezione Dettagli app per salvare il tuo lavoro.
Recupero della chiave API
Per ottenere la chiave API:
- Nella pagina App (Pubblica > App), fai clic su keyser_app.
Nella pagina keyser_app, fai clic su Mostra accanto a Chiave nella sezione Credenziali. Nella sezione Product, noterai che la chiave è associata a helloworld_apikey
.- Seleziona e copia la Chiave. Lo utilizzerai nel passaggio successivo.
Chiama l'API con una chiave
Ora che disponi di una chiave API, puoi utilizzarla per chiamare il proxy API. Inserisci quanto segue nel browser web. Sostituisci il nome dell'organizzazione Edge con ORG_NAME e la chiave API con API_KEY di seguito. Assicurati che non siano presenti spazi aggiuntivi nel parametro di query.
http://ORG_NAME-test.apigee.net/helloapikey?apikey=API_KEY
Ora, quando chiami il proxy API, dovresti ricevere questa risposta:
Hello, Guest!
Complimenti! Hai creato un proxy API e lo hai protetto richiedendo l'inclusione di una chiave API valida nella chiamata.
Tieni presente che, in generale, non è consigliabile passare una chiave API come parametro di query. Considera invece di passarlo nell'intestazione HTTP.
Best practice: passaggio della chiave nell'intestazione HTTP
In questo passaggio, modificherai il proxy per cercare la chiave API in
un'intestazione denominata x-apikey
.
- Modifica il proxy API. Seleziona Sviluppo > Proxy API > helloworld_apikey e vai alla vista Sviluppo.
-
Seleziona il criterio Verifica chiave API e modifica il codice XML del criterio per indicare al criterio di cercare nel
header
anziché inqueryparam
:<APIKey ref="request.header.x-apikey"/>
- Salva il proxy API per eseguire il deployment della modifica.
-
Effettua la seguente chiamata API utilizzando cURL per passare la chiave API sotto forma di intestazione denominata
x-apikey
. Non dimenticare di sostituire il nome della tua organizzazione.curl -v -H "x-apikey: API_KEY" http://ORG_NAME-test.apigee.net/helloapikey
Tieni presente che, per completare la modifica, devi anche configurare il criterio AssegnaMessage per rimuovere l'intestazione anziché il parametro di query. Ad esempio:
<Remove> <Headers> <Header name="x-apikey"/> </Headers> </Remove>
Argomenti correlati
Ecco alcuni argomenti direttamente correlati a questo tutorial:
- Gestisci i prodotti basati su API
- Chiavi API
- Registra gli sviluppatori di app
- Registra le app e gestisci le chiavi API
- Criterio di VerificationAPIKey
- Criterio AssegnaMessage
Andando più a fondo, la protezione delle API con le chiavi API è solo una parte. Spesso, la protezione delle API richiede ulteriori misure di sicurezza, ad esempio OAuth.
OAuth è un protocollo aperto che, in poche parole, scambia credenziali (come nome utente e password) per token di accesso. I token di accesso sono stringhe lunghe e casuali che possono essere trasmesse in una pipeline di messaggi, anche da un'app all'altra, senza compromettere le credenziali originali. I token di accesso spesso hanno vite brevi, per cui ne vengono sempre generati di nuovi.