Utilizzo delle mappe di coppie chiave-valore

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

A volte vuoi archiviare i dati per il recupero in fase di runtime, dati non scaduti che non devono essere codificati in modo rigido nella logica del proxy API. Le mappe chiave-valore (KVM) sono ideali per questo. Una KVM è una raccolta personalizzata di coppie chiave/valore di tipo Stringa, criptate o non criptate. Ecco due esempi:

Per scoprire di più su altri tipi di persistenza, consulta Aggiungere la memorizzazione nella cache e la persistenza.

Scenari KVM

Ecco alcune situazioni in cui le KVM sono utili:

  • 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 in modo rigido gli URL in nel proxy, puoi fare in modo che il proxy rilevi l'ambiente in cui si trova, esegua la policy Operazioni della mappa chiave-valore correlata e recuperi l'URL di destinazione corretto da una delle KVM che hai creato. In un secondo momento, se una o entrambe le destinazioni cambiano, ti basterà aggiornare le KVM con i nuovi URL. Il proxy recupera i nuovi valori e non è necessario il ridimensionamento del proxy.
  • Vuoi archiviare credenziali, chiavi private o token, ad esempio token per servizi esterni , credenziali necessarie per generare token OAuth o chiavi private utilizzate in Java Callout o JavaScript per la crittografia o la firma di token web JSON (JWT). Anziché passare credenziali, chiavi o token nella richiesta o codificarli in modo rigido nella logica del proxy, puoi archiviarli in una KVM (sempre criptata) e recuperarli dinamicamente nelle chiamate alle destinazioni che li richiedono.

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

  • Luoghi specifici del codice richiedono valori diversi in fase di runtime.
  • I dati sensibili devono essere passati senza essere codificati in modo rigido.
  • Vuoi archiviare valori che non scadono come potrebbe fare una cache.

Le KVM hanno un ambito

L'ambito indica "dove è disponibile una KVM". Le KVM possono essere create nei seguenti ambiti: organization, environment e apiproxy.

Ad esempio, se solo un proxy API richiede dati in una KVM, puoi creare la KVM nell'ambito apiproxy dove solo quel proxy API può accedere ai dati.

In alternativa, potresti voler consentire a tutti i proxy API nel tuo ambiente di test di accedere a una mappa chiave-valore, nel qual caso creeresti una mappa chiave-valore nell'ambito dell'ambiente. I proxy di cui è stato eseguito il deployment nell'ambiente "prod" non possono accedere alle KVM nell'ambito dell'ambiente "test". Se vuoi che le stesse chiavi KVM siano disponibili in produzione, crea una KVM parallela con ambito "prod".

Se vuoi che tutti i proxy in tutti gli ambienti accedano alla stessa KVM, crea la KVM nell'ambito organization.

Informazioni sulle KVM criptate

Le KVM criptate vengono criptate con una chiave di crittografia AES-128 generata da Apigee. La chiave utilizzata per criptare una KVM viene archiviata nell'ambito della KVM. Ad esempio, all'interno di un'organizzazione, tutte le KVM criptate che crei nell'ambito dell'ambiente vengono create utilizzando la stessa chiave con ambito dell'ambiente.

Edge gestisce la visualizzazione dei valori criptati nei seguenti modi. (Per informazioni sulla creazione di KVM criptate, consulta Gestire e utilizzare le KVM.)

UI Edge

Le mappe chiave-valore criptate mostrano i valori mascherati con asterischi nell'UI (*****). Ad esempio:

API di gestione

Nell'API di gestione, i valori criptati vengono restituiti mascherati. Di seguito è riportata una risposta di esempio dell'API di gestione a una chiamata Get KVM criptata:

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}

Traccia e debug

Quando utilizzi la policy Operazioni della mappa chiave-valore per recuperare i valori KVM criptati, fornisci il nome di una variabile in cui archiviare il valore. Per ottenere un valore criptato, devi aggiungere il prefisso "private." al nome della variabile, in modo che le chiavi/i valori KVM non vengano visualizzati nelle sessioni di traccia e debug.

Limiti

Nelle organizzazioni con i servizi di persistenza principali (CPS) abilitati:

  • Il nome/identificatore KVM fa distinzione tra maiuscole e minuscole.
  • La dimensione della chiave è limitata a 2 KB.
  • La dimensione del valore è limitata a 10 KB.

Per Apigee Edge per il cloud privato, ogni KVM non deve superare i 15 MB (questa è la dimensione combinata delle chiavi e dei valori). Se superi questo limite, Apigee Edge per il cloud privato restituisce un errore. Per determinare la dimensione delle KVM, puoi utilizzare il comando nodetool cfstats.

Le KVM più grandi possono comportare un peggioramento delle prestazioni. Di conseguenza, per migliorare le prestazioni, devi suddividere le KVM grandi e monolitiche in KVM più piccole.

Gestire e utilizzare le KVM

Puoi creare, gestire e utilizzare le KVM in diversi modi. Questa sezione descrive le diverse opzioni per creare e poi recuperare le KVM criptate e non criptate.

Creare e aggiornare le KVM

Puoi creare e aggiornare le KVM nei seguenti modi:

  • Policy Operazioni della mappa chiave-valore (nessuna crittografia)

    Per la creazione e l'aggiornamento delle KVM in fase di runtime da parte dei proxy API, utilizza la policy Operazioni della mappa chiave-valore. (Nella policy, devi specificare il nome della KVM in l'attributo mapIdentifier dell'elemento principale.)

    L'<InitialEntries> elemento ti consente di creare e popolare un insieme di base di voci in una nuova KVM non appena salvi la policy nell'UI o esegui il deployment del proxy API (se l'hai sviluppato offline). Se i valori cambiano nella policy, i valori esistenti vengono sovrascritti. Le nuove chiavi/i nuovi valori vengono aggiunti alla KVM esistente insieme alle chiavi/ai valori 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 chiavi/i valori vengono aggiunti (o aggiornati se la chiave esiste già). Puoi utilizzare più <Put> elementi in una policy KVM.

  • API di gestione

    L'API di gestione è pensata per l'utilizzo delle KVM da parte di un amministratore anziché durante il runtime nei proxy API. Ad esempio, potresti avere uno script interno che utilizza l'API di gestione per eliminare e ricreare le KVM in un ambiente di test oppure potresti voler reimpostare il valore di una chiave in una KVM in modo che tutti i proxy lo recuperino. (Per la manipolazione delle KVM in fase di runtime, utilizza la policy Operazioni della mappa chiave-valore nei proxy).

    L'API di gestione delle mappe chiave-valore consente di creare, aggiornare ed eliminare le KVM e le chiavi/i valori criptati in tutti gli ambiti (organizzazione, ambiente e apiproxy).

    Per creare una KVM criptata con l'API di gestione, aggiungi "encrypted" : "true" al payload JSON. Puoi criptare le KVM solo quando le crei Non puoi criptare una KVM esistente.

  • UI di gestione

    Nell'UI di gestione di Edge, puoi creare e aggiornare le KVM con ambito dell'ambiente, che sono l'unico ambito di KVM visualizzato nell'UI. L'UI di gestione è un buon modo per amministrare manualmente i dati KVM per i proxy API in fase di runtime. Per saperne di più, consulta Creare e modificare le mappe chiave-valore dell'ambiente.

Recuperare le KVM

Puoi recuperare le mappe chiave-valore criptate e non criptate nello stesso modo, con una leggera variazione quando le recuperi con la policy Operazioni della mappa chiave-valore.

  • Policy: utilizza l'elemento <Get> nella policy Operazioni della mappa chiave-valore per recuperare le KVM criptate e non criptate. L'unica leggera differenza è il recupero dei valori criptati con la policy, in cui devi aggiungere un prefisso "private." al nome della variabile che conterrà il valore recuperato, come descritto nella sezione Operazione Get dell'argomento di riferimento. Questo prefisso nasconde il valore dalle sessioni di traccia e debug durante il debug dei proxy API.
  • API di gestione: per scopi di gestione amministrativa, puoi utilizzare Creare e modificare le mappe chiave-valore dell'ambiente per ottenere KVM e chiavi/valori. Ad esempio, se vuoi eseguire il backup delle KVM recuperando e archiviando le definizioni JSON, utilizza l'API di gestione. Tieni presente, tuttavia, che i valori criptati vengono visualizzati come ***** nella risposta dell'API.
  • UI di gestione: puoi visualizzare le KVM con ambito dell'ambiente nell'UI di gestione andando ad API > Configurazione ambiente > Mappe chiave-valore (Edge classico) o Amministrazione > Ambienti > Mappe chiave-valore (Edge nuovo).

Esempio di KVM

Per un esempio di utilizzo di una KVM per popolare i valori in un URL, consulta Creare un modello dell'URL di destinazione con la KVM per ambiente.