R 插件（预览版）

项目
10/29/2024

适用于：✅Azure 数据资源管理器✅Azure Monitor✅Microsoft 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`		提示，用于在多个群集节点上分布插件的执行。默认值为 `single`。 `single` 意味着脚本的单个实例将针对整个查询数据运行。 `per_node` 意味着如果在分发 R 块之前执行查询，则脚本的一个实例将在每个节点上针对其包含的数据运行。
external_artifacts	`dynamic`		名称和 URL 对的属性包，用于可从云存储访问的项目。它们可供脚本在运行时使用。如存储连接字符串所述，此属性包中引用的 URL 需要包含在群集的标注策略和公开可用的位置，或者包含必要的凭据。这些项目可供脚本从本地临时目录 `.\Temp` 使用。属性包中提供的名称用作本地文件名。请参阅示例。有关详细信息，请参阅安装 R 插件的包。

保留的 R 变量

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

df：输入表格数据（上述 T 的值），采用 R 数据帧形式。
kargs：script_parameters 参数的值，采用 R 字典形式。
result：R 脚本创建的 R 数据帧。此值将成为发送到插件后面的任何 Kusto 查询运算符的表格数据。

启用插件

此插件默认处于禁用状态。
在 Azure 门户中，可以在群集的“配置”选项卡中启用或禁用此插件。有关详细信息，请参阅管理 Azure 数据资源管理器群集中的语言扩展（预览版）

R 沙盒映像

R 沙盒映像基于 R 3.4.4 for Windows，并且包括来自 Anaconda's R Essentials 捆绑包的程序包。

示例

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 插件的包

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

先决条件

创建 blob 容器来承载包，最好与群集位于同一个位置。例如 https://artifactschinaeast2.blob.core.chinacloudapi.cn/r，假设群集位于中国东部 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 计算机。

验证使用的是否是适当的 R 版本 - 当前 R 沙盒版本为 3.4.4：
```
> R.Version()["version.string"]

$version.string
[1] "R version 3.4.4 (2018-03-15)"
```
如果需要，可以从此处下载它。
启动 x64 RGui
创建一个新的空文件夹，以在其中填充要安装的所有相关包。在此示例中，我们将安装 brglm2 包，因此创建“C：\brglm2”。
将新建的文件夹路径添加到 lib 路径：
```
> .libPaths("C://brglm2")
```

验证新文件夹现在是否是 .libPaths() 中的第一个路径：

> .libPaths()

[1] "C:/brglm2"    "C:/Program Files/R/R-3.4.4/library"

完成此设置后，我们安装的任何包都应添加到此新文件夹中。让我们安装请求的包及其依赖项：
```
> install.packages("brglm2")
```
如果弹出了问题“是否要从源安装需要编译的包?”，请回答“Y”。
验证是否已将新文件夹添加到“C:\brglm2”：
选择该文件夹中的所有项目并将它们压缩成 libs.zip 之类的文件（不要压缩父文件夹）。应获得如下所示的存档结构：

libs.zip：
- brglm2（文件夹）
- enrichwith（文件夹）
- numDeriv（文件夹）
将 libs.zip 上传到上面设置的 blob 容器
调用 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 后缀，以防止在对名称与存档名称相同的文件夹进行解压缩时发生冲突。

通过