Usare attività personalizzate in una pipeline di Azure Data Factory o Azure Synapse Analytics

Articolo
05/15/2024

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Suggerimento

Provare Data Factory in Microsoft Fabric, una soluzione di analisi all-in-one per le aziende. Microsoft Fabric copre tutto, dallo spostamento dati al data science, all'analisi in tempo reale, alla business intelligence e alla creazione di report. Vedere le informazioni su come iniziare una nuova prova gratuita!

Esistono due tipi di attività che è possibile usare in una pipeline di Azure Data Factory o Synapse.

Attività di spostamento dei dati per spostare dati tra archivi dati supportati di origine e sink.
Attività di trasformazione dei dati per trasformare i dati usando servizi di calcolo come Azure HDInsight e Azure Batch.

Per spostare i dati da e verso un archivio dati non supportato dal servizio o per trasformare/elaborare i dati in modo non supportato dal servizio, è possibile creare un'attività personalizzata con la propria logica di spostamento o trasformazione dei dati e usare l'attività in una pipeline. L'attività personalizzata esegue la logica del codice personalizzata in un pool di Azure Batch di macchine virtuali.

Nota

È consigliabile usare il modulo Azure Az PowerShell per interagire con Azure. Per iniziare, vedere Installare Azure PowerShell. Per informazioni su come eseguire la migrazione al modulo AZ PowerShell, vedere Eseguire la migrazione di Azure PowerShell da AzureRM ad Az.

Vedere gli articoli seguenti se non si ha familiarità con il servizio Azure Batch:

Nozioni di base di Azure Batch per una panoramica del servizio Azure Batch.
Cmdlet New-AzureBatchAccount per creare un account di Azure Batch oppure portale di Azure per creare l'account di Azure Batch usando il portale di Azure. Per istruzioni dettagliate sull'uso del cmdlet, vedere l'articolo Uso di Azure PowerShell per gestire l'account di Azure Batch.
Cmdlet New AzureBatchPool per creare un pool di Azure Batch.

Importante

Quando si crea un nuovo pool di Azure Batch, è necessario usare 'VirtualMachineConfiguration' e NON 'CloudServiceConfiguration'. Per altre informazioni, vedere Le indicazioni sulla migrazione del pool di Azure Batch.

Aggiungere attività personalizzate a una pipeline con l'interfaccia utente

Per usare un'attività personalizzata in una pipeline, completare la procedura seguente:

Cercare Personalizzato nel riquadro Attività pipeline e trascinare un'attività personalizzata nell'area di disegno della pipeline.
Selezionare la nuova attività Personalizzata nell'area di disegno, se non è già selezionata.
Selezionare la scheda Azure Batch per selezionare o creare un nuovo servizio collegato di Azure Batch che eseguirà l'attività personalizzata.
Selezionare la scheda Impostazioni e specificare un comando da eseguire in Azure Batch e i dettagli avanzati facoltativi.

Servizio collegato Azure Batch

Il codice JSON seguente definisce un servizio collegato Azure Batch di esempio. Per informazioni dettagliate, vedere Ambienti di calcolo supportati

{
    "name": "AzureBatchLinkedService",
    "properties": {
        "type": "AzureBatch",
        "typeProperties": {
            "accountName": "batchaccount",
            "accessKey": {
                "type": "SecureString",
                "value": "access key"
            },
            "batchUri": "https://batchaccount.region.batch.azure.com",
            "poolName": "poolname",
            "linkedServiceName": {
                "referenceName": "StorageLinkedService",
                "type": "LinkedServiceReference"
            }
        }
    }
}

Per altre informazioni sul servizio collegato Azure Batch, vedere l'articolo Servizi collegati di calcolo.

Impegno personalizzato

Il frammento di codice JSON seguente definisce una pipeline con una semplice attività personalizzata. La definizione dell'attività contiene un riferimento al servizio collegato Azure Batch.

{
  "name": "MyCustomActivityPipeline",
  "properties": {
    "description": "Custom activity sample",
    "activities": [{
      "type": "Custom",
      "name": "MyCustomActivity",
      "linkedServiceName": {
        "referenceName": "AzureBatchLinkedService",
        "type": "LinkedServiceReference"
      },
      "typeProperties": {
        "command": "helloworld.exe",
        "folderPath": "customactv2/helloworld",
        "resourceLinkedService": {
          "referenceName": "StorageLinkedService",
          "type": "LinkedServiceReference"
        }
      }
    }]
  }
}

In questo esempio, helloworld.exe è un'applicazione personalizzata salvata nella cartella customactv2/helloworld dell'account di Archiviazione di Azure usato in resourceLinkedService. L'attività personalizzata invia l'applicazione personalizzata per l'esecuzione in Azure Batch. Nel comando è possibile sostituire l'applicazione con qualsiasi altra applicazione che possa essere eseguita nel sistema operativo di destinazione dei nodi del pool di Azure Batch.

Nella tabella seguente vengono descritti i nomi e le descrizioni delle proprietà specifiche per questa attività.

Proprietà	Descrizione	Richiesto
name	Nome dell'attività nella pipeline	Sì
description	Testo che descrive l'attività.	No
type	Per l'attività personalizzata, il tipo corrisponde a Custom.	Sì
linkedServiceName	Servizio collegato ad Azure Batch. Per informazioni su questo servizio collegato, vedere l'articolo Servizi collegati di calcolo.	Sì
Comando	Comando dell'applicazione personalizzata da eseguire. Se l'applicazione è già disponibile nel nodo del pool di Azure Batch, è possibile ignorare resourceLinkedService e folderPath. È ad esempio possibile specificare come comando `cmd /c dir`, supportato in modo nativo dal nodo del pool di batch di Windows.	Sì
resourceLinkedService	Servizio di Archiviazione di Azure collegato all'account di archiviazione in cui è archiviata l'applicazione personalizzata	No *
folderPath	Percorso della cartella dell'applicazione personalizzata e di tutte le relative dipendenze Se sono presenti dipendenze archiviate nelle sottocartelle, vale a dire, in una struttura di cartelle gerarchiche in folderPath, la struttura di cartelle è attualmente di tipo flat quando i file vengono copiati in Azure Batch. Vale a dire, tutti i file vengono copiati in un'unica cartella senza sottocartelle. Per risolvere questo comportamento, è possibile comprimere i file, copiare il file compresso e quindi decomprimerlo con codice personalizzato nel percorso desiderato.	No *
referenceObjects	Matrice di servizi collegati e set di dati esistenti. I servizi collegati e i set di dati a cui si fa riferimento vengono passati all'applicazione personalizzata in formato JSON, in modo che il codice personalizzato possa fare riferimento alle risorse del servizio	No
extendedProperties	Proprietà definite dall'utente che possono essere passate all'applicazione personalizzata in formato JSON. Il codice personalizzato può quindi fare riferimento a proprietà aggiuntive	No
retentionTimeInDays	Tempo di conservazione per i file inviati per l'attività personalizzata. Il valore predefinito è 30 giorni.	No

* Le proprietà resourceLinkedService e folderPath devono essere specificate o entrambe o entrambe omesse.

Nota

Se si passano servizi collegati come referenceObjects nell'attività personalizzata, è consigliabile passare un servizio collegato abilitato per Azure Key Vault (poiché non contiene stringhe sicure) e recuperare le credenziali usando il nome segreto direttamente da Key Vault dal codice. È possibile trovare un esempio qui che fa riferimento al servizio collegato abilitato per AKV, recupera le credenziali da Key Vault e quindi accede all'archiviazione nel codice.

Nota

Attualmente solo l'archiviazione BLOB di Azure è supportata per resourceLinkedService nell'attività personalizzata ed è l'unico servizio collegato che viene creato per impostazione predefinita e non è possibile scegliere altri connettori come ADLS Gen2.

Autorizzazioni per le attività personalizzate

L'attività personalizzata imposta l'account utente automatico di Azure Batch sull'accesso senza privilegi di amministratore con ambito di attività (specifica di utente automatico predefinito). Non è possibile modificare il livello di autorizzazione dell'account utente automatico. Per altre informazioni, vedere Eseguire attività con account utente in Batch | Account utente automatici.

Esecuzione di comandi

È possibile eseguire direttamente un comando tramite l'attività personalizzata. L'esempio seguente esegue un comando "echo hello world" nei nodi del pool di destinazione di Azure Batch e stampa l'output in stdout.

{
  "name": "MyCustomActivity",
  "properties": {
    "description": "Custom activity sample",
    "activities": [{
      "type": "Custom",
      "name": "MyCustomActivity",
      "linkedServiceName": {
        "referenceName": "AzureBatchLinkedService",
        "type": "LinkedServiceReference"
      },
      "typeProperties": {
        "command": "cmd /c echo hello world"
      }
    }]
  }
}

Passaggio di oggetti e proprietà

Questo esempio illustra come usare referenceObjects e extendedProperties per passare oggetti e proprietà definite dall'utente dal servizio all'applicazione personalizzata.

{
  "name": "MyCustomActivityPipeline",
  "properties": {
    "description": "Custom activity sample",
    "activities": [{
      "type": "Custom",
      "name": "MyCustomActivity",
      "linkedServiceName": {
        "referenceName": "AzureBatchLinkedService",
        "type": "LinkedServiceReference"
      },
      "typeProperties": {
        "command": "SampleApp.exe",
        "folderPath": "customactv2/SampleApp",
        "resourceLinkedService": {
          "referenceName": "StorageLinkedService",
          "type": "LinkedServiceReference"
        },
        "referenceObjects": {
          "linkedServices": [{
            "referenceName": "AzureBatchLinkedService",
            "type": "LinkedServiceReference"
          }]
        },
        "extendedProperties": {          
          "connectionString": {
            "type": "SecureString",
            "value": "aSampleSecureString"
          },
          "PropertyBagPropertyName1": "PropertyBagValue1",
          "propertyBagPropertyName2": "PropertyBagValue2",
          "dateTime1": "2015-04-12T12:13:14Z"
        }
      }
    }]
  }
}

Quando l'attività viene eseguita, le proprietà referenceObjects ed extendedProperties vengono archiviate nei file descritti di seguito, che vengono distribuiti nella stessa cartella di esecuzione di SampleApp.exe:

activity.json

Contiene extendedProperties e le proprietà dell'attività personalizzata.
linkedServices.json

Contiene una matrice di servizi collegati definiti nella proprietà referenceObjects.
datasets.json

Contiene una matrice di set di dati definiti nella proprietà referenceObjects.

Il codice di esempio seguente illustra come SampleApp.exe è in grado di accedere alle informazioni necessarie dai file JSON:

using Newtonsoft.Json;
using System;
using System.IO;

namespace SampleApp
{
    class Program
    {
        static void Main(string[] args)
        {
            //From Extend Properties
            dynamic activity = JsonConvert.DeserializeObject(File.ReadAllText("activity.json"));
            Console.WriteLine(activity.typeProperties.extendedProperties.connectionString.value);

            // From LinkedServices
            dynamic linkedServices = JsonConvert.DeserializeObject(File.ReadAllText("linkedServices.json"));
            Console.WriteLine(linkedServices[0].properties.typeProperties.accountName);
        }
    }
}

Recuperare gli output di esecuzione

Per avviare una pipeline, eseguire il comando di PowerShell seguente:

$runId = Invoke-AzDataFactoryV2Pipeline -DataFactoryName $dataFactoryName -ResourceGroupName $resourceGroupName -PipelineName $pipelineName

Quando la pipeline è in esecuzione, è possibile controllare l'output dell'esecuzione usando i comandi seguenti:

while ($True) {
    $result = Get-AzDataFactoryV2ActivityRun -DataFactoryName $dataFactoryName -ResourceGroupName $resourceGroupName -PipelineRunId $runId -RunStartedAfter (Get-Date).AddMinutes(-30) -RunStartedBefore (Get-Date).AddMinutes(30)

    if(!$result) {
        Write-Host "Waiting for pipeline to start..." -foregroundcolor "Yellow"
    }
    elseif (($result | Where-Object { $_.Status -eq "InProgress" } | Measure-Object).count -ne 0) {
        Write-Host "Pipeline run status: In Progress" -foregroundcolor "Yellow"
    }
    else {
        Write-Host "Pipeline '"$pipelineName"' run finished. Result:" -foregroundcolor "Yellow"
        $result
        break
    }
    ($result | Format-List | Out-String)
    Start-Sleep -Seconds 15
}

Write-Host "Activity `Output` section:" -foregroundcolor "Yellow"
$result.Output -join "`r`n"

Write-Host "Activity `Error` section:" -foregroundcolor "Yellow"
$result.Error -join "`r`n"

stdout e stderr dell'applicazione personalizzata vengono salvati nel contenitore adfjobs nel servizio collegato di Archiviazione di Azure definito durante la creazione del servizio collegato Azure Batch con un GUID dell'attività. È possibile ottenere il percorso dettagliato dall'output di Esecuzione attività, come illustrato nel frammento di codice seguente:

Pipeline ' MyCustomActivity' run finished. Result:

ResourceGroupName : resourcegroupname
DataFactoryName   : datafactoryname
ActivityName      : MyCustomActivity
PipelineRunId     : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
PipelineName      : MyCustomActivity
Input             : {command}
Output            : {exitcode, outputs, effectiveIntegrationRuntime}
LinkedServiceName :
ActivityRunStart  : 10/5/2017 3:33:06 PM
ActivityRunEnd    : 10/5/2017 3:33:28 PM
DurationInMs      : 21203
Status            : Succeeded
Error             : {errorCode, message, failureType, target}

Activity Output section:
"exitcode": 0
"outputs": [
  "https://<container>.blob.core.windows.net/adfjobs/<GUID>/output/stdout.txt",
  "https://<container>.blob.core.windows.net/adfjobs/<GUID>/output/stderr.txt"
]
"effectiveIntegrationRuntime": "DefaultIntegrationRuntime (East US)"
Activity Error section:
"errorCode": ""
"message": ""
"failureType": ""
"target": "MyCustomActivity"

Se si desidera utilizzare il contenuto di stdout.txt nelle attività downstream, è possibile ottenere il percorso del file stdout.txt nell'espressione "@activity('MyCustomActivity').outputs[0]".

Importante

Activity.json, linkedServices.json e datasets.json vengono archiviati nella cartella di runtime dell'attività Batch. Per questo esempio, le activity.json, le linkedServices.json e le datasets.json vengono archiviate nel https://adfv2storage.blob.core.windows.net/adfjobs/<GUID>/runtime/ percorso. Se necessario, la pulizia di questi file deve essere eseguita separatamente.
Per i servizi collegati che usano il runtime di integrazione self-hosted, le informazioni riservate, come chiavi o password, vengono crittografate dal runtime di integrazione self-hosted per verificare che le credenziali rimangano nell'ambiente di rete privata definito dal cliente. Alcuni campi riservati potrebbero risultare mancanti se il codice dell'applicazione personalizzata fa riferimento a tali campi in questo modo. Se necessario, usare SecureString in extendedProperties anziché un riferimento a servizi collegati.

Passare gli output a un'altra attività

È possibile inviare valori personalizzati dal codice in un'attività personalizzata al servizio. È possibile farlo scrivendoli in outputs.json dall'applicazione. Il servizio copia il contenuto di outputs.json e lo aggiunge all'output dell'attività come valore della customOutput proprietà . Il limite di dimensioni è 2 MB. Se si desidera utilizzare il contenuto di outputs.json nelle attività downstream, è possibile ottenere il valore usando l'espressione @activity('<MyCustomActivity>').output.customOutput.

Recuperare gli output SecureString

I valori delle proprietà sensibili designati come tipo SecureString, come illustrato in alcuni esempi di questo articolo, vengono mascherati nella scheda Monitoraggio nell'interfaccia utente. Nell'esecuzione effettiva della pipeline, tuttavia, una proprietà SecureString viene serializzata come JSON all'interno del activity.json file come testo normale. Ad esempio:

"extendedProperties": {
  "connectionString": {
    "type": "SecureString",
    "value": "aSampleSecureString"
  }
}

Questa serializzazione non è propriamente sicura e non è progettata per esserlo. La finalità è un hint per il servizio per mascherare il valore nella scheda Monitoraggio.

Per accedere alle proprietà di tipo SecureString da un'attività personalizzata, leggere il activity.json file, che viene inserito nella stessa cartella del .EXE, deserializzare il codice JSON e quindi accedere alla proprietà JSON (extendedProperties => [propertyName] => value).

Scalabilità automatica di Azure Batch

È anche possibile creare un pool di Azure Batch con la funzionalità Scalabilità automatica . Ad esempio, è possibile creare un pool di Batch di Azure con 0 macchine virtuali dedicate e una formula di scalabilità automatica in base al numero di attività in sospeso.

La formula di esempio seguente consente di ottenere il comportamento seguente: quando il pool viene creato inizialmente, inizia con 1 macchina virtuale. La metrica $PendingTasks definisce il numero di attività in esecuzione e quelle in coda. La formula trova il numero medio di attività in sospeso negli ultimi 180 secondi e imposta TargetDedicated di conseguenza. Assicura che TargetDedicated non vada mai oltre 25 macchine virtuali. Pertanto, quando vengono inviate nuove attività, il pool si espande automaticamente e al completamento delle attività le macchine virtuali diventano disponibili una alla volta e la scalabilità automatica le riduce. È possibile regolare startingNumberOfVMs e maxNumberofVMs in base alle esigenze.

Formula di scalabilità automatica:

startingNumberOfVMs = 1;
maxNumberofVMs = 25;
pendingTaskSamplePercent = $PendingTasks.GetSamplePercent(180 * TimeInterval_Second);
pendingTaskSamples = pendingTaskSamplePercent < 70 ? startingNumberOfVMs : avg($PendingTasks.GetSample(180 * TimeInterval_Second));
$TargetDedicated=min(maxNumberofVMs,pendingTaskSamples);

Per i dettagli, vedere Ridimensionare automaticamente i nodi di calcolo in un pool di Azure Batch .

Se il pool usa il valore predefinito autoScaleEvaluationInterval, possono essere necessari 15-30 minuti perché il servizio Batch prepari la VM prima di eseguire l'attività personalizzata. Se il pool usa un valore autoScaleEvaluationInterval diverso, il servizio Batch può richiedere un valore autoScaleEvaluationInterval + 10 minuti.

Vedere gli articoli seguenti, che illustrano altre modalità di trasformazione dei dati:

Condividi tramite

Usare attività personalizzate in una pipeline di Azure Data Factory o Azure Synapse Analytics

Aggiungere attività personalizzate a una pipeline con l'interfaccia utente

Servizio collegato Azure Batch

Impegno personalizzato

Autorizzazioni per le attività personalizzate

Esecuzione di comandi

Passaggio di oggetti e proprietà

Recuperare gli output di esecuzione

Passare gli output a un'altra attività

Recuperare gli output SecureString

Scalabilità automatica di Azure Batch

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Usare attività personalizzate in una pipeline di Azure Data Factory o Azure Synapse Analytics

Aggiungere attività personalizzate a una pipeline con l'interfaccia utente

Servizio collegato Azure Batch

Impegno personalizzato

Autorizzazioni per le attività personalizzate

Esecuzione di comandi

Passaggio di oggetti e proprietà

Recuperare gli output di esecuzione

Passare gli output a un'altra attività

Recuperare gli output SecureString

Scalabilità automatica di Azure Batch

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive