Condividi tramite

Trasformare i dati usando l'attività Script in Azure Data Factory o Synapse Analytics

  • Articolo

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Suggerimento

Provare Data Factory in Microsoft Fabric, una soluzione di analisi completa per le aziende. Microsoft Fabric copre tutti gli elementi, dallo spostamento dei dati all'analisi scientifica dei dati, all'analisi in tempo reale, alla business intelligence e alla creazione di report. Scopri come avviare gratuitamente una nuova versione di valutazione .

Le attività di trasformazione dei dati vengono usate in una pipeline di Data Factory o Synapse per trasformare ed elaborare dati non elaborati in stime e informazioni dettagliate. L'attività Script è una delle attività di trasformazione supportate dalle pipeline. Questo articolo si basa sull'articolo trasformare i dati, che presenta una panoramica generale della trasformazione dei dati e delle attività di trasformazione supportate.

Usando l'attività script, è possibile eseguire operazioni comuni con DML (Data Manipulation Language) e DDL (Data Definition Language). Le istruzioni DML come IN edizione Standard RT, UPDATE, DELETE e edizione Standard LECT consentono agli utenti di inserire, modificare, eliminare e recuperare i dati nel database. Le istruzioni DDL come CREATE, ALTER e DROP consentono a un gestore di database di creare, modificare e rimuovere oggetti di database, ad esempio tabelle, indici e utenti.

È possibile usare l'attività Script per richiamare uno script SQL in uno degli archivi dati seguenti nell'organizzazione o in una macchina virtuale di Azure:

  • database SQL di Azure
  • Azure Synapse Analytics
  • Database di SQL Server. Se si usa SQL Server, è necessario installare Runtime di integrazione (self-hosted) nello stesso computer che ospita il database o in un computer separato che ha accesso al database. Runtime di integrazione (self-hosted) è un componente che connette in modo sicuro e gestito origini dati presenti in locale o in macchine virtuali di Azure ai servizi cloud. Per informazioni dettagliate, vedere l'articolo Runtime di integrazione self-hosted.
  • Oracle
  • Snowflake

Lo script può contenere una singola istruzione SQL o più istruzioni SQL eseguite in sequenza. È possibile utilizzare l'attività Script per gli scopi seguenti:

  • Troncare una tabella in preparazione per l'inserimento di dati.
  • Creare, modificare ed eliminare oggetti di database come tabelle e viste.
  • Ricreare tabelle dei fatti e delle dimensioni prima di caricarvi i dati.
  • Eseguire stored procedure. Se l'istruzione SQL richiama una stored procedure che restituisce risultati da una tabella temporanea, utilizzare l'opzione WITH RESULT SETS per definire metadati per il set di risultati.
  • Salvare il set di righe restituito da una query come output dell'attività per l'utilizzo downstream.

Dettagli sintassi

Di seguito è riportato il formato JSON per la definizione di un'attività script:

{ 
   "name": "<activity name>", 
   "type": "Script", 
   "linkedServiceName": { 
      "referenceName": "<name>", 
      "type": "LinkedServiceReference" 
    }, 
   "typeProperties": { 
      "scripts" : [ 
         { 
            "text": "<Script Block>", 
            "type": "<Query> or <NonQuery>", 
            "parameters":[ 
               { 
                  "name": "<name>", 
                  "value": "<value>", 
                  "type": "<type>", 
                  "direction": "<Input> or <Output> or <InputOutput>", 
                  "size": 256 
               }, 
               ... 
            ] 
         }, 
         ... 
      ],     
         ... 
         ] 
      }, 
      "scriptBlockExecutionTimeout": "<time>",  
      "logSettings": { 
         "logDestination": "<ActivityOutput> or <ExternalStore>", 
         "logLocationSettings":{ 
            "linkedServiceName":{ 
               "referenceName": "<name>", 
               "type": "<LinkedServiceReference>" 
            }, 
            "path": "<folder path>" 
         } 
      } 
    } 
}

La tabella seguente illustra queste proprietà JSON:

Nome proprietà Descrizione Obbligatoria
name Il nome dell'impegno. Sì
type Tipo dell'attività, impostato su "Script". Sì
typeProperties Specificare le proprietà per configurare l'attività script. Sì
linkedServiceName Database di destinazione in cui viene eseguito lo script. Deve essere un riferimento a un servizio collegato. Sì
scripts Matrice di oggetti da rappresentare lo script. No
scripts.text Testo normale di un blocco di query. No
scripts.type Tipo del blocco di query. Può essere Query o NonQuery. Impostazione predefinita: query. No
scripts.parameter Matrice di parametri dello script. No
scripts.parameter.name Nome del parametro. No
scripts.parameter.value Valore del parametro . No
scripts.parameter.type Tipo di dati del parametro. Il tipo è di tipo logico e segue il mapping dei tipi di ogni connettore. No
scripts.parameter.direction Direzione del parametro. Può essere Input, Output, InputOutput. Il valore viene ignorato se la direzione è Output. Il tipo ReturnValue non è supportato. Impostare il valore restituito di SP su un parametro di output per recuperarlo. No
scripts.parameter.size Dimensione massima del parametro. Si applica solo al parametro di direzione Output/InputOutput di tipo string/byte[]. No
scriptBlockExecutionTimeout Tempo di attesa per il completamento dell'operazione di esecuzione del blocco di script prima del timeout. No
log Impostazioni Impostazioni per archiviare i log di output. Se non specificato, il log di script è disabilitato. No
log Impostazioni.logDestination Destinazione dell'output del log. Può essere ActivityOutput o ExternalStore. Impostazione predefinita: ActivityOutput. No
log Impostazioni.logLocation Impostazioni Le impostazioni del percorso di destinazione se logDestination è ExternalStore. No
logSettiongs.logLocation Impostazioni.linkedServiceName Servizio collegato della posizione di destinazione. È supportata solo l'archiviazione BLOB. No
log Impostazioni.logLocation Impostazioni.path Percorso della cartella in cui verranno archiviati i log. No

Activity Output

Output di esempio:

{ 
    "resultSetCount": 2, 
    "resultSets": [ 
        { 
            "rowCount": 10, 
            "rows":[ 
                { 
                    "<columnName1>": "<value1>", 
                    "<columnName2>": "<value2>", 
                    ... 
                } 
            ] 
        }, 
        ... 
    ], 
    "recordsAffected": 123, 
    "outputParameters":{ 
        "<parameterName1>": "<value1>", 
        "<parameterName2>": "<value2>" 
    }, 
    "outputLogs": "<logs>", 
    "outputLogsLocation": "<folder path>", 
    "outputTruncated": true, 
    ... 
}
Nome proprietà Descrizione Condizione
resultSetCount Conteggio dei set di risultati restituiti dallo script. Sempre
Gruppi Matrice che contiene tutti i set di risultati. Sempre
resultSets.rowCount Totale righe nel set di risultati. Sempre
resultSets.rows Matrice di righe nel set di risultati. Sempre
Recordsaffected Numero di righe interessate dallo script. Se scriptType è NonQuery.
outputParameters Parametri di output dello script. Se il tipo di parametro è Output o InputOutput.
outputLogs I log scritti dallo script, ad esempio, l'istruzione print. Se il connettore supporta l'istruzione log e enableScriptLogs è true e logLocation Impostazioni non viene fornito.
outputLogsPath Percorso completo del file di log. Se enableScriptLogs è true e viene fornito logLocation Impostazioni.
outputTruncated Indicatore che indica se l'output supera i limiti e viene troncato. Se l'output supera i limiti.

Nota

  • L'output viene raccolto ogni volta che viene eseguito un blocco di script. L'output finale è il risultato unito di tutti gli output dei blocchi di script. Il parametro di output con lo stesso nome in un blocco di script diverso verrà sovrascritto.
  • Poiché l'output presenta limitazioni di dimensioni/righe, l'output verrà troncato nell'ordine seguente: logs -> parameters -> rows. Si noti che si applica a un singolo blocco di script, il che significa che le righe di output del blocco di script successivo non rimuoveranno i log precedenti.
  • Qualsiasi errore causato dal log non riuscirà l'attività.
  • Per l'utilizzo dei set di risultati dell'output dell'attività di attività inattiva, vedere la documentazione sui risultati dell'attività di ricerca.
  • Usare outputLogs quando si usano istruzioni 'PRINT' a scopo di registrazione. Se la query restituisce resultSet, sarà disponibile nell'output dell'attività e sarà limitata a 5000 righe/ limite di 4 MB.

Configurare l'attività Script usando l'interfaccia utente

Script inline

Screenshot showing the UI to configure an inline script.

Gli script inline si integrano bene con CI/CD della pipeline perché lo script viene archiviato come parte dei metadati della pipeline.

Registrazione

Screenshot showing the UI for the logging settings for a script.

Opzioni di registrazione:

  • Disabilita : non viene registrato alcun output di esecuzione.
  • Output dell'attività: l'output dell'esecuzione dello script viene aggiunto all'output dell'attività. Può essere utilizzato dalle attività downstream. Le dimensioni di output sono limitate a 4 MB.
  • Archiviazione esterna: rende persistente l'output nell'archiviazione. Usare questa opzione se le dimensioni di output sono superiori a 2 MB o si vuole rendere persistente in modo esplicito l'output nell'account di archiviazione.

Nota

Fatturazione : l'attività Script verrà fatturata come attività della pipeline.

Contenuto correlato

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