Modul plug-in R (Preview)

Článek
10/31/2024

Platí pro: ✅Microsoft Fabric✅Azure Data Explorer ✅Azure Monitor✅Microsoft Sentinel

Modul plug-in R spouští uživatelem definovanou funkci (UDF) pomocí skriptu jazyka R.

Skript získá tabulková data jako vstup a vytvoří tabulkový výstup. Modul runtime modulu plug-in je hostovaný v sandboxu na uzlech clusteru. Sandbox poskytuje izolované a zabezpečené prostředí.

Syntaxe

T | evaluate [hint.distribution = (singleper_node | )] r(output_schema, skript [, script_parameters] [, external_artifacts])

Přečtěte si další informace o konvencích syntaxe.

Parametry

Název	Type	Požadováno	Popis
output_schema	`string`	✔️	`type` Literál, který definuje výstupní schéma tabulkových dat vrácených kódem R. Formát je: `typeof(`ColumnName`:` ColumnType[, ...]`)`. Příklad: `typeof(col1:string, col2:long)`. Chcete-li rozšířit vstupní schéma, použijte následující syntaxi: `typeof(*, col1:string, col2:long)`.
skript	`string`	✔️	Platný skript jazyka R, který se má spustit.
script_parameters	`dynamic`		Sada vlastností párů názvů a hodnot, které se mají předat skriptu R jako vyhrazený `kargs` slovník. Další informace najdete v tématu Rezervované proměnné jazyka R.
`hint.distribution`	`string`		Tip pro spuštění modulu plug-in, který se má distribuovat napříč několika uzly clusteru. Výchozí hodnota je `single`. `single` znamená, že jedna instance skriptu se spustí přes celá data dotazu. `per_node` znamená, že pokud je dotaz před distribuovaným blokem R, instance skriptu se spustí na každém uzlu přes data, která obsahuje.
external_artifacts	`dynamic`		Sada vlastností párů názvů a adres URL pro artefakty, které jsou přístupné z cloudového úložiště. Dají se zpřístupnit pro skript, který se má použít za běhu. Adresy URL odkazované v tomto kontejneru vlastností musí být zahrnuty do zásad popisku clusteru a do veřejně dostupného umístění nebo obsahují nezbytné přihlašovací údaje, jak je vysvětleno v připojovací řetězec úložiště. Artefakty jsou zpřístupněny pro skript, který může využívat z místního dočasného adresáře . `.\Temp` Názvy zadané v kontejneru vlastností se používají jako názvy místních souborů. Viz příklad. Další informace naleznete v tématu Instalace balíčků pro modul plug-in R.

Rezervované proměnné R

Následující proměnné jsou vyhrazené pro interakci mezi dotazovací jazyk Kusto a kódem R:

df: Vstupní tabulková data (hodnoty T výše) jako datový rámec R.
kargs: Hodnota argumentu script_parameters jako slovník jazyka R.
result: Datový rámec jazyka R vytvořený skriptem jazyka R. Hodnota se stane tabulkovou datou, která se odešlou do libovolného operátoru dotazu Kusto, který následuje za modulem plug-in.

Povolení modulu plug-in

Modul plug-in je ve výchozím nastavení zakázaný.
Povolte nebo zakažte modul plug-in na webu Azure Portal na kartě Konfigurace vašeho clusteru. Další informace najdete v tématu Správa jazykových rozšíření v clusteru Azure Data Exploreru (Preview)

Image sandboxu R

Image sandboxu R je založená na R 3.4.4 pro Windows a obsahuje balíčky ze sady R Essentials od Anaconda.

Příklady

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

Sine demo.

Tipy týkající se výkonu

Snižte vstupní datovou sadu modulu plug-in na minimální požadované množství (sloupce nebo řádky).
Pokud je to možné, použijte filtry u zdrojové datové sady pomocí dotazovací jazyk Kusto.
Pokud chcete provést výpočet podmnožině zdrojových sloupců, projektujte před vyvoláním modulu plug-in pouze tyto sloupce.
Použijte hint.distribution = per_node pokaždé, když je logika ve vašem skriptu distribuovatelná.
Můžete také použít operátor oddílu pro dělení vstupních dat et.

Kdykoli je to možné, použijte dotazovací jazyk Kusto k implementaci logiky skriptu jazyka R.

Příklad:

.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)

Tipy k používání

Aby nedocházelo ke konfliktům mezi oddělovači řetězců Kusto a oddělovači řetězců R:
- V dotazech Kusto použijte jednoduché znaky uvozovek (') pro řetězcové literály Kusto.
- Pro řetězcové literály jazyka R ve skriptech jazyka R použijte dvojité uvozovky (").

Pomocí operátoru externích dat můžete získat obsah skriptu, který jste uložili do externího umístění, jako je úložiště objektů blob v Azure nebo veřejné úložiště GitHub.

Příklad:

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

Instalace balíčků pro modul plug-in R

Podle těchto podrobných pokynů nainstalujte balíčky, které nejsou součástí základní image modulu plug-in.

Požadavky

Vytvořte kontejner objektů blob pro hostování balíčků, nejlépe na stejném místě jako cluster. Předpokládejme například, https://artifactswestus.blob.core.windows.net/rže váš cluster je v oblasti USA – západ.
Upravte zásady popisku clusteru tak, aby umožňovaly přístup k danému umístění.
- Tato změna vyžaduje oprávnění AllDatabasesAdmin .
- Pokud například chcete povolit přístup k objektu blob umístěnému v https://artifactswestus.blob.core.windows.net/r, spusťte následující příkaz:
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/r/","CanCall": true } ]'
```

Instalace balíčků

Následující příklad výnisek předpokládá místní počítač R v prostředí Windows.

Ověřte, že používáte odpovídající verzi jazyka R – aktuální verze sandboxu R je 3.4.4:
```
> R.Version()["version.string"]

$version.string
[1] "R version 3.4.4 (2018-03-15)"
```
V případě potřeby si ho můžete stáhnout odsud.
Spuštění X64 RGui
Vytvořte novou prázdnou složku, která se naplní všemi příslušnými balíčky, které chcete nainstalovat. V tomto příkladu nainstalujeme balíček brglm2, takže vytvoříme C:\brglm2.
Přidejte nově vytvořenou cestu ke složce do cest lib:
```
> .libPaths("C://brglm2")
```

Ověřte, že nová složka je teď první cestou v cestě .libPaths():

> .libPaths()

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

Po dokončení této instalace se všechny balíčky, které nainstalujeme, přidají do této nové složky. Pojďme nainstalovat požadovaný balíček a jeho závislosti:
```
> install.packages("brglm2")
```
V případě, že se otázka "Chcete nainstalovat ze zdrojů balíčků, které potřebují kompilaci?", zobrazí se odpověď "Y".
Ověřte, že byly do složky C:\brglm2 přidány nové složky:
Vyberte všechny položky v této složce a zazipujte je do libs.zip (nezazipujte nadřazenou složku). Archivní struktura by měla vypadat takto:

libs.zip:
- brglm2 (složka)
- enrichwith (složka)
- numDeriv (složka)
Nahrání libs.zip do kontejneru objektů blob nastaveného výše
Zavolejte modul plug-in r .
- external_artifacts Zadejte parametr s názvem a odkazem na soubor ZIP (adresa URL objektu blob včetně tokenu SAS).
- Do vloženého kódu r naimportujte zipfile sandboxutils a volejte jeho install() metodu s názvem souboru ZIP.

Příklad

Nainstalujte balíček 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 ***'))

linka	Ver
0	1.8.2

Ujistěte se, že název archivu (první hodnota v páru balíčků) má příponu *.zip, aby se zabránilo kolizím při rozbalování složek, jejichž název je shodný s názvem archivu.

Sdílet prostřednictvím