Utilizzo delle mappe di coppie chiave-valore

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

A volte potresti voler archiviare dati per il recupero in fase di runtime, ovvero dati non in scadenza che non devono essere impostati come hardcoded nella logica del proxy API. Le mappe chiave-valore (KVM) sono ideali per questo scopo. R KVM è una raccolta personalizzata di coppie chiave/valore di stringhe criptate o non criptate. Di seguito sono riportati due esempi:

Per saperne di più su altri tipi di persistenza, vedi Aggiunta di memorizzazione nella cache e persistenza.

Scenari KVM

Ecco alcune situazioni in cui le KVM tornano utili:

  • Hai un proxy API che deve chiamare un URL di destinazione (o callout di servizio) in un test e un altro URL di destinazione in un ambiente di produzione. Invece di inserire URL come hardcoded in tuo proxy, puoi fare in modo che il proxy rilevi in quale ambiente si trova, esegua la chiave correlata il criterio Value Map Operations e recuperare l'URL di destinazione corretto da una delle KVM che hai è stato creato. In seguito, se una o entrambe le destinazioni cambiano, è sufficiente aggiornare le KVM con i nuovi URL. Il proxy preleva i nuovi valori e non è necessario eseguire di nuovo il deployment del proxy.
  • Vuoi archiviare credenziali, chiavi private o token, ad esempio token per credenziali richieste per generare token OAuth o chiavi private utilizzato nei callout Java o JavaScript per la crittografia o la firma JWT (JSON Web Token). Invece di passare credenziali, chiavi o token nella richiesta oppure codificarli come hardcoded nella logica del proxy puoi archiviarle su una KVM (sempre criptata) e recuperarle dinamicamente e target che li richiedono.

Scoprirai altre situazioni in cui è utile memorizzare coppie chiave/valore. Nella in generale, prendi in considerazione l'utilizzo delle KVM quando:

  • Punti specifici del codice richiedono valori diversi durante il runtime.
  • I dati sensibili devono essere trasmessi senza hardcoded.
  • Vuoi archiviare i valori che non scadono come potrebbe essere una cache.

Le KVM hanno un ambito

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

Ad esempio, se un solo proxy API richiede i dati in una KVM, puoi creare la KVM apiproxy, in cui solo quel proxy API può accedere ai dati.

Oppure potresti volere che tutti i proxy API nel tuo ambiente di test abbiano accesso a una mappa chiave-valore, in questo caso creerai una mappa chiave-valore nell'ambito dell'ambiente. Proxy distribuiti "prod" non può accedere alle KVM nella sezione "test" nell'ambito dell'ambiente di lavoro. Se vuoi lo stesso KVM disponibili in produzione, crea una KVM parallela con ambito "prod" completamente gestito di Google Cloud.

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

Informazioni sulle KVM criptate

Le KVM criptate sono criptate con una chiave di crittografia AES-128 generata da Apigee. La chiave utilizzata crittografare una KVM viene archiviata nell'ambito della KVM. Ad esempio, all'interno di un'organizzazione, le KVM criptate create nell'ambito dell'ambiente vengono create utilizzando lo stesso ambito chiave.

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

UI Edge

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

API di gestione

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

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

Tracciamento e debug

Quando utilizzi il criterio Key-Value Map Operations per recuperare i valori KVM criptati, devi indicare il nome di una variabile per archiviare valore. Per ricevere un valore criptato, devi aggiungere "private." al prefisso che impedisce la visualizzazione di chiavi/valori KVM nelle sessioni di traccia e di debug.

Limiti

Nelle organizzazioni con Principale Servizi di persistenza (CPS) abilitati:

  • Il nome/l'identificatore della KVM è sensibile alle maiuscole.
  • Le dimensioni della chiave sono limitate 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 delle tue KVM, puoi utilizzare il comando nodetool cfstats.

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

Gestione e utilizzo delle KVM

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

Creazione e aggiornamento di KVM

Puoi creare e aggiornare le KVM nei seguenti modi:

  • Criterio per le operazioni di Key Value Map (nessuna crittografia)

    Per la creazione e l'aggiornamento di KVM runtime tramite proxy API, utilizza Norme relative alle operazioni della mappa chiave-valore. Nel criterio, specifichi il nome della KVM in l'attributo mapIdentifier nell'elemento principale element.)

    L'elemento <InitialEntries> ti 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 proxy API (se lo hai sviluppato offline). Se i valori cambiano nel criterio, i valori esistenti vengono sovrascritti. Tutte le nuove chiavi/valori vengono aggiunti alla KVM esistente insieme e le chiavi/valori esistenti.

    L'elemento <Put> crea una nuova KVM se non ne viene creata una. esistono già e crea una chiave con uno o più valori. Se la KVM è già installata esistono, vengono aggiunti (o aggiornati, se la chiave esiste già). Puoi utilizzare più elementi <Put> in un criterio KVM.

  • API di gestione

    L'API di gestione è destinata a lavorare con le KVM in qualità di amministratore anziché durante il runtime nei proxy API. Ad esempio, potresti avere uno script interno che utilizza lo script di gestione API per eliminare e ricreare le KVM in un ambiente di test oppure reimpostare il valore di una chiave in una KVM che possa essere usata da tutti i proxy. (per la manipolazione del runtime delle KVM, utilizza Norme relative alle operazioni della mappa chiave-valore nei proxy).

    L'API di gestione delle mappe chiave/valore. consente di creare, aggiornare ed eliminare KVM e chiavi/valori criptati 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 crei che li rappresentano. Non puoi criptare una KVM esistente.

  • UI di gestione

    Nell'interfaccia utente di gestione perimetrale puoi creare KVM con ambito ambiente, che sono l'unico ambito delle KVM che appare nell'interfaccia utente. L'interfaccia utente di gestione è un buon modo per amministrare manualmente i dati KVM per l'API proxy in fase di runtime. Consulta Creare e modificare le mappe chiave-valore degli ambienti per ulteriori informazioni.

Recupero delle KVM in corso

Le mappe dei valori chiave criptate e non criptate vengono recuperate nello stesso modo, con una leggera variazione durante il recupero con il criterio Key Value Map Operations.

  • Policy: utilizza l'elemento <Get> nella sezione Norme relative alle operazioni della mappa chiave-valore per recuperare le KVM criptate e non criptate. L'unica piccola differenza è recupero dei valori criptati con il criterio, in cui devi aggiungere "private." al nome della variabile che conterrà il valore recuperato, come descritto in Sezione Ottieni operazioni dell'argomento di riferimento. Questo prefisso nasconde il valore in Trace e debug durante il debug dei proxy API.
  • API di gestione: ai fini della gestione amministrativa, puoi utilizzare la Creazione e modifica delle mappe chiave-valore degli ambienti per ottenere KVM e chiavi/valori. Ad esempio, se vuoi eseguire il backup delle KVM recuperando e memorizzando le definizioni JSON, utilizzando l'API di gestione. Attenzione, tuttavia, i valori criptati vengono visualizzati come ***** nella risposta dell'API.
  • Interfaccia utente di gestione: puoi visualizzare le KVM con ambito di ambiente nella UI da API > Configurazione dell'ambiente > Mappe chiave-valore (Versione classica di Edge) o Amministratore > Ambienti > Mappe chiave-valore (New Edge).

Esempio di KVM

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