Trasformare i dati usando l'attività Script in Azure Data Factory o Synapse Analytics
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!
Le attività di trasformazione dei dati in una pipeline di Data Factory o Synapse trasformano ed elaborano i dati non elaborati in stime e approfondimenti. L'attività Script è una delle attività di trasformazione supportate dalle pipeline. Questo articolo si basa sull'articolo relativo alla trasformazione dei dati, che offre 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 INSERT, UPDATE, DELETE e SELECT consentono agli utenti di inserire, modificare, eliminare e recuperare 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 dei seguenti archivi dati presenti in azienda 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 i dettagli, vedere l'articolo Runtime di integrazione self-hosted.
- Oracle
- Snowflake
Lo script può includere una o più istruzioni SQL che vengono eseguite in ordine sequenziale. È possibile utilizzare l'attività Script per gli scopi seguenti:
- Troncare una tabella per prepararla 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à di 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 | Richiesto |
|---|---|---|
| name | Il nome dell'impegno. | Sì |
| type | Il 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 per 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 | La 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 | Il tempo di attesa per il completamento dell'operazione di esecuzione del blocco di script prima del timeout. | No |
| logSettings | Impostazioni per archiviare i log di output. Se non specificato, il log di script è disabilitato. | No |
| logSettings.logDestination | Destinazione dell'output del log. Può essere ActivityOutput o ExternalStore. Impostazione predefinita: ActivityOutput. | No |
| logSettings.logLocationSettings | Le impostazioni del percorso di destinazione se logDestination è ExternalStore. | No |
| logSettiongs.logLocationSettings.linkedServiceName | Servizio collegato della posizione di destinazione. È supportata solo l'archiviazione BLOB. | No |
| logSettings.logLocationSettings.path | Percorso della cartella in cui archiviare 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 |
| resultSets | 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, enableScriptLogs è true e logLocationSettings non viene fornito. |
| outputLogsPath | Il percorso completo del file di log. | Se enableScriptLogs è true e logLocationSettings viene fornito. |
| outputTruncated | Indicatore che specifica 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: log -> parametri -> righe. Si noti che ciò 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 comporterà errori nell'attività.
- Per l'utilizzo di resultSets dell'output dell'attività nell'attività downstream, 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
Gli script inline si integrano bene con CI/CD della pipeline perché lo script viene archiviato come parte dei metadati della pipeline.
Registrazione
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à. Le attività downstream possono quindi utilizzarlo. Le dimensioni di output sono limitate a 4 MB.
- Archiviazione esterna: rende persistente l'output nell'archiviazione. Usare questa opzione se le dimensioni dell'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: