Stai visualizzando la documentazione di Apigee Edge.
Consulta la
documentazione di Apigee X. info

Cosa
Il criterio Verifica chiave API consente di applicare la verifica delle chiavi API in fase di runtime, consentendo solo alle app con chiavi API approvate di accedere alle tue API. Queste norme garantiscono che le chiavi API siano valide, non siano state revocate e siano approvate per l'utilizzo delle risorse specifiche associate ai tuoi prodotti API.
Esempi
Chiave nel parametro di query
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.apikey" /> </VerifyAPIKey>
In questo esempio, il criterio prevede di trovare la chiave API in una variabile di flusso chiamata
request.queryparam.apikey
. La variabile request.queryparam.{name}
è una variabile di flusso Edge standard che viene compilata con il valore di un parametro di query passato
nella richiesta client.
Il seguente comando curl
passa la chiave API in un parametro di query:
curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls
Chiave nell'intestazione
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey" /> </VerifyAPIKey>
In questo esempio, il criterio prevede di trovare la chiave API in una variabile di flusso chiamata
request.header.x-apikey
. La variabile request.header.{name}
è una variabile di flusso Edge standard che viene compilata con il valore di un'intestazione passata
nella richiesta del client.
Il seguente cURL mostra come passare la chiave API in un'intestazione:
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
Chiave nella variabile
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="requestAPIKey.key"/> </VerifyAPIKey>
Il criterio può fare riferimento a qualsiasi variabile che contenga la chiave. Le norme in questo esempio estraggono la chiave API da una variabile denominata requestAPIKey.key.
Spetta a te decidere come viene compilata la variabile. Ad esempio, puoi utilizzare la norma Estrai variabili per compilare requestAPIKey.key da un parametro di ricerca denominato myKey, come mostrato di seguito:
<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar"> <Source>request</Source> <QueryParam name="myKey"> <Pattern ignoreCase="true">{key}</Pattern> </QueryParam> <VariablePrefix>requestAPIKey</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Variabili di flusso delle policy di accesso
<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars"> <AssignVariable> <Name>devFirstName</Name> <Ref>verifyapikey.verify-api-key.developer.firstName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devLastName</Name> <Ref>verifyapikey.verify-api-key.developer.lastName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devEmail</Name> <Ref>verifyapikey.verify-api-key.developer.email</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
Edge compila automaticamente un insieme di variabili di flusso quando esegue il criterio Verifica chiave API per una chiave API valida. Puoi utilizzare queste variabili per accedere a informazioni quali il nome dell'app, l'ID app e informazioni sullo sviluppatore o sull'azienda che ha registrato l'app. Nell'esempio precedente, utilizzi il criterio Assegna messaggio per accedere al nome, al cognome e all'indirizzo email dello sviluppatore dopo l'esecuzione di Verifica chiave API.
Tutte queste variabili sono precedute da:
verifyapikey.{policy_name}
In questo esempio, il nome del criterio Verifica chiave API è "verify-api-key". Pertanto, fai riferimento
al nome dello sviluppatore che effettua la richiesta accedendo alla
variabile verifyapikey.verify-api-key.developer.firstName.
Learn Edge
Informazioni sul criterio Verifica chiave API
Quando uno sviluppatore registra un'app su Edge, Edge genera automaticamente una coppia di chiave e secret del consumatore. Puoi visualizzare la coppia di chiave e secret del consumatore dell'app nell'interfaccia utente di Edge o accedervi dall'API Edge.
Al momento della registrazione dell'app, lo sviluppatore seleziona uno o più prodotti API da associare all'app, dove un prodotto API è una raccolta di risorse accessibili tramite proxy API. Lo sviluppatore passa quindi la chiave API (chiave consumer) come parte di ogni richiesta a un'API in un prodotto API associato all'app. Per saperne di più, consulta la Panoramica della pubblicazione.
Le chiavi API possono essere utilizzate come token di autenticazione oppure per ottenere token di accesso OAuth. In OAuth, le chiavi API sono chiamate "ID client". I nomi possono essere utilizzati in modo intercambiabile. Per saperne di più, consulta la home page di OAuth.
Edge compila automaticamente un insieme di variabili di flusso durante l'esecuzione del criterio Verifica chiave API. Per saperne di più, consulta la sezione Variabili del flusso di seguito.
Riferimento elemento
Di seguito sono riportati gli elementi e gli attributi che puoi configurare in queste norme:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1"> <DisplayName>Custom label used in UI</DisplayName> <APIKey ref="variable_containing_api_key"/> </VerifyAPIKey>
Attributi <VerifyAPIKey>
L'esempio seguente mostra gli attributi del tag <VerifyAPIKey>
:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
La tabella seguente descrive gli attributi comuni a tutti gli elementi principali del criterio:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
name |
Il nome interno del criterio. Il valore dell'attributo Se vuoi, puoi utilizzare l'elemento |
N/D | Obbligatorio |
continueOnError |
Imposta il valore su Imposta su |
falso | Facoltativo |
enabled |
Imposta il valore su Imposta |
true | Facoltativo |
async |
Questo attributo è obsoleto. |
falso | Deprecato |
<DisplayName> elemento
Da utilizzare in aggiunta all'attributo name
per etichettare il criterio in
editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.
<DisplayName>Policy Display Name</DisplayName>
Predefinito |
N/D Se ometti questo elemento, il valore dell'attributo |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
Elemento <APIKey>
Questo elemento specifica la variabile di flusso che contiene la chiave API. In genere, il client invia la chiave API
in un parametro di query, un'intestazione HTTP o un parametro del modulo. Ad esempio, se la chiave viene inviata in un'intestazione
denominata x-apikey
, la chiave verrà trovata nella variabile: request.header.x-apikey
Predefinito | ND |
---|---|
Presenza | Obbligatorio |
Tipo | Stringa |
Attributi
La tabella seguente descrive gli attributi dell'elemento <APIKey>
.
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
ref |
Un riferimento alla variabile che contiene la chiave API. È consentita una sola posizione per criterio. |
N/D | Obbligatorio |
Esempi
In questi esempi, la chiave viene passata nei parametri e in un'intestazione chiamata x-apikey
.
Come parametro di ricerca:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.x-apikey"/> </VerifyAPIKey>
Come intestazione HTTP:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey"/> </VerifyAPIKey>
Come parametro del modulo HTTP:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.formparam.x-apikey"/> </VerifyAPIKey>
Schemi
Variabili di flusso
Quando un criterio Verifica chiave API viene applicato a una chiave API valida, Edge compila un insieme di variabili di flusso. Queste variabili sono disponibili per le norme o il codice eseguiti in un secondo momento nel flusso e vengono spesso utilizzate per eseguire l'elaborazione personalizzata in base agli attributi della chiave API, come il nome dell'app, il prodotto API utilizzato per autorizzare la chiave o gli attributi personalizzati della chiave API.
I criteri compilano diversi tipi di variabili di flusso, tra cui:
- Generale
- App
- Sviluppatore
- Società
- Analytics
Ogni tipo di variabile di flusso ha un prefisso diverso. Tutte le variabili sono scalari, tranne quelle specificamente indicate come array.
Variabili di flusso generali
La tabella seguente elenca le variabili di flusso generali compilate dal criterio Verifica chiave API. Tutte queste variabili sono precedute da:
verifyapikey.{policy_name}
Ad esempio: verifyapikey.{policy_name}.client_id
Le variabili disponibili includono:
Variabile | Descrizione |
---|---|
client_id |
La chiave utente (nota anche come chiave API o chiave app) fornita dall'app richiedente. |
client_secret |
Il secret consumer associato alla chiave consumer. |
redirection_uris |
Eventuali URI di reindirizzamento nella richiesta. |
developer.app.id |
L'ID dell'app sviluppatore che effettua la richiesta. |
developer.app.name |
Il nome dell'app dello sviluppatore che effettua la richiesta. |
developer.id |
L'ID dello sviluppatore registrato come proprietario dell'app richiedente. |
developer.{custom_attrib_name} |
Qualsiasi attributo personalizzato derivato dal profilo della chiave dell'app |
DisplayName |
Il valore dell'attributo <DisplayName> del criterio. |
failed |
Impostato su "true" quando la convalida della chiave API non va a buon fine. |
{custom_app_attrib} |
Qualsiasi attributo personalizzato derivato dal profilo dell'app. Specifica il nome dell'attributo personalizzato. |
apiproduct.name* |
Il nome del prodotto API utilizzato per convalidare la richiesta. |
apiproduct.{custom_attrib_name}* |
Qualsiasi attributo personalizzato derivato dal profilo del prodotto API. |
apiproduct.developer.quota.limit* |
Il limite di quota impostato sul prodotto API, se presente. |
apiproduct.developer.quota.interval* |
L'intervallo di quota impostato sul prodotto API, se presente. |
apiproduct.developer.quota.timeunit* |
L'unità di tempo della quota impostata sul prodotto API, se presente. |
* Le variabili del prodotto API vengono compilate automaticamente se i prodotti API sono
configurati con ambiente, proxy e risorse validi (derivati da
proxy.pathsuffix ). Per istruzioni sulla configurazione dei prodotti API, consulta
Utilizzo dell'API
di gestione Edge per pubblicare le API. |
Variabili di flusso dell'app
Le seguenti variabili di flusso contenenti informazioni sull'app vengono compilate dalle norme. Tutte queste variabili sono precedute da:
verifyapikey.{policy_name}.app
.
Ad esempio:
verifyapikey.{policy_name}.app.name
Le variabili disponibili includono:
Variabile | Descrizione |
---|---|
name |
Il nome dell'app. |
id |
L'ID dell'app. |
accessType |
Non utilizzato da Apigee. |
callbackUrl |
L'URL di callback dell'app. In genere viene utilizzato solo per OAuth. |
DisplayName |
Il nome visualizzato dell'app. |
status |
Lo stato dell'app, ad esempio "approvata" o "revocata". |
apiproducts |
Un array contenente l'elenco dei prodotti API associati all'app. |
appFamily |
Qualsiasi famiglia di app contenente l'app o "predefinita". |
appParentStatus |
Lo stato del genitore dell'app, ad esempio "attivo" o "non attivo". |
appType |
Il tipo di app, "Azienda" o "Sviluppatore". |
appParentId |
L'ID dell'app principale. |
created_at |
Il timestamp di data/ora di creazione dell'app. |
created_by |
L'indirizzo email dello sviluppatore che ha creato l'app. |
last_modified_at |
Il timestamp di data/ora dell'ultimo aggiornamento dell'app. |
last_modified_by |
L'indirizzo email dello sviluppatore che ha aggiornato per ultimo l'app. |
{app_custom_attributes} |
Qualsiasi attributo personalizzato dell'app. Specifica il nome dell'attributo personalizzato. |
Variabili del flusso per sviluppatori
Le seguenti variabili di flusso contenenti informazioni sullo sviluppatore vengono compilate dalle norme. Tutte queste variabili sono precedute da:
verifyapikey.{policy_name}.developer
Ad esempio:
verifyapikey.{policy_name}.developer.id
Le variabili disponibili includono:
Variabile | Descrizione |
---|---|
id |
Restituisce {org_name}@@@{developer_id} |
userName |
Il nome utente dello sviluppatore. |
firstName |
Il nome dello sviluppatore. |
lastName |
Il cognome dello sviluppatore. |
email |
L'indirizzo email dello sviluppatore. |
status |
Lo stato dello sviluppatore, ovvero attivo, non attivo o login_lock. |
apps |
Un array di app associate allo sviluppatore. |
created_at |
Il timestamp di data/ora di creazione dello sviluppatore. |
created_by |
L'indirizzo email dell'utente che ha creato lo sviluppatore. |
last_modified_at |
Il timestamp di data/ora dell'ultima modifica dello sviluppatore. |
last_modified_by |
L'indirizzo email dell'utente che ha modificato lo sviluppatore. |
{developer_custom_attributes} |
Qualsiasi attributo sviluppatore personalizzato. Specifica il nome dell'attributo personalizzato. |
Company |
Il nome dell'azienda, se presente, associata allo sviluppatore. |
Variabili di flusso aziendali
Le seguenti variabili di flusso contenenti informazioni sull'azienda vengono compilate dalle norme. Tutte queste variabili sono precedute da:
verifyapikey.{policy_name}.company
Ad esempio:
verifyapikey.{policy_name}.company.name
Le variabili disponibili includono:
Variabile | Descrizione |
---|---|
name |
Il nome dell'azienda. |
displayName |
Il nome visualizzato dell'azienda. |
id |
L'ID azienda. |
apps |
Un array contenente l'elenco delle app aziendali. |
appOwnerStatus |
Lo stato del proprietario dell'app, ovvero attivo, non attivo o login_lock.
|
created_at |
Il timestamp di data/ora di creazione dell'azienda. |
created_by |
L'indirizzo email dell'utente che ha creato l'azienda. |
last_modified_at |
Il timestamp di data/ora dell'ultima modifica dell'azienda. |
last_modified_by |
L'indirizzo email dell'utente che ha modificato per ultimo l'azienda. |
{company_custom_attributes} |
Qualsiasi attributo aziendale personalizzato. Specifica il nome dell'attributo personalizzato. |
Variabili di Analytics
Le seguenti variabili vengono compilate automaticamente in Analytics quando viene applicata una policy Verifica chiave API per una chiave API valida. Queste variabili vengono compilate solo dalle norme Verifica chiave API e dalle norme OAuth.
Le variabili e i valori possono essere utilizzati come dimensioni per creare report Analytics per ottenere visibilità sui pattern di consumo di sviluppatori e app.
- apiproduct.name
- developer.app.name
- client_id
- developer.id
Messaggi di errore
Questa sezione descrive i codici e i messaggi di errore restituiti, nonché le variabili di errore impostate da Edge quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per per gestire gli errori. Per saperne di più, consulta Cosa devi sapere sugli errori relativi ai criteri e sulla gestione di errore.
Errori di runtime
Questi errori possono verificarsi quando il criterio viene eseguito.
Codice di errore | Stato HTTP | Causa |
---|---|---|
keymanagement.service.CompanyStatusNotActive |
401 | La società associata all'app sviluppatore che dispone della chiave API in uso ha un non attivo. Quando lo stato di un'azienda è impostato su inattivo, non puoi accedere ai sviluppatori o app associati all'Azienda. Un amministratore dell'organizzazione può modificare lo stato di un'azienda utilizzando l'API di gestione. Consulta l'articolo Impostare lo stato. di una Società. |
keymanagement.service.DeveloperStatusNotActive |
401 |
Lo sviluppatore che ha creato l'app sviluppatore con la chiave API che stai utilizzando ha non attivo. Quando lo stato di uno sviluppatore di app è impostato su Inattivo, qualsiasi app sviluppatore create dallo sviluppatore vengono disattivate. Un utente amministratore con le autorizzazioni appropriate (ad es. Amministratore dell'organizzazione) può modificare lo stato di uno sviluppatore nei seguenti modi: modi:
|
keymanagement.service.invalid_client-app_not_approved |
401 | L'app sviluppatore associata alla chiave API è stata revocata. Un'app revocata non può accede a qualsiasi prodotto API e non può richiamare alcuna API gestita da Apigee Edge. Un amministratore dell'organizzazione può Modificare lo stato di un'app sviluppatore utilizzando l'API di gestione. Vedi Approvare o revocare l'app sviluppatore. |
oauth.v2.FailedToResolveAPIKey |
401 | Il criterio prevede di trovare la chiave API in una variabile specificata nella relativa <APIKey> . Questo errore si verifica quando il valore previsto non esiste (non può essere risolta). |
oauth.v2.InvalidApiKey |
401 | Una chiave API è stata ricevuta da Edge, ma non è valida. Quando Edge cerca la chiave deve corrispondere esattamente a quello inviato nella richiesta. Se l'API ha funzionato assicurati che la chiave non sia stata rigenerata. Se la chiave è stata rigenerata, vedrai questo errore se provi a usare la chiave precedente. Per maggiori dettagli, vedi Registrare app e gestire l'API chiave. |
oauth.v2.InvalidApiKeyForGivenResource |
401 | Una chiave API è stata ricevuta da Edge ed è valida. ma non corrisponde chiave approvata nell'App sviluppatore associata al tuo proxy API tramite un Prodotto. |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome errore | Causa |
---|---|
SpecifyValueOrRefApiKey |
Per l'elemento <APIKey> non è stato specificato un valore o una chiave. |
Variabili di errore
Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come elencato nella precedente tabella Errori di runtime. Il nome dell'errore è l'ultima parte del codice di errore. | fault.name Matches "FailedToResolveAPIKey" |
oauthV2.policy_name.failed |
policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. | oauthV2.VK-VerifyAPIKey.failed = true |
Esempi di risposte di errore
{ "fault":{ "faultstring":"Invalid ApiKey", "detail":{ "errorcode":"oauth.v2.InvalidApiKey" } } }
{ "fault":{ "detail":{ "errorcode":"keymanagement.service.DeveloperStatusNotActive" }, "faultstring":"Developer Status is not Active" } }
Esempio di regola di errore
<FaultRule name="FailedToResolveAPIKey"> <Step> <Name>AM-FailedToResolveAPIKey</Name> </Step> <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition> </FaultRule>