Aggiungere mappe per le trasformazioni nei flussi di lavoro con App per la logica di Azure

  • Articolo

Si applica a: App per la logica di Azure (consumo + standard)

Le azioni del flusso di lavoro, ad esempio Transform XML e Liquid , richiedono una mappa per eseguire le attività. L'azione Trasforma XML , ad esempio, richiede una mappa per convertire xml tra formati. Una mappa è un documento XML che usa il linguaggio XSLT (Extensible Stylesheet Language Transformation) per descrivere come convertire i dati da XML in un altro formato e ha l'estensione xslt. La mappa è costituita da un XML Schema di origine come input e da uno schema XML di destinazione come output. È possibile definire una trasformazione di base, ad esempio copiare un nome e un indirizzo da un documento a un altro. In alternativa, è possibile creare trasformazioni più complesse usando operazioni di mapping predefinite. È possibile modificare o controllare i dati usando diverse funzioni predefinite, ad esempio manipolazioni di stringhe, assegnazioni condizionali, espressioni aritmetiche, formattatori di data e persino costrutti di ciclo.

Si supponga, ad esempio, di ricevere regolarmente ordini B2B o fatture da un cliente che usa il formato di data YearMonthDay (AAAAMMGG). Tuttavia, l'organizzazione usa il formato di data MonthDayYear (MMDDYYYYY). È possibile definire e usare una mappa che trasforma il formato AAAAMMGG nel formato MMDDYYYYY PRIMA di archiviare i dettagli dell'ordine o della fattura nel database attività del cliente.

Questa guida illustra come aggiungere una mappa per il flusso di lavoro da usare. È possibile aggiungere mappe all'account di integrazione collegato oppure, se si dispone di un'app per la logica Standard, è possibile aggiungere mappe direttamente alla risorsa dell'app per la logica.

Prerequisiti

  • Account e sottoscrizione di Azure. Se non si ha ancora una sottoscrizione, iscriversi per ottenere un account Azure gratuito.

  • Mappa da aggiungere. Per creare mappe, è possibile usare uno degli strumenti seguenti:

    • Visual Studio Code e l'estensione Data Mapper. Per chiamare le mappe create con Data Mapper dal flusso di lavoro, è necessario usare l'azione Operazioni Di mapper dati denominata Transform using Data Mapper XSLT, non l'azione Operazioni XML denominata Transform XML. Per altre informazioni, vedere Creare mappe per la trasformazione dei dati con Visual Studio Code.

    • Visual Studio 2019 e l'estensione Microsoft App per la logica di Azure Enterprise Integration Tools.

    • Visual Studio 2015 e l'estensione Microsoft App per la logica di Azure Enterprise Integration Tools per Visual Studio 2015 2.0.

      Nota

      Non installare l'estensione Microsoft App per la logica di Azure Enterprise Integration Tools insieme all'estensione BizTalk Server. La presenza di entrambe le estensioni potrebbe produrre un comportamento imprevisto. Assicurarsi di avere installato solo una di queste estensioni.

      Nei monitor ad alta risoluzione è possibile che si verifichi un problema di visualizzazione con la finestra di progettazione mappe in Visual Studio. Per risolvere questo problema di visualizzazione, riavviare Visual Studio in modalità DPI-unware o aggiungere il valore del Registro di sistema DPIUNAWARE.

      Per altre informazioni, vedere la sezione Creare mappe in questo articolo.

  • In base al fatto che si stia lavorando a un flusso di lavoro dell'app per la logica a consumo o Standard, è necessaria una risorsa dell'account di integrazione. In genere, questa risorsa è necessaria quando si vogliono definire e archiviare artefatti da usare nei flussi di lavoro di integrazione aziendale e B2B.

    Importante

    Per collaborare, sia l'account di integrazione che la risorsa dell'app per la logica devono esistere nella stessa sottoscrizione di Azure e nella stessa area di Azure.

    • Se si usa un flusso di lavoro dell'app per la logica a consumo, è necessario un account di integrazione collegato alla risorsa dell'app per la logica.

    • Se si usa un flusso di lavoro dell'app per la logica Standard, è possibile collegare l'account di integrazione alla risorsa dell'app per la logica, caricare le mappe direttamente nella risorsa dell'app per la logica o entrambe, in base agli scenari seguenti:

      • Se si ha già un account di integrazione con gli artefatti necessari o da usare, è possibile collegare l'account di integrazione a più risorse dell'app per la logica Standard in cui si vogliono usare gli artefatti. In questo modo, non è necessario caricare mappe in ogni singola app per la logica. Per altre informazioni, vedere Collegare la risorsa dell'app per la logica all'account di integrazione.

      • Il connettore predefinito Liquid consente di selezionare una mappa caricata in precedenza nella risorsa dell'app per la logica o in un account di integrazione collegato, ma non entrambi.

      Pertanto, se non si ha o non è necessario un account di integrazione, è possibile usare l'opzione di caricamento. In caso contrario, è possibile usare l'opzione di collegamento. In entrambi i casi, è possibile usare questi artefatti in tutti i flussi di lavoro figlio all'interno della stessa risorsa dell'app per la logica.

  • I flussi di lavoro a consumo e Standard supportano mappe XSLT che fanno riferimento ad assembly esterni, che consentono di chiamare direttamente codice .NET personalizzato dalle mappe XSLT. Per supportare questa funzionalità, i flussi di lavoro a consumo hanno anche i requisiti seguenti:

    • È necessario un assembly a 64 bit. Il servizio di trasformazione esegue un processo a 64 bit, quindi gli assembly a 32 bit non sono supportati. Se si dispone del codice sorgente per un assembly a 32 bit, ricompilare il codice in un assembly a 64 bit. Se il codice sorgente non è disponibile, ma è stato ottenuto il file binario da un provider di terze parti, ottenere la versione a 64 bit da tale provider. Ad esempio, alcuni fornitori forniscono assembly nei pacchetti con versioni a 32 bit e a 64 bit. Se è disponibile l'opzione , usare invece la versione a 64 bit.

    • È necessario caricare sia l'assembly che la mappa in un ordine specifico per l'account di integrazione. Assicurarsi di caricare prima l'assembly e quindi la mappa che fa riferimento all'assembly.

    • Se l'assembly o la mappa è di 2 MB o di dimensioni inferiori, è possibile aggiungere l'assembly ed eseguire il mapping all'account di integrazione direttamente dal portale di Azure.

    • Se l'assembly è maggiore di 2 MB, ma non è superiore al limite di dimensioni per gli assembly, è necessario un account di archiviazione di Azure e un contenitore BLOB in cui è possibile caricare l'assembly. Successivamente, è possibile specificare la posizione del contenitore quando si aggiunge l'assembly all'account di integrazione. Per questa attività, la tabella seguente descrive gli elementi necessari:

      Articolo Descrizione
      Account di archiviazione di Azure In questo account creare un contenitore BLOB di Azure per l'assembly. Informazioni su come creare un account di archiviazione.
      Contenitore BLOB In questo contenitore è possibile caricare l'assembly. È necessario anche il percorso dell'URI del contenuto di questo contenitore quando si aggiunge l'assembly all'account di integrazione. Informazioni su come creare un contenitore BLOB.
      Azure Storage Explorer Questo strumento consente di gestire più facilmente gli account di archiviazione e i contenitori BLOB. Per usare Storage Explorer, scaricare e installare Azure Storage Explorer, quindi connettere Storage Explorer all'account di archiviazione seguendo i passaggi illustrati in Introduzione a Storage Explorer. Per altre informazioni, vedere Avvio rapido: Creare un BLOB nell'archivio oggetti con Archiviazione di Azure Explorer.

      In alternativa, nella portale di Azure selezionare l'account di archiviazione. Dal menu dell'account di archiviazione selezionare Storage Explorer.

      Per aggiungere mappe più grandi, è possibile usare l'API REST App per la logica di Azure - Mappe. Per i flussi di lavoro Standard, l'API REST di App per la logica di Azure non è attualmente disponibile.

Limiti

  • I limiti si applicano al numero di artefatti, ad esempio mappe, per account di integrazione. Per altre informazioni, vedere Limiti e informazioni di configurazione per App per la logica di Azure.

  • In base al fatto che si stia lavorando a un flusso di lavoro di app per la logica a consumo o standard, si applicano le limitazioni seguenti:

    • Flussi di lavoro standard

      • Supporto di XSLT 1.0, 2.0 e 3.0.

      • Non si applicano limiti alle dimensioni dei file di mapping.

    • Flussi di lavoro a consumo

      • App per la logica di Azure alloca memoria limitata per l'elaborazione delle trasformazioni XML. Se si creano flussi di lavoro a consumo e le trasformazioni della mappa o del payload hanno un consumo elevato di memoria, tali trasformazioni potrebbero non riuscire, causando errori di memoria insufficiente. Per evitare questo scenario, prendere in considerazione queste opzioni:

        • Modificare le mappe o i payload per ridurre il consumo di memoria.

        • Creare flussi di lavoro di app per la logica Standard, che vengono eseguiti in App per la logica di Azure a tenant singolo e offrono opzioni dedicate e flessibili per le risorse di calcolo e memoria.

Creare una mappa

È possibile creare mappe usando Visual Studio Code con l'estensione Data Mapper o Visual Studio con l'estensione Microsoft App per la logica di Azure Enterprise Integration Tools.

Visual Studio Code

Quando si creano mappe usando Visual Studio Code e l'estensione Data Mapper, è possibile chiamare queste mappe dal flusso di lavoro, ma solo con l'azione Operazioni di Data Mapper denominata Transform using Data Mapper XSLT, non l'azione Operazioni XML denominata Transform XML. Per altre informazioni, vedere Creare mappe per la trasformazione dei dati con Visual Studio Code.

Visual Studio

Quando si creano mappe usando Visual Studio, è necessario creare un progetto di integrazione con uno degli strumenti seguenti:

Nel progetto di integrazione è possibile compilare un file della mappa di integrazione, che consente di eseguire il mapping visivo degli elementi tra due file di XML Schema. Questi strumenti offrono le funzionalità della mappa seguenti:

  • Si lavora con una rappresentazione grafica della mappa, che mostra tutte le relazioni e i collegamenti creati.

  • È possibile creare una copia diretta dei dati tra gli XML Schema usati per creare la mappa. Enterprise Integration SDK per Visual Studio include un mapper che rende questa attività semplice come disegnare una linea che connette gli elementi nello schema XML di origine con le controparti nello schema XML di destinazione.

  • Sono disponibili operazioni o funzioni per più mappe, tra cui funzioni stringa, funzioni di data e così via.

  • Per aggiungere un messaggio XML di esempio, è possibile usare la funzionalità di test della mappa. Con un solo gesto, è possibile testare la mappa creata ed esaminare l'output generato.

  • Dopo aver compilato il progetto, si ottiene un documento XSLT.

La mappa deve avere gli attributi seguenti e una CDATA sezione contenente la chiamata al codice dell'assembly:

  • name è il nome dell'assembly personalizzato.

  • namespace è lo spazio dei nomi nell'assembly che include il codice personalizzato.

Nell'esempio seguente viene illustrata una mappa che fa riferimento a un assembly denominato XslUtilitiesLib e chiama il circumference metodo dall'assembly.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:msxsl="urn:schemas-microsoft-com:xslt" xmlns:user="urn:my-scripts">
<msxsl:script language="C#" implements-prefix="user">
    <msxsl:assembly name="XsltHelperLib"/>
    <msxsl:using namespace="XsltHelpers"/>
    <![CDATA[public double circumference(int radius){ XsltHelper helper = new XsltHelper(); return helper.circumference(radius); }]]>
</msxsl:script>
<xsl:template match="data">
<circles>
    <xsl:for-each select="circle">
        <circle>
            <xsl:copy-of select="node()"/>
                <circumference>
                    <xsl:value-of select="user:circumference(radius)"/>
                </circumference>
        </circle>
    </xsl:for-each>
</circles>
</xsl:template>
</xsl:stylesheet>

Aggiungere gli assembly a cui viene fatto riferimento

Una risorsa dell'app per la logica a consumo supporta il riferimento agli assembly esterni dalle mappe, che consentono di chiamare direttamente codice .NET personalizzato dalle mappe XSLT.

  1. Nella casella di ricerca portale di Azure immettere gli account di integrazione e selezionare Account di integrazione.

  2. Selezionare l'account di integrazione in cui si vuole aggiungere l'assembly.

  3. Nel menu dell'account di integrazione selezionare Panoramica. In Impostazioni selezionare Assembly.

  4. Sulla barra degli strumenti del riquadro Assembly selezionare Aggiungi.

In base alle dimensioni del file di assembly, seguire i passaggi per caricare un assembly di dimensioni pari o inferiori a 2 MB oppure comprese tra 2 MB e 8 MB. Per i limiti sulle quantità di assembly negli account di integrazione, vedere Limiti e configurazione per App per la logica di Azure.

Nota

Se si modifica l'assembly, è anche necessario aggiornare la mappa indipendentemente dal fatto che la mappa abbia o meno modifiche.

Aggiungere assembly di dimensioni pari o inferiori a 2 MB

  1. In Aggiungi assembly immettere un nome per l'assembly. Mantenere selezionato File piccolo. Accanto alla casella Assembly selezionare l'icona della cartella. Trovare e selezionare l'assembly che si sta caricando.

    Dopo aver selezionato l'assembly, la proprietà Nome assembly visualizza automaticamente il nome del file dell'assembly.

  2. Al termine, seleziona OK.

    Al termine del caricamento del file di assembly, l'assembly viene visualizzato nell'elenco Assembly. Nel riquadro Panoramica dell'account di integrazione, in Artefatti, viene visualizzato anche l'assembly caricato.

Aggiungere assembly di dimensioni superiori a 2 MB

Per aggiungere assembly più grandi, è possibile caricare l'assembly in un contenitore BLOB di Azure nell'account di archiviazione di Azure. I passaggi per l'aggiunta di assembly variano a seconda che il contenitore BLOB disponga dell'accesso in lettura pubblico. Prima di tutto, verificare se il contenitore BLOB ha accesso in lettura pubblico seguendo questa procedura: Impostare il livello di accesso pubblico per il contenitore BLOB

Controllare il livello di accesso del contenitore

  1. Aprire Azure Storage Explorer. Nella finestra di Explorer espandere la sottoscrizione di Azure, se necessario.

  2. Espandere Archiviazione Account> {account-archiviazione}>Contenitori BLOB. Selezionare il contenitore BLOB.

  3. Scegliere Set Public Access Level (Imposta livello di accesso pubblico) dal menu di scelta rapida del contenitore BLOB.

Caricare in contenitori con accesso pubblico

  1. Caricare l'assembly nell'account di archiviazione. Nella finestra a destra selezionare Carica.

  2. Al termine del caricamento, selezionare l'assembly caricato. Sulla barra degli strumenti selezionare Copia URL in modo da copiare l'URL dell'assembly.

  3. Tornare al portale di Azure in cui è aperto il riquadro Aggiungi assembly. Immettere un nome per lo schema. Selezionare File di grandi dimensioni (maggiore di 2 MB).

    Verrà ora visualizzata la casella URI del contenuto, invece della casella Assembly.

  4. Nella casella URI del contenuto incollare l'URL dell'assembly. Terminare l'aggiunta dell'assembly.

    Al termine del caricamento dell'assembly, l'assembly viene visualizzato nell'elenco Assembly . Nel riquadro Panoramica dell'account di integrazione, in Artefatti, viene visualizzato anche l'assembly caricato.

Caricare in contenitori senza accesso pubblico

  1. Caricare l'assembly nell'account di archiviazione. Nella finestra a destra selezionare Carica.

  2. Al termine del caricamento, generare una firma di accesso condiviso per l'assembly. Scegliere Get Shared Access Signature (Ottieni firma di accesso condiviso).

  3. Nel riquadro Firma di accesso condiviso selezionare Generate container-level shared access signature URI (Genera l'URI di firma di accesso condiviso a livello di contenitore)>Crea. Dopo aver generato l'URL della firma di accesso condiviso, accanto alla casella URL selezionare Copia.

  4. Tornare al portale di Azure in cui è aperto il riquadro Aggiungi assembly. Immettere un nome per lo schema. Selezionare File di grandi dimensioni (maggiore di 2 MB).

    Verrà ora visualizzata la casella URI del contenuto, invece della casella Assembly.

  5. Nella casella URI contenuto incollare l'URI di firma di accesso condiviso generato in precedenza. Terminare l'aggiunta dell'assembly.

Al termine del caricamento dell'assembly, l'assembly viene visualizzato nell'elenco Assembly . Nella pagina Panoramica dell'account di integrazione, in Artefatti, viene visualizzato anche l'assembly caricato.

Aggiungere una mappa

  • Se si usa un flusso di lavoro a consumo, è necessario aggiungere la mappa a un account di integrazione collegato.

  • Se si usa un flusso di lavoro Standard, sono disponibili le opzioni seguenti:

    • Aggiungere la mappa a un account di integrazione collegato. È possibile condividere l'account di mapping e integrazione tra più risorse dell'app per la logica Standard e i relativi flussi di lavoro figlio.

    • Aggiungere la mappa direttamente alla risorsa dell'app per la logica. Tuttavia, è possibile condividere tale mappa solo tra flussi di lavoro figlio nella stessa risorsa dell'app per la logica.

Aggiungere il mapping all'account di integrazione

  1. Nella portale di Azure accedere con le credenziali dell'account Azure.

  2. Nella casella di ricerca portale di Azure immettere gli account di integrazione e selezionare Account di integrazione.

  3. Trovare e selezionare l'account di integrazione.

  4. Nel menu di spostamento dell'account di integrazione, in Impostazioni, selezionare Mappe.

  5. Sulla barra degli strumenti del riquadro Mappe selezionare Aggiungi.

Per i flussi di lavoro a consumo, in base alle dimensioni del file della mappa, seguire ora i passaggi per caricare una mappa con dimensioni massime di 2 MB o più di 2 MB.

Aggiungere mappe di dimensioni pari o inferiori a 2 MB

  1. Nel riquadro Aggiungi mappa immettere un nome univoco per la mappa.

  2. In Tipo mappa selezionare il tipo, ad esempio Liquid, XSLT, XSLT 2.0 o XSLT 3.0.

  3. Accanto alla casella Mappa selezionare l'icona della cartella. Selezionare la mappa da caricare.

    Se si lascia vuota la proprietà Name , il nome file della mappa viene visualizzato automaticamente in tale proprietà dopo aver selezionato il file di mappa.

  4. Al termine, seleziona OK.

    Al termine del caricamento del file, la mappa viene visualizzata nell'elenco Mappe. Nella pagina Panoramica dell'account di integrazione, in Artefatti, viene visualizzata anche la mappa caricata.

Aggiungere mappe di dimensioni superiori a 2 MB

Per aggiungere mappe più grandi per i flussi di lavoro a consumo, usare l'API REST App per la logica di Azure - Mappe.

Aggiungere il mapping alla risorsa dell'app per la logica Standard

I passaggi seguenti si applicano solo se si vuole aggiungere una mappa direttamente alla risorsa dell'app per la logica Standard. In caso contrario, aggiungere la mappa all'account di integrazione.

Azure portal

  1. Nel menu della risorsa dell'app per la logica, in Artefatti selezionare Mappe.

  2. Sulla barra degli strumenti del riquadro Mappe selezionare Aggiungi.

  3. Nel riquadro Aggiungi mappa immettere un nome univoco per la mappa e includere il nome dell'estensione xslt.

  4. Accanto alla casella Mappa selezionare l'icona della cartella. Selezionare la mappa da caricare.

  5. Al termine, seleziona OK.

    Al termine del caricamento del file, la mappa viene visualizzata nell'elenco Mappe. Nella pagina Panoramica dell'account di integrazione, in Artefatti, viene visualizzata anche la mappa caricata.

Visual Studio Code

  1. Nella struttura del progetto dell'app per la logica aprire la cartella Artifacts e quindi la cartella Mappe.

  2. Nella cartella Mappe aggiungere la mappa.

Modificare una mappa

Per aggiornare una mappa esistente, è necessario caricare un nuovo file di mappa contenente le modifiche desiderate. È tuttavia possibile scaricare prima la mappa esistente e poi modificarla.

  1. Nel portale di Azure aprire l'account di integrazione, se non è già aperto.

  2. Nel menu dell'account di integrazione, in Impostazioni, selezionare Mappe.

  3. Dopo aver aperto il riquadro Mappe, selezionare la mappa. Per scaricare e modificare prima la mappa, nella barra degli strumenti del riquadro Mappe selezionare Scarica e salvare la mappa.

  4. Quando si è pronti per caricare la mappa aggiornata, nel riquadro Mappe selezionare la mappa da aggiornare. Sulla barra degli strumenti del riquadro Mappe selezionare Aggiorna.

  5. Trovare e selezionare la mappa aggiornata che si vuole caricare.

    Al termine del caricamento del file, la mappa aggiornata viene visualizzata nell'elenco Mappe.

Eliminare una mappa

  1. Nel portale di Azure aprire l'account di integrazione, se non è già aperto.

  2. Nel menu dell'account di integrazione, in Impostazioni, selezionare Mappe.

  3. Dopo aver aperto il riquadro Mappe, selezionare la mappa e quindi selezionare Elimina.

  4. Per confermare che si vuole eliminare la mappa, selezionare Sì.

Passaggi successivi