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, ovvero dati non scaduti che non devono essere codificati nella logica del proxy API. Le mappe chiave-valore (KVM) sono ideali per questo scopo. Un KVM è una raccolta personalizzata di coppie di stringhe chiave/valore criptate o non criptate. Di seguito sono riportati due esempi:

Per scoprire di più su altri tipi di persistenza, consulta Aggiunta di memorizzazione nella cache e 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 gli URL nel proxy, puoi fare in modo che il proxy rilevi l'ambiente in cui si trova, esegua il criterio Operazioni di mapping chiave-valore correlato e recuperi l'URL di destinazione corretto da uno dei mapping chiave-valore che hai creato. Se in un secondo momento uno o entrambi i target cambiano, è sufficiente aggiornare le KVM con i nuovi URL. Il proxy rileva i nuovi valori e non è necessario un nuovo deployment 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 callout Java o JavaScript per la crittografia o la firma di token web JSON (JWT). Anziché trasmettere credenziali, chiavi o token nella richiesta o codificarli nella logica del proxy, puoi archiviarli in una KVM (sempre criptata) 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:

  • Punti specifici 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.

I KVM hanno un ambito

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

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

In alternativa, potresti voler concedere a tutti i proxy API nel tuo ambiente di test l'accesso 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 chiave KVM parallela con ambito "prod".

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

Informazioni sulle KVM criptate

I KVM criptati sono criptati 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 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 valori mascherati con asterischi nell'interfaccia utente (*****). Ad esempio:

API di gestione

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

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

Traccia e debug

Quando utilizzi il criterio Operazioni con le mappe chiave-valore per recuperare i valori KVM criptati, fornisci il nome di una variabile in cui memorizzare il valore. Per ottenere un valore criptato, devi aggiungere il prefisso "private." al nome della variabile, in modo da impedire che le chiavi/i valori KVM vengano visualizzati nelle sessioni di tracciamento e debug.

Limiti

Nelle organizzazioni con Core Persistence Services (CPS) abilitato:

  • Il nome/identificatore KVM è sensibile alle maiuscole.
  • La dimensione della chiave è limitata a 2 KB.
  • La dimensione del valore è limitata a 10 kB.

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

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

Gestione e utilizzo di KVM

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

Creazione e aggiornamento di KVM

Puoi creare e aggiornare le KVM nei seguenti modi:

  • Norme relative alle operazioni sulla mappa delle coppie chiave-valore (nessuna crittografia)

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

    L'elemento <InitialEntries> consente di creare e compilare un insieme di voci di base in una nuova KVM non appena salvi il criterio nella UI 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 chiavi/i nuovi valori vengono aggiunti alla KVM esistente insieme a quelli esistenti.

    L'elemento <Put> crea una nuova KVM se non ne esiste già una 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.

  • API di gestione

    L'API di gestione è pensata per l'utilizzo delle KVM come amministratore anziché durante l'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 per tutti i proxy. Per la manipolazione in fase di runtime delle mappe chiave-valore, utilizza il criterio Operazioni di mappa chiave-valore nei proxy.

    L'API di gestione delle mappe chiave/valore consente di creare, aggiornare ed eliminare KVM e chiavi/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 un KVM esistente.

  • UI di gestione

    Nell'interfaccia utente di gestione Edge, puoi creare e aggiornare KVM con ambito ambiente, che sono l'unico ambito di KVM che viene visualizzato nell'interfaccia utente. La UI di gestione è un buon 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 dell'ambiente.

Recupero di KVM

Recuperi le mappe chiave-valore criptate e non criptate nello stesso modo, con una leggera variazione quando recuperi con il Key Value Map Operations policy.

  • Policy: utilizza l'elemento <Get> nella policy Operazioni con le mappe chiave-valore per recuperare le KVM criptate e non criptate. L'unica leggera 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 Operazione Get dell'argomento di riferimento. Questo prefisso nasconde il valore dalle sessioni di Trace e debug durante il debug dei proxy API.
  • API Management: per scopi di gestione amministrativa, puoi utilizzare Creazione e modifica delle mappe di coppie 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 Management. Tieni presente, tuttavia, che i valori criptati vengono visualizzati come ***** nella risposta dell'API.
  • UI di gestione: puoi visualizzare le KVM con ambito ambiente nell'UI di gestione andando ad API > Configurazione ambiente > Key-Value Map (Classic Edge) o Amministrazione > Ambienti > Key-Value Map (New Edge).

Esempio di KVM

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