R 插件(预览版)

适用于:✅Azure 数据资源管理器Azure MonitorMicrosoft Sentinel

R 插件使用 R 脚本运行用户定义的函数 (UDF)。

此脚本获取表格数据作为其输入,并生成表格输出。 插件的运行时承载在群集节点上的沙盒中。 沙盒提供隔离的安全环境。

语法

T | evaluate [hint.distribution = (single | per_node)] r(output_schema, script [, script_parameters] [, external_artifacts])

详细了解语法约定

参数

客户 类型​​ 必需 说明
output_schema string ✔️ type 文本,定义由 R 代码返回的表格数据的输出架构。 格式为:typeof(ColumnName: ColumnType[, ...])。例如:typeof(col1:string, col2:long)。 若要扩展输入架构,请使用以下语法:typeof(*, col1:string, col2:long)
脚本 string ✔️ 要执行的有效 R 脚本。
script_parameters dynamic 要作为保留的 kargs 字典传递给 R 脚本的名称和值对的属性包。 有关详细信息,请参阅保留的 R 变量
hint.distribution string 提示,用于在多个群集节点上分布插件的执行。 默认值为 singlesingle 意味着脚本的单个实例将针对整个查询数据运行。 per_node 意味着如果在分发 R 块之前执行查询,则脚本的一个实例将在每个节点上针对其包含的数据运行。
external_artifacts dynamic 名称和 URL 对的属性包,用于可从云存储访问的项目。 它们可供脚本在运行时使用。 如存储连接字符串所述,此属性包中引用的 URL 需要包含在群集的标注策略和公开可用的位置,或者包含必要的凭据。 这些项目可供脚本从本地临时目录 .\Temp 使用。 属性包中提供的名称用作本地文件名。 请参阅示例。 有关详细信息,请参阅安装 R 插件的包

保留的 R 变量

以下变量保留用于在 Kusto 查询语言与 R 代码之间进行交互:

  • df:输入表格数据(上述 T 的值),采用 R 数据帧形式。
  • kargsscript_parameters 参数的值,采用 R 字典形式。
  • result:R 脚本创建的 R 数据帧。 此值将成为发送到插件后面的任何 Kusto 查询运算符的表格数据。

启用插件

R 沙盒映像

示例

range x from 1 to 360 step 1
| evaluate r(
//
typeof(*, fx:double),               //  Output schema: append a new fx column to original table 
//
'result <- df\n'                    //  The R decorated script
'n <- nrow(df)\n'
'g <- kargs$gain\n'
'f <- kargs$cycles\n'
'result$fx <- g * sin(df$x / n * 2 * pi * f)'
//
, bag_pack('gain', 100, 'cycles', 4)    //  dictionary of parameters
)
| render linechart 

正弦演示。

性能提示

  • 将插件的输入数据集减少到所需的最小量(列/行)。

  • 请尽可能通过 Kusto 查询语言对源数据集使用筛选器。

  • 若要对源列的子集进行计算,请在调用插件之前仅投影这些列。

  • 如果脚本中的逻辑可分发,请使用 hint.distribution = per_node

  • 还可以使用分区运算符对输入数据集进行分区。

  • 请尽可能使用 Kusto 查询语言来实现 R 脚本的逻辑。

    例如:

    .show operations
    | where StartedOn > ago(1d) // Filtering out irrelevant records before invoking the plugin
    | project d_seconds = Duration / 1s // Projecting only a subset of the necessary columns
    | evaluate hint.distribution = per_node r( // Using per_node distribution, as the script's logic allows it
        typeof(*, d2:double),
        'result <- df\n'
        'result$d2 <- df$d_seconds\n' // Negative example: this logic should have been written using Kusto's query language
      )
    | summarize avg = avg(d2)
    

使用提示

  • 若要避免 Kusto 字符串分隔符与 R 字符串分隔符之间的冲突,请使用以下方法:

    • 为 Kusto 查询中的 Kusto 字符串文本使用单引号字符 (')。
    • 为 R 脚本中的 R 字符串文本使用双引号字符 (")。
  • 使用 externaldata 运算符获取存储在外部位置(例如 Azure Blob 存储或公共 GitHub 存储库)中的脚本内容。

    例如:

    let script = 
        externaldata(script:string)
        [h'https://kustoscriptsamples.blob.core.chinacloudapi.cn/samples/R/sample_script.r']
        with(format = raw);
    range x from 1 to 360 step 1
    | evaluate r(
        typeof(*, fx:double),
        toscalar(script), 
        bag_pack('gain', 100, 'cycles', 4))
    | render linechart 
    

安装 R 插件的包

按照以下这些分步说明,安装插件基础映像中未包含的软件包。

先决条件

  1. 创建 blob 容器来承载包,最好与群集位于同一个位置。 例如 https://artifactschinaeast2.blob.core.chinacloudapi.cn/r,假设群集位于中国东部 2。

  2. 更改群集的标注策略以允许访问该位置。

    • 此更改需要 AllDatabasesAdmin 权限。

    • 例如,若要启用对位于 https://artifactschinaeast2.blob.core.chinacloudapi.cn/r 中的 blob 的访问,请运行以下命令:

    .alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactschinaeast2\\.blob\\.core\\.chinacloudapi\\.cn/r/","CanCall": true } ]'
    

安装包

下面的示例片段假定有一个处于 Windows 环境中的本地 R 计算机。

  1. 验证使用的是否是适当的 R 版本 - 当前 R 沙盒版本为 3.4.4:

    > R.Version()["version.string"]
    
    $version.string
    [1] "R version 3.4.4 (2018-03-15)"
    

    如果需要,可以从此处下载它。

  2. 启动 x64 RGui

  3. 创建一个新的空文件夹,以在其中填充要安装的所有相关包。 在此示例中,我们将安装 brglm2 包,因此创建“C:\brglm2”。

  4. 将新建的文件夹路径添加到 lib 路径:

    > .libPaths("C://brglm2")
    
  5. 验证新文件夹现在是否是 .libPaths() 中的第一个路径:

    > .libPaths()
    
    [1] "C:/brglm2"    "C:/Program Files/R/R-3.4.4/library"
    
    
  6. 完成此设置后,我们安装的任何包都应添加到此新文件夹中。 让我们安装请求的包及其依赖项:

    > install.packages("brglm2")
    

    如果弹出了问题“是否要从源安装需要编译的包?”,请回答“Y”。

  7. 验证是否已将新文件夹添加到“C:\brglm2”:

    库目录内容的屏幕截图。

  8. 选择该文件夹中的所有项目并将它们压缩成 libs.zip 之类的文件(不要压缩父文件夹)。 应获得如下所示的存档结构:

    libs.zip:

    • brglm2(文件夹)
    • enrichwith(文件夹)
    • numDeriv(文件夹)
  9. 将 libs.zip 上传到上面设置的 blob 容器

  10. 调用 r 插件。

    • 使用一个包含名称和对 zip 文件(blob 的 URL,包括一个 SAS 令牌)的引用的属性包指定 external_artifacts 参数。
    • 在内联 r 代码中,从 sandboxutils 导入 zipfile 并使用 zip 文件的名称调用其 install() 方法。

示例

安装 brglm2 包

print x=1
| evaluate r(typeof(*, ver:string),
    'library(sandboxutils)\n'
    'zipfile.install("brglm2.zip")\n'
    'library("brglm2")\n'
    'result <- df\n'
    'result$ver <-packageVersion("brglm2")\n'
    ,external_artifacts=bag_pack(brglm2.zip', 'https://artifactschinaeast2.blob.core.chinacloudapi.cn/r/libs.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))
x ver
1 1.8.2

请确保存档的名称(包对中的第一个值)具有 *.zip 后缀,以防止在对名称与存档名称相同的文件夹进行解压缩时发生冲突。