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

适用于: 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 配置脚本活动

内联脚本

屏幕截图显示用于配置内联脚本的 UI。

日志记录

屏幕截图显示脚本日志记录设置的 UI。

日志记录选项:

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

注意

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

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