Attività di mappatura dei dati

L'attività Mappatura dei dati consente di eseguire assegnazioni di variabili nell'integrazione, ottenere e impostare proprietà degli oggetti JSON e applicare funzioni di trasformazione nidificate ai valori. Le variabili possono essere variabili di integrazione o variabili attività.

Ad esempio, puoi assegnare valori da una variabile di integrazione X a una variabile attività Y o da una variabile attività Y a una variabile di integrazione X. Per ulteriori informazioni sulle variabili in Apigee Integration, consulta la pagina Utilizzare le variabili in Apigee Integration.

Configura l'attività di mappatura dei dati

Per configurare un'attività di mappatura dei dati, segui questi passaggi:

  1. Nell'UI di Apigee, seleziona la tua organizzazione Apigee.
  2. Fai clic su Sviluppa > Integrazioni.
  3. Seleziona un'integrazione esistente o creane una nuova facendo clic su Crea integrazione.

    Se stai creando una nuova integrazione:

    1. Inserisci un nome e una descrizione nella finestra di dialogo Crea integrazione.
    2. Seleziona una regione per l'integrazione dall'elenco delle regioni supportate.
    3. Fai clic su Crea.

    Viene aperta l'integrazione nel designer dell'integrazione.

  4. Nella barra di navigazione integration designer, fai clic su +Aggiungi un'attività/un attivatore > Tasks per visualizzare l'elenco delle attività disponibili.
  5. Fai clic sull'elemento Mappatura dei dati e posizionalo nell'editor dell'integrazione.
  6. Fai clic sull'elemento Mappatura dei dati nel designer per visualizzare il riquadro di configurazione dell'attività Mappatura dei dati.
  7. Fai clic su Apri editor di mappatura dei dati per visualizzare i valori predefiniti dell'attività e aggiungere una nuova mappatura. Per la procedura dettagliata su come aggiungere una mappatura, consulta Aggiungere una mappatura.

    Per saperne di più sul layout dell'editor di mappatura dati, consulta Panoramica della mappatura dei dati.

Aggiungi una mappatura

Per aggiungere una mappatura, segui questi passaggi:

  1. Nel riquadro di configurazione dell'attività di mappatura dei dati, fai clic su Apri editor mappatura dati.
  2. Configura la mappatura Input:
    1. Trascina una variabile o il relativo campo secondario dall'elenco Variabili alla riga Input. Per visualizzare i sottocampi disponibili di una variabile, fai clic su (Espandi) accanto alla variabile nell'elenco Variabili.
    2. In alternativa, nella riga Input, fai clic su Variabile o Valore e attieniti alla procedura seguente:
      • Seleziona Variabile per cercare e utilizzare una variabile esistente. Per creare una nuova variabile, fai clic su + Aggiungi nuova variabile e inserisci il nome e il tipo di dati della nuova variabile.
      • Seleziona Valore per inserire un valore letterale di tipo string, integer, double o Boolean.
      • Seleziona Funzione per cercare e utilizzare una funzione di base.

        Una funzione di base viene utilizzata per recuperare o generare valori durante l'esecuzione di un'integrazione. Ad esempio, la generazione di un UUID casuale o il recupero della regione di integrazione attuale. Per informazioni sulle funzioni di base supportate, vedi Funzioni di base supportate.

      • Fai clic su Salva.
    3. Fai clic su + (Aggiungi una funzione) su qualsiasi variabile di input, valore o funzione di base nella riga Input per aggiungere una funzione di mappatura dall'elenco delle funzioni di mappatura disponibili. Una funzione di mappatura può avere uno o più parametri. Ogni parametro può inoltre avere un valore, una variabile o una funzione base seguita da una catena di funzioni di mappatura.
      • Per aggiungere una funzione nidificata, fai clic su + (Aggiungi una funzione) accanto al parametro della funzione. Allo stesso modo, per rimuovere o eliminare la funzione aggiunta più di recente, fai clic su - (Elimina funzione precedente).
      • Per aggiungere, rimuovere o modificare una funzione tra un'espressione di mappatura e l'altra, fai clic su una funzione e seleziona rispettivamente Aggiungi funzione, Rimuovi funzione o Modifica funzione dal menu a discesa.

        • Per saperne di più sulle funzioni di mappatura, consulta la pagina sulle funzioni di mappatura.

        Per informazioni sulle funzioni di mappatura supportate, vedi Tipi di dati e funzioni di mappatura supportati.

      • Per rimuovere una variabile all'interno di un'espressione di mappatura, fai clic su (Rimuovi) accanto alla riga della variabile.
      • Per rimuovere l'intera riga Input, fai clic su (Cancella) nella riga.
  3. Configura la mappatura Output:
    1. Trascina una variabile dall'elenco Variabili alla riga Output. Se la variabile non è disponibile, fai clic su Creane una nuova per configurare il nome e il tipo di dati della nuova variabile. Facoltativamente, puoi fare clic sulla variabile di output e scegliere se utilizzarla come output dell'integrazione o come input per un'altra integrazione.
    2. Per rimuovere la variabile di output, fai clic su (Cancella).
  4. (Facoltativo) Per eliminare una riga di mappatura, fai clic su (Elimina questa mappatura).
  5. Chiudi l'editor di mappatura dei dati al termine della mappatura. Eventuali modifiche verranno salvate automaticamente.

La mappatura dei dati completata può essere visualizzata nel riquadro di configurazione dell'attività Mappatura dei dati, come mostrato nell'immagine seguente:

immagine che mostra l'editor di mappatura dei dati immagine che mostra l'editor di mappatura dei dati

Funzioni di mappatura e tipi di dati supportati

Apigee Integration supporta i seguenti tipi di dati per le variabili nell'attività Mappatura dei dati:

  • Stringa e array di stringhe
  • Numero intero e array intero
  • Array doppio e doppio
  • array booleani e booleani
  • JSON
La tabella seguente elenca le funzioni di mappatura dei dati disponibili per ogni tipo di dati.
Tipo di dati Funzioni di mappatura supportate
Booleano AND, EQUALS, NAND, NOR, NOT, OR, TO_JSON, TO_STRING, XOR, XOR
Matrice booleana APPEND, APPEND_ALL, CONTAINS, FILTRO, FOR_EACH, GET, RIMUOVI, REMOVE_AT, IMPOSTA, DIMENSIONI, TO_IMPOSTAZIONITO_JSONTO_SET
Doppio ADD2, DIVIDE, CEIL, EQUALS, EXPONENT, GREATER_THAN, GREATER_THAN_EQUAL_TO, FLOOR, LESS_THE{/17LES}S ROUND_18}LESS_THAN_EQUAL_TOMULTIPLYROUNDSUBTRACTTO_JSONTO_STRING
Array doppio APPEND, APPEND_ALL, AVG, CONTAINS, FILTRO, FOR_EACH, GET, MAX, MIN, RIMUOVERE, REMOVE_ATTO_JSONTO_SET
Integer ADD2, DIVIDE, EPOCH_TO_HUMAN_READABLE_TIME, EQUALS, EXPONENT, GREATER_THAN, GREATER_THAN_EQUAL_TO, LESS_THAN, {17_QUALS_TH16}LESS_THAN_EQUAL_TOMULTIPLYSUBTRACTTO_DOUBLETO_JSONTO_STRING
Array intero APPEND, APPEND_ALL, AVG, CONTAINS, FILTRO, FOR_EACH, GET, MAX, MIN, RIMUOVERE, REMOVE_ATTO_JSONTO_SET
JSON APPEND_ELEMENT, FLATTEN, FILTER, FOR_EACH, GET_ELEMENT, GET_PROPERTY, MERGE, REMOVE_PROPERTY, RESOLVE_TEMPLATE, 19TOPROPERTY, TO_BOOLEANTO_BOOLEAN_ARRAYTO_DOUBLETO_DOUBLE_ARRAYTO_INTTO_INT_ARRAYTO_STRINGTO_STRING_ARRAY
String CONCAT, CONTAINS, DECODE_BASE64_STRING, EQUALS, EQUALS_IGNORE_CASE, LENGTH, REPLACE_ALL, RESOLVE_TEMPLATE, SPLIT, TO_BASE_64TO_BOOLEANTO_DOUBLETO_INTTO_JSONTO_LOWERCASETO_UPPERCASE
Array di stringhe APPEND, APPEND_ALL, CONTAINS, FILTRO, FOR_EACH, GET, RIMUOVI, REMOVE_AT, IMPOSTA, DIMENSIONI, TO_IMPOSTAZIONITO_JSONTO_SET
Per ulteriori informazioni su ciascuna funzione di mappatura dei dati, consulta la pagina di riferimento sulle funzioni di mappatura dei dati.

Funzioni di base supportate

La seguente tabella elenca le funzioni di base della mappatura dei dati disponibili:
Tipo di dati Funzioni di base supportate
Integer NOW_IN_MILLIS
Array intero INT_LIST
String GENERATE_UUID, GET_EXECUTION_ID, GET_INTEGRATION_NAME, GET_INTEGRATION_REGION, GET_PROJECT_ID
Per ulteriori informazioni su ciascuna delle funzioni di base di mappatura dati, consulta la pagina di riferimento sulle funzioni di mappatura dati.

Best practice

L'attività di mappatura dei dati può essere un modo efficace per trasformare e passare variabili chiave a varie attività nell'integrazione. Ecco alcuni suggerimenti da tenere a mente durante la creazione dell'integrazione:

  • Le mappature vengono eseguite in sequenza dall'alto verso il basso. In altre parole, se la variabile di input A è mappata a una variabile di output B nella prima riga, la variabile B è disponibile per la mappatura nelle righe successive.
  • In ogni riga, il tipo di dati della riga Input deve corrispondere al tipo di dati della riga Output. Per eseguire la trasmissione tra tipi, utilizza funzioni di trasformazione come TO_STRING e TO_INT.
  • Non ci sono limitazioni alla lunghezza del concatenamento delle trasformazioni. Tuttavia, il debug di trasformazioni concatenate di grandi dimensioni può essere difficile. Consigliamo di mantenere leggibili le trasformazioni di input e di suddividere le trasformazioni complesse in più mappature.
  • Se una mappatura richiede un valore di riserva, imposta un valore di riserva per la mappatura. Se non fornisci un valore di riserva, la mappatura restituisce un errore quando il valore di input o la trasformazione restituisce null.
  • Quando elimini una variabile, assicurati di eliminare tutti i mapping che la contengono.

Per informazioni sui limiti di utilizzo che si applicano all'attività Mappatura dei dati, vedi Limiti di utilizzo.

Considerazioni

Per le variabili JSON, in base a uno schema JSON, Apigee Integration interpreta la proprietà secondaria della variabile come un tipo JSON nei seguenti casi:

  • Se il tipo della proprietà figlio specifica null. Ad esempio: 
    {
  "properties": {
    "PersonID": {
      "type": [
        "double",
        "null"
      ],
      "readOnly": false
    }
  }
}
  • Se il tipo di proprietà secondaria specifica più tipi di dati. Ad esempio: 
    {
  "properties": {
    "PersonID": {
      "type": [
        "integer",
        "string",
        "number"
      ],
      "readOnly": false
    }
  }
}

In questi casi, utilizzando le funzioni di mappatura dei dati, devi convertire esplicitamente le variabili figlio nel tipo desiderato.

I seguenti esempi illustrano i vari tipi di dichiarazioni delle proprietà e mostrano come utilizzare le funzioni di mappatura dei dati per ottenere il tipo desiderato:

Esempio 1

{
  "type": "object",
  "properties": {
    "dbIntegers": {
      "type": "array",
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    },
    "dbBooleans": {
      "type": [
        "array"
      ],
      "items": {
        "type": "boolean"
      }
    }
  }
}
Apigee Integration interpreta dbIntegers come un tipo JSON e dbBooleans come un tipo BOOLEAN_ARRAY.

Per convertire dbIntegers usa: 

dbIntegers.TO_INT_ARRAY()

Esempio 2

{
  "type": "object",
  "properties": {
    "dbId": {
      "type": [
        "number",
        "null"
      ],
      "readOnly": false
    },
    "dbStatus": {
      "type": [
        "boolean",
        "null"
      ],
      "readOnly": false
    }
  }
}
Apigee Integration riconosce sia dbId che dbStatus come tipi JSON, ma dbId è un parametro che può assumere un singolo valore doppio o nullo e dbStatus è un parametro che può assumere un singolo valore booleano o null.

Per convertire dbId e dbStatus utilizza: 

dbId.TO_DOUBLE()
dbStatus.TO_BOOLEAN()

Esempio 3

{
  "type": "object",
  "properties": {
    "dbString": {
      "type": [
        "string"
      ],
      "readOnly": false
    }
  }
}
Apigee Integration riconosce dbString come tipo di stringa.

Strategia di gestione degli errori

Una strategia di gestione degli errori per un'attività specifica l'azione da eseguire se l'attività non riesce a causa di un errore temporaneo. Per informazioni su come utilizzare una strategia di gestione degli errori e per conoscere i diversi tipi di strategie di gestione degli errori, consulta l'articolo sulle strategie di gestione degli errori.