共用方式為

R 外掛程式 （預覽）

  • 發行項

適用於：✅Microsoft網狀架構✅Azure 數據✅總管 Azure 監視器✅Microsoft Sentinel

R 外掛程式會使用 R 文稿執行使用者定義函式 （UDF）。

文本會取得表格式數據做為其輸入，併產生表格式輸出。 外掛程式的運行時間裝載於 叢集節點上的沙箱 中。 沙箱提供隔離且安全的環境。

語法

T | evaluate [ （single | per_node）] r(output_schema,腳本 [hint.distribution =, 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 要傳遞至 R 文稿做為保留 kargs 字典的名稱和值組屬性包。 如需詳細資訊，請參閱 保留的 R 變數。
hint.distribution string 外掛程式執行要分散到多個叢集節點的提示。 預設值是 single。 single 表示文本的單一實例將會在整個查詢數據上執行。 per_node 表示如果在 R 區塊散發前的查詢，腳本的實例將會在每個節點上透過它所包含的數據執行。
external_artifacts dynamic 可從雲端記憶體存取之成品的名稱和URL組屬性包。 腳本可在運行時間使用它們。 這個屬性包中參考的 URL 必須包含在叢集的圖說文字原則和公開可用位置，或包含必要的認證，如記憶體 連接字串 中所述。 成品可供文稿從本機暫存目錄取用。 .\Temp 屬性包中提供的名稱會當做本機檔名使用。 請參閱範例 (部分機器翻譯)。 如需詳細資訊，請參閱 安裝 R 外掛程式的套件。

保留的 R 變數

下列變數會保留給 Kusto 查詢語言 與 R 程式代碼之間的互動：

  • df：輸入表格式數據（上述的值 T ），做為 R DataFrame。
  • kargs：script_parameters自變數的值，做為 R 字典。
  • result：R 文稿所建立的 R 數據框架。 值會變成表格式數據，該數據會傳送至外掛程式之後的任何 Kusto 查詢運算元。

啟用外掛程式

R 沙箱映像

  • R 沙箱映像是以 R 3.4.4 for Windows 為基礎，並包含 Anaconda 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 字串常值使用雙引號字元 （"）。

  • 使用外部數據運算符來取得您已儲存在外部位置的腳本內容，例如 Azure Blob 記憶體或公用 GitHub 存放庫。

    例如：

    let script = 
    externaldata(script:string)
    [h'https://kustoscriptsamples.blob.core.windows.net/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://artifactswestus.blob.core.windows.net/r假設您的叢集位於美國西部。

  2. 改變叢集的 註標原則 ，以允許存取該位置。

    • 這項變更需要 AllDatabasesAdmin 許可權。

    • 例如，若要啟用中 https://artifactswestus.blob.core.windows.net/rBlob 的存取權，請執行下列命令：

    .alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/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呼叫外掛程式。

    • external_artifacts使用名稱的屬性包和 ZIP 檔案的參考來指定 參數（Blob 的 URL，包括 SAS 令牌）。
    • 在您的內嵌 r 程式代碼中，從 zipfile sandboxutils 匯入 ，並使用 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://artifactswestus.blob.core.windows.net/r/libs.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))
x ver
1 1.8.2

請確定封存的名稱（套件組的第一個值）具有 *.zip 後綴，以避免在解壓縮名稱與封存名稱相同的資料夾時發生衝突。