Utilizzo delle mappe di coppie chiave-valore

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

A volte, può capitare che tu voglia archiviare dati per recuperarli in fase di runtime, dati in scadenza che non devono essere impostati come hardcoded nella logica del proxy API. Le mappe chiave-valore (KVM) sono l'ideale. Un KVM è una raccolta personalizzata di coppie chiave/valore crittografate o non criptate. Ecco due esempi:

Per scoprire di più sugli altri tipi di persistenza, consulta la pagina relativa all'aggiunta di memorizzazione nella cache e persistenza.

Scenari KVM

Ecco alcune situazioni in cui i KVM possono tornare utili:

  • Hai un proxy API che deve chiamare un URL di destinazione (o callout di servizio) in un ambiente di test e un altro URL di destinazione in un ambiente di produzione. Anziché codificare gli URL nel proxy, puoi fare in modo che il proxy rilevi l'ambiente in cui si trova, eseguire il criterio Key Value Map Operations correlato e recuperare l'URL di destinazione corretto da uno dei KVM creati. In seguito, se uno o entrambi i target cambiano, sarà sufficiente aggiornare i KVM con i nuovi URL. Il proxy acquisisce i nuovi valori e non è necessario ripetere il deployment del proxy.
  • Vuoi archiviare 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 per la firma JWT (JSON Web Token). Invece di passare credenziali, chiavi o token nella richiesta oppure codificarli come hardcoded nella logica del proxy, puoi archiviarli in un KVM (sempre criptato) e recuperarli dinamicamente nelle chiamate ai target che li richiedono.

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

  • Posizioni specifiche nel codice richiedono valori diversi in fase di runtime.
  • I dati sensibili devono essere trasmessi senza codificarli come hardcoded.
  • Vuoi archiviare i valori che non scadono come una cache.

I KVM hanno un ambito

Per ambito si intende "dove è disponibile un KVM". I KVM possono essere creati nei seguenti ambiti: organization, environment e apiproxy.

Ad esempio, se un solo proxy API richiede dati in un KVM, puoi creare il KVM nell'ambito apiproxy, dove solo quel proxy API potrà accedere ai dati.

Oppure potresti volere che tutti i proxy API nel tuo ambiente di test abbiano accesso a una mappa chiave-valore, nel qual caso creerai una mappa chiave-valore nell'ambito dell'ambiente. I proxy di cui è stato eseguito il deployment nell'ambiente "prod" non possono accedere ai KVM nell'ambito dell'ambiente "test". Se vuoi che le stesse chiavi KVM siano disponibili in produzione, crea un KVM parallelo con ambito di produzione.

Se vuoi che tutti i proxy in tutti gli ambienti accedano allo stesso KVM, crea il KVM nell'ambito organization.

Informazioni sui KVM criptati

I KVM criptati sono criptati con una chiave di crittografia AES-128 generata da Apigee. La chiave utilizzata per criptare un KVM è archiviata nell'ambito del KVM. Ad esempio, all'interno di un'organizzazione, tutti i KVM criptati che crei nell'ambito dell'ambiente vengono creati utilizzando la stessa chiave basata sull'ambiente.

Edge gestisce la visualizzazione dei valori criptati nei seguenti modi. Per informazioni sulla creazione di KVM criptate, consulta la sezione Gestione e utilizzo dei dispositivi KVM.

UI perimetrale

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

API di gestione

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

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

Traccia ed esegui il debug

Quando utilizzi il criterio Operazioni mappa chiave-valore per recuperare valori KVM criptati, devi fornire il nome di una variabile per archiviare il valore. Per ottenere un valore criptato, devi aggiungere il prefisso "private." al nome della variabile, che impedisce la visualizzazione delle chiavi/valori KVM nelle sessioni di Trace e di debug.

Limiti

Nelle organizzazioni in cui sono abilitati i Core Persistence Services (CPS):

  • Il nome/l'identificatore KVM è sensibile alle maiuscole.
  • 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 (ovvero la dimensione combinata di chiavi e valori). Se superi questo limite, Apigee Edge per il cloud privato restituisce un errore. Per determinare le dimensioni dei tuoi KVM, puoi utilizzare il comando nodetool cfstats.

I KVM più grandi possono compromettere le prestazioni. Di conseguenza, i KVM monoolitici di grandi dimensioni devono essere suddivisi in dispositivi più piccoli per migliorare le prestazioni.

Gestione e utilizzo dei KVM

Puoi creare, gestire e utilizzare i KVM in diversi modi. Questa sezione descrive le diverse opzioni per la creazione e il recupero di KVM sia criptati che non criptati.

Creazione e aggiornamento di KVM

È possibile creare e aggiornare i KVM nei seguenti modi:

  • Norme relative alle operazioni sulla mappa chiave-valore (senza crittografia)

    Per la creazione e l'aggiornamento di KVM in runtime mediante i proxy API, utilizza il criterio relativo alle operazioni di mappa chiave-valore. Nel criterio, devi specificare il nome del KVM nell'attributo mapIdentifier dell'elemento padre.

    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, quelli esistenti vengono sovrascritti. Eventuali nuove chiavi/valori vengono aggiunte al KVM esistente insieme a chiavi/valori esistenti.

    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 un criterio KVM.

  • API di gestione

    L'API di gestione consente di lavorare con i KVM in qualità di 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 i KVM in un ambiente di test oppure potresti voler reimpostare il valore di una chiave in un KVM affinché tutti i proxy vengano recuperati. Per la manipolazione a livello di runtime dei KVM, utilizza il criterio relativo alle operazioni di mappa chiave-valore nei proxy.

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

    Per creare un KVM criptato con l'API di gestione, aggiungi "encrypted" : "true" al payload JSON. Puoi criptare i KVM solo quando li crei. Non puoi criptare un KVM esistente.

  • UI di gestione

    Nell'interfaccia utente di gestione perimetrale puoi creare e aggiornare KVM basati sull'ambiente, che sono l'unico ambito di KVM visualizzato nell'interfaccia utente. L'interfaccia utente di gestione è un ottimo modo per amministrare manualmente i dati KVM per i proxy API in fase di runtime. Per ulteriori informazioni, consulta la sezione Creazione e modifica delle mappe chiave-valore di ambiente.

Recupero dei KVM

Puoi recuperare le mappe delle coppie chiave-valore criptate e non criptate allo stesso modo, con una leggera variazione quando esegui il recupero con il criterio Key Value Map Operations.

  • Criterio: utilizza l'elemento <Get> nel criterio Operazioni di mappatura chiave-valore per recuperare KVM criptate e non criptate. L'unica piccola differenza è il recupero dei valori criptati con il criterio, in cui devi aggiungere un prefisso "private." al nome della variabile che conterrà il valore recuperato, come descritto nella sezione Recupero operazione dell'argomento di riferimento. Questo prefisso nasconde il valore nelle sessioni di traccia e debug mentre esegui il debug dei proxy API.
  • API di gestione: a fini di gestione amministrativa, puoi utilizzare la creazione e modifica di mappe chiave-valore dell'ambiente per ottenere KVM e chiavi/valori. Ad esempio, se vuoi eseguire il backup dei KVM recuperando e archiviando le definizioni JSON, utilizza l'API di gestione. Tuttavia, tieni presente che i valori criptati vengono visualizzati come ***** nella risposta dell'API.
  • UI di gestione: per visualizzare i tuoi KVM basati sull'ambiente nella UI di gestione, vai ad API > Configurazione ambiente > Mappe chiave-valore (Classic Edge) o Amministrazione > Ambienti > Mappe chiave-valore (nuovo Edge).

Esempio di KVM

Per un esempio di utilizzo di un KVM per inserire i valori in un URL, consulta https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html.