Utilizzo delle mappe chiave-valore

Stai visualizzando la documentazione di Apigee X.
Visualizza la documentazione di Apigee Edge.

Questa sezione illustra come utilizzare le mappe delle coppie chiave-valore (KVM).

Panoramica

Ci sono casi in cui vuoi archiviare dati per il recupero in fase di runtime, senza che i dati scadano, che non devono essere hardcoded nella logica del proxy dell'API. Le mappe di coppie chiave-valore (KVM) sono la soluzione ideale. Una KVM è una raccolta personalizzata di coppie chiave-valore criptate.

Di seguito sono elencati tre ampi casi d'uso per l'archiviazione di dati nelle KVM:

Dati delle sessioni utente: dati creati ed eliminati solo dal runtime; non è possibile visualizzare o gestire le voci KVM al di fuori del runtime. ad esempio i contenuti del carrello.
Configurazione (ad esempio regole di routing e tabelle di ricerca): dati che in genere vengono creati all'esterno del runtime, ma vengono letti dal runtime. Questi dati vengono configurati utilizzando l'interfaccia utente o l'API e vengono resi disponibili al gateway (come variabili o contenuti di sola lettura).
Ad esempio, hai un proxy API che deve chiamare un URL di destinazione (o un callout di servizio) in un ambiente di test e un altro URL di destinazione in un ambiente di produzione. Invece di impostare gli URL come hardcoded nel proxy dell'API, puoi fargli rilevare in quale ambiente si trova, eseguire il criterio KeyValueMapOperations correlato e recuperare l'URL di destinazione corretto dalla KVM appropriata.

In seguito, se uno o entrambi i target cambiano, dovrai semplicemente aggiornare le KVM con i nuovi URL. Il proxy API rileva i nuovi valori; non è necessario rieseguire il deployment.
Credenziali: archivia le credenziali, le chiavi private o i token, ad esempio token per servizi esterni, credenziali necessarie per generare token OAuth o chiavi private utilizzate nei callout Java o in JavaScript per la crittografia o la firma JWT (JSON Web Token). Invece di trasmettere le credenziali, le chiavi o i token nella richiesta o di codificarli nella logica del proxy, puoi archiviarli in una KVM e recuperarli dinamicamente nelle chiamate alle destinazioni che li richiedono.

Scoprirai altre situazioni in cui è utile archiviare le coppie chiave-valore della stringa. In generale, valuta l'utilizzo di KVM quando:

Le sezioni specifiche del codice richiedono valori diversi al momento dell'esecuzione.
I dati sensibili devono essere trasmessi senza hard coding.
Vuoi archiviare valori che non scadono come la cache.

In alcuni casi, i set di proprietà rappresentano una buona alternativa alle KVM, perché sono più facili da utilizzare. Per scoprire di più, consulta la sezione Utilizzo dei set di proprietà.

Informazioni sull'ambito KVM

L'ambito definisce dove è disponibile una KVM. Le KVM possono essere create nei seguenti ambiti:

Ambito	Descrizione
proxy API	Solo il proxy API può accedere alla KVM.
Ambiente	Tutti i proxy API in un ambiente specifico possono accedere alla KVM. Ad esempio, potresti volere che i proxy API di cui è stato eseguito il deployment nell'ambiente `prod` non abbiano accesso alle KVM nell'ambiente `test`. Se vuoi che le stesse chiavi KVM siano disponibili in produzione, crea una KVM parallela con ambito `prod`.
Organizzazione	Tutti i proxy API in tutti gli ambienti possono accedere a KVM.

Informazioni sulla crittografia KVM

In Apigee X, tutte le voci KVM per l'ambito proxy, l'organizzazione e gli ambiti dell'API sono protette utilizzando la chiave Cloud KMS fornita quando viene eseguito il provisioning di un'organizzazione Apigee (vedi il campo runtimeDatabaseEncryptionKey nella risorsa Organizzazione). Apigee utilizza AES256 come standard di crittografia.

In Apigee ibrido puoi fornire chiavi di crittografia separate per tutte le voci KVM per gli ambiti API, organizzazione e proxy. Apigee accetta dimensioni di crittografia di AES128, AES196 o AES256 come standard di crittografia.

Creazione di KVM

Crea KVM come descritto nelle sezioni seguenti.

Interfaccia utente di Apigee

Per creare una nuova KVM (vuota) o visualizzare un elenco di KVM:

Accedi alla UI di Apigee.
Seleziona Amministratore > ambienti > Mappe chiave-valore.
Dall'elenco a discesa dell'ambiente, seleziona l'ambiente per il quale vuoi creare una KVM.
Nella pagina Mappe chiave-valore viene visualizzato un elenco delle KVM esistenti. Se non hai creato alcuna KVM, l'elenco è vuoto.
Per creare una nuova KVM (vuota), fai clic su + Mappa chiave-valore.
Viene visualizzata la finestra di dialogo Aggiungi mappa chiave/valore.
Inserisci un nome per la KVM nel campo Nome.
Il nome può contenere solo lettere, numeri e trattini. Non può includere spazi o altri caratteri speciali. Ad esempio: my-kvm-1
Fai clic su Aggiungi.
Il nuovo KVM viene visualizzato nell'elenco.

API Apigee

Utilizza le API Apigee per creare, elencare ed eliminare KVM per i seguenti ambiti:

Criterio KVM

Per creare KVM in fase di runtime e aggiornarle nei proxy API, utilizza il criterio KeyValueMapOperations. Nel criterio, devi specificare il nome della KVM nell'attributo mapIdentifier sull'elemento principale.

L'elemento <InitialEntries> consente di creare e completare un insieme di voci di riferimento in una nuova KVM non appena salvi il criterio nell'interfaccia utente o esegui il deployment del proxy API (se lo hai sviluppato offline). Se i valori cambiano nel criterio, i valori esistenti vengono sovrascritti. Le nuove coppie chiave/valore vengono aggiunte alla KVM esistente insieme alle coppie chiave/valore esistenti.

L'elemento <Put> crea una nuova KVM se non ne esiste già una e crea una chiave con uno o più valori. Se la KVM esiste già, vengono aggiunte coppie di chiave/valore (o aggiornate se la chiave esiste già). In un criterio KVM puoi utilizzare più elementi <Put>.

Debug

Quando utilizzi il criterio KeyValueMapOperations per recuperare i valori KVM criptati, devi fornire il nome di una variabile per archiviare il valore. Poiché tutti i valori KVM sono criptati, devi aggiungere il prefisso private. al nome della variabile, impedendo così la visualizzazione delle coppie chiave-valore KVM nelle sessioni di debug.

Recupero delle KVM in corso...

Recupera le KVM utilizzando l'elemento <Get> del criterio KeyValueMapOperations. Poiché tutti i valori KVM sono criptati, aggiungi un prefisso private. al nome della variabile che conterrà il valore recuperato. Questo prefisso nasconde il valore dalle sessioni di debug mentre esegui il debug dei proxy API. Per maggiori informazioni, consulta la sezione <Get> elemento.

Eliminazione di KVM

Elimina le KVM come descritto nelle sezioni seguenti.

Interfaccia utente di Apigee

Per eliminare una KVM:

Accedi alla UI di Apigee.
Seleziona Amministratore > ambienti > Mappe chiave-valore.
Dall'elenco a discesa dell'ambiente, seleziona l'ambiente per il quale vuoi eliminare una KVM.
Nella pagina Mappe chiave-valore viene visualizzato un elenco delle KVM esistenti.
Posiziona il cursore sulla KVM che vuoi eliminare.
Fai clic su Elimina.
Fai clic su Elimina per confermare l'operazione.
La KVM viene eliminata e rimossa dall'elenco.

API Apigee

Utilizza una delle seguenti API Apigee per eliminare una KVM basata sull'ambito di essa: