Utilizzo delle mappe chiave-valore

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa sezione descrive come utilizzare le mappe chiave-valore (KVM).

Panoramica

A volte vuoi archiviare i dati per il recupero in fase di runtime, ovvero dati non scaduti che non devono essere codificati nella logica del proxy API. Le mappe di coppie chiave-valore (KVM) sono ideali per questo scopo. Un KVM è una raccolta personalizzata di coppie di stringhe chiave/valore criptate.

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

  • Dati della sessione utente:dati creati ed eliminati solo dal runtime. Ad esempio, i contenuti del carrello degli acquisti.
  • Configurazione (ad esempio regole di routing e tabelle di ricerca): dati in genere creati al di fuori del runtime, ma letti dal runtime. Questi dati vengono configurati utilizzando la UI o l'API e poi 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 Service Callout) in un ambiente di test e un altro URL di destinazione in un ambiente di produzione. Anziché codificare gli URL nell'proxy API, puoi fare in modo che rilevi l'ambiente in cui si trova, esegua il criterio KeyValueMapOperations correlato e recuperi l'URL di destinazione corretto dal KVM appropriato.

    In un secondo momento, se uno o entrambi i target cambiano, è sufficiente aggiornare le KVM con i nuovi URL. Il proxy API rileva i nuovi valori e non è necessario eseguire un nuovo deployment.

  • Credenziali:memorizza credenziali, chiavi private o token, ad esempio token per servizi esterni, credenziali necessarie per generare token OAuth o chiavi private utilizzate nelle norme JavaCallout o JavaScript per la crittografia o la firma di token web JSON (JWT). Anziché passare credenziali, chiavi o token nella richiesta o codificarli nella logica del proxy, puoi archiviarli in una KVM e recuperarli dinamicamente nelle chiamate ai target che li richiedono.

Scoprirai altre situazioni in cui l'archiviazione di coppie di stringhe chiave/valore è utile. In generale, valuta la possibilità di utilizzare le KVM quando:

  • Sezioni specifiche del codice richiedono valori diversi in fase di runtime.
  • I dati sensibili devono essere trasmessi senza essere codificati in modo permanente.
  • Vuoi archiviare valori che non scadono come una cache.

In alcuni casi, i set di proprietà sono una buona alternativa alle KVM, in quanto possono essere più facili da utilizzare. Per ulteriori informazioni, consulta Utilizzare i set di proprietà.

Informazioni sull'ambito KVM

L'ambito definisce dove è disponibile un KVM. I KVM possono essere creati nei seguenti ambiti:

Ambito Descrizione
Proxy API Solo il proxy API può accedere al KVM.
Ambiente Tutti i proxy API in un ambiente specifico possono accedere alla KVM. Ad esempio, potresti voler impedire ai proxy API di cui è stato eseguito il deployment nell'ambiente prod di accedere ai KVM nell'ambiente test. Se vuoi che le stesse chiavi KVM siano disponibili in produzione, crea una KVM parallela con ambito limitato all'ambiente prod.
Organizzazione Tutti i proxy API in tutti gli ambienti possono accedere al KVM.

Informazioni sulla crittografia KVM

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

In Apigee Hybrid, puoi fornire chiavi di crittografia separate per tutte le voci KVM per i proxy API, l'organizzazione e gli ambiti dell'ambiente. Apigee accetta dimensioni di cifratura AES128, AES196 o AES256 come standard di crittografia.

Informazioni sul mascheramento KVM

Per impostazione predefinita, i valori KVM vengono visualizzati come testo normale. Puoi attivare la maschera KVM per mascherare i valori con asterischi (*****). Per attivare o disattivare la maschera KVM, utilizza l'impostazione Maschera valori nell'interfaccia utente o il flag maskedValues nella richiesta API.

I valori vengono mascherati a livello di KVM. Non puoi mascherare le singole voci KVM; tutti i valori all'interno di una KVM vengono mascherati oppure nessuno.

Nota:il mascheramento KVM non verrà attivato automaticamente per i KVM esistenti. Dovrai aggiornare esplicitamente le KVM esistenti per utilizzare il mascheramento KVM.

Crea KVM

Crea KVM come descritto nelle sezioni seguenti.

Interfaccia utente di Apigee

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

  1. Nella console Google Cloud , vai alla pagina Apigee > Gestione > Ambienti.

    Vai ad Ambienti

  2. Seleziona l'ambiente che vuoi modificare dall'elenco degli ambienti disponibili.
  3. Fai clic sulla scheda Mappe chiave-valore nella pagina Dettagli ambiente.

    La pagina Mappe chiave-valore mostra un elenco delle mappe chiave-valore esistenti. Se non hai creato KVM, l'elenco è vuoto.

  4. Per creare una nuova KVM-valore (vuota), fai clic su + Crea mappa di coppie chiave-valore.

    Si apre la finestra di dialogo Crea mappa di coppie chiave-valore.

  5. Inserisci un nome per la KVM-valore nel campo Nome mappa di coppie chiave-valore.

    Il nome può contenere solo lettere, numeri e trattini e non può superare i 255 caratteri. Non può includere spazi o altri caratteri speciali. Ad esempio: my-kvm-1

  6. Fai clic su Maschera valori per mascherare tutti i valori. Se non è selezionata, i valori KVM vengono visualizzati in testo normale. Per saperne di più, consulta la sezione Informazioni sul mascheramento KVM.
  7. Fai clic su Crea.

    Il nuovo KVM viene visualizzato nell'elenco.

API Apigee

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

Policy KVM

Per creare KVM in fase di runtime e aggiornarli nei proxy API, utilizza il criterio KeyValueMapOperations. Nella policy, specifica il nome del KVM nell'attributo mapIdentifier dell'elemento principale.

L'elemento <InitialEntries> consente di creare e compilare un insieme di base di voci in un nuovo 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 a KVM 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à, le coppie chiave/valore vengono aggiunte (o aggiornate se la chiave esiste già). Puoi utilizzare più elementi <Put> in una policy KVM.

Debug

Quando utilizzi il criterio KeyValueMapOperations per recuperare i valori KVM criptati, fornisci il nome di una variabile in cui archiviare il valore. Poiché tutti i valori KVM sono criptati, devi aggiungere il prefisso private. al nome della variabile, in modo che le coppie chiave/valore KVM non vengano visualizzate nelle sessioni di debug.

Ottieni KVM

Interfaccia utente di Apigee

Per visualizzare un elenco di KVM e i relativi dettagli nella UI di Apigee:

  1. Accedi all'elenco delle KVM per il tuo ambiente (vedi Crea KVM).
  2. La pagina Mappe chiave-valore mostra un elenco delle mappe chiave-valore esistenti.
  3. Seleziona il nome di un KVM per visualizzarne le voci e le impostazioni.

API Apigee

Utilizza le API Apigee per ottenere KVM per i seguenti ambiti:

Ad esempio, per ottenere un KVM con ambito proxy API, inserisci una richiesta GET al seguente URL:

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

Aggiorna KVM

Interfaccia utente di Apigee

Per aggiornare l'impostazione Valori maschera per un KVM esistente nella UI di Apigee:

  1. Accedi all'elenco delle KVM per il tuo ambiente (vedi Crea KVM).
  2. Seleziona il nome del KVM per aprire la pagina dei dettagli.
  3. Attiva/disattiva l'impostazione Maschera valori.
  4. Fai clic su Salva.

API Apigee

Utilizza le API Apigee per aggiornare i KVM per i seguenti ambiti:

Ad esempio, per aggiornare un KVM con ambito proxy API, inserisci una richiesta PUT al seguente URL:

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

Gestisci i valori KVM

Puoi gestire i valori KVM utilizzando i seguenti metodi:

Interfaccia utente di Apigee

Per gestire le voci KVM nella UI di Apigee:

  1. Accedi all'elenco delle KVM per il tuo ambiente (vedi Crea KVM).
  2. Seleziona il nome del KVM per aprire la pagina dei dettagli.
  3. Per gestire le voci:
    • Aggiungi una voce: fai clic su + Aggiungi. Compila i campi Chiave e Valore e fai clic su Aggiungi.
    • Modificare una voce: fai clic su Modifica accanto a una voce. Aggiorna il Valore e fai clic su Salva.
    • Eliminare una voce: fai clic su Elimina accanto a una voce. Fai clic su Elimina nella finestra di dialogo di conferma.

API Apigee

Utilizza le API Apigee per gestire i valori KVM per i seguenti ambiti:

Policy KeyValueMapOperations

Utilizza il KeyValueMapOperations policy per aggiungere, ottenere o eliminare valori dalle KVM.

Aggiungi chiavi e valori KVM utilizzando l'elemento <Put> del criterio KeyValueMapOperations. L'elemento <Put> crea un nuovo KVM se non ne esiste già uno e crea una chiave con uno o più valori. Se il KVM esiste già, le coppie chiave/valore vengono aggiunte (o aggiornate se la chiave esiste già). Puoi utilizzare più elementi <Put> in una policy KVM. Per saperne di più, consulta Elemento<Put>.

Ottieni i valori 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 durante il debug dei proxy API. Per ulteriori informazioni, vedi Elemento<Get>.

Elimina i valori KVM utilizzando l'elemento <Delete> del criterio KeyValueMapOperations. Per saperne di più, consulta la sezione Elemento<Delete>.

Elimina KVM

Elimina le KVM come descritto nelle sezioni seguenti.

Interfaccia utente di Apigee

Per eliminare un KVM:

  1. Nella console Google Cloud , vai alla pagina Apigee > Gestione > Ambienti.

    Vai ad Ambienti

  2. Seleziona il nome dell'ambiente che vuoi modificare dall'elenco degli ambienti disponibili.
  3. Fai clic sulla scheda Mappe chiave-valore nella pagina Dettagli ambiente.

    La pagina Mappe chiave-valore mostra un elenco delle mappe chiave-valore esistenti.

  4. Individua la riga del KVM che vuoi eliminare.
  5. Fai clic su Elimina nella colonna Azioni.
  6. Fai clic su Elimina mappa di coppie chiave-valore nella finestra di dialogo per confermare l'operazione.

    Il KVM viene eliminato e rimosso dall'elenco.

API Apigee

Utilizza una delle seguenti API Apigee per eliminare un KVM in base al suo ambito: