在 Azure 数据工厂或 Synapse Analytics 中使用脚本活动转换数据

项目
02/23/2024

适用于： Azure 数据工厂 Azure Synapse Analytics

提示

试用 Microsoft Fabric 中的数据工厂，这是一种适用于企业的一站式分析解决方案。 Microsoft Fabric 涵盖从数据移动到数据科学、实时分析、商业智能和报告的所有内容。了解如何免费开始新的试用！

可使用数据工厂或 Synapse Analytics 管道中的数据转换活动将原始数据转换和处理为预测和见解。脚本活动是管道支持的转换活动之一。本文基于转换数据一文编写，它概述了数据转换和受支持的转换活动。

通过脚本活动，可使用数据操作语言 (DML) 和数据定义语言 (DDL) 执行常见操作。 DML 语句（如 INSERT、UPDATE、DELETE 和 SELECT）允许用户在数据库中插入、修改、删除和检索数据。数据库管理员可使用 CREATE、ALTER 和 DROP 等 DDL 语句创建、修改和删除数据库对象，例如表、索引和用户。

可使用脚本活动在企业或 Azure 虚拟机 (VM) 的以下数据存储之一中调用 SQL 脚本：

Azure SQL 数据库
Azure Synapse Analytics
SQL Server 数据库。如果使用 SQL Server，请在托管数据库的同一计算机上或在可以访问数据库的单独计算机上安装自托管集成运行时。自托管集成运行时是一种以安全托管方式将本地/Azure VM 上的数据源与云服务进行连接的组件。有关详细信息，请参阅自承载集成运行时一文。
Oracle
Snowflake

此脚本可以包含单个 SQL 语句，也可以包含按顺序运行的多个 SQL 语句。可以将脚本任务用于下列目的：

截断表，以便为插入数据做准备。
创建、更改和删除数据库对象（如表和视图）。
在向事实数据表和维度表加载数据之前，重新创建这些表。
运行存储过程。如果 SQL 语句调用从临时表返回结果的某一存储过程，则使用 WITH RESULT SETS 选项可为结果集定义元数据。
将查询返回的行集另存为活动输出，以供下游使用。

语法详细信息

下面用于定义脚本活动的 JSON 格式：

{ 
   "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>" 
         } 
      } 
    } 
}

下表描述了其中的 JSON 属性：

属性名称	说明	必需
name	活动的名称。	是
type	活动的类型，设置为“脚本”。	是
typeProperties	指定用于配置脚本活动的属性。	是
linkedServiceName	运行脚本的目标数据库。它应该是对链接服务的引用。	是
脚本	用于表示脚本的对象数组。	否
scripts.text	查询块的纯文本。	否
scripts.type	查询块的类型。它可以是 Query，也可以是 NonQuery。默认值：Query。	否
scripts.parameter	脚本的参数数组。	否
scripts.parameter.name	参数的名称。	否
scripts.parameter.value	参数值。	否
scripts.parameter.type	参数的数据类型。该类型为逻辑类型，并遵循每个连接器的类型映射。	否
scripts.parameter.direction	参数的方向。它可以是输入、输出、InputOutput。如果方向为输出，则忽略该值。不支持 ReturnValue 类型。将 SP 的返回值设置为输出参数以检索它。	否
scripts.parameter.size	参数的最大大小。仅适用于 string/byte[] 类型的 Output/InputOutput 方向参数。	否
scriptBlockExecutionTimeout	在超时之前完成脚本块执行操作的等待时间。	否
logSettings	用于存储输出日志的设置。如果未指定此项，则禁用脚本日志。	否
logSettings.logDestination	日志输出的目标。它可以是 ActivityOutput，也可以是 ExternalStore。默认值：ActivityOutput。	否
logSettings.logLocationSettings	如果 logDestination 为 ExternalStore，则为目标位置的设置。	否
logSettiongs.logLocationSettings.linkedServiceName	目标位置的链接服务。仅支持 Blob 存储。	否
logSettings.logLocationSettings.path	用于存储日志的文件夹路径。	否

活动输出

示例输出：

{ 
    "resultSetCount": 2, 
    "resultSets": [ 
        { 
            "rowCount": 10, 
            "rows":[ 
                { 
                    "<columnName1>": "<value1>", 
                    "<columnName2>": "<value2>", 
                    ... 
                } 
            ] 
        }, 
        ... 
    ], 
    "recordsAffected": 123, 
    "outputParameters":{ 
        "<parameterName1>": "<value1>", 
        "<parameterName2>": "<value2>" 
    }, 
    "outputLogs": "<logs>", 
    "outputLogsLocation": "<folder path>", 
    "outputTruncated": true, 
    ... 
}

属性名称	说明	条件
resultSetCount	脚本返回的结果集计数。	始终
resultSets	包含所有结果集的数组。	始终
resultSets.rowCount	结果集的总行数。	始终
resultSets.rows	结果集内行的数组。	始终
recordsAffected	受脚本影响的行的行计数。	如果 scriptType 为 NonQuery。
outputParameters	脚本的输出参数。	如果参数类型为 Output 或 InputOutput。
outputLogs	通过脚本编写的日志，例如 print 语句。	如果连接器支持 log 语句，enableScriptLogs 为 true，且未提供 logLocationSettings。
outputLogsPath	日志文件的完整路径。	如果 enableScriptLogs 为 true 并且提供了 logLocationSettings。
outputTruncated	指示输出是否超出限制并被截断。	如果输出超出限制。

注意

每次执行脚本块时都会收集输出。最终输出是所有脚本块输出的合并结果。不同脚本块中同名的输出参数将被覆盖。
由于输出具有大小/行限制，输出将按以下顺序截断：logs -> parameters -> rows。注意，这适用于单个脚本块，这意味着下一个脚本块的输出行不会逐出以前的日志。
任何由日志引起的错误都不会导致活动失败。
有关在下游活动中使用活动输出 resultSets 的信息，请参阅查找活动结果文档。
使用“PRINT”语句进行日志记录时，请使用 outputLogs。如果查询返回 resultSets，它将在活动输出中可用，并且仅限 5000 行/ 4MB 大小。

使用 UI 配置脚本活动

内联脚本

Screenshot showing the UI to configure an inline script.

日志记录

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

日志记录选项：

禁用 - 不记录任何执行输出。
活动输出 - 脚本执行输出将追加到活动输出。下游活动可以使用该输出。输出大小限制为 4 MB。
外部存储 - 将输出持久保存到存储。如果输出大小大于 2 MB，或者希望将输出显式持久保存到存储帐户，请使用此选项。

注意

计费 - 脚本活动将作为管道活动进行计费。

参阅以下文章了解如何以其他方式转换数据：