Plug-in R (anteprima)

Articolo
10/31/2024

Si applica a: ✅Microsoft Fabric ✅Azure Esplora dati ✅ Azure Monitor✅Microsoft Sentinel

Il plug-in R esegue una funzione definita dall'utente usando uno script R.

Lo script ottiene i dati tabulari come input e produce output tabulare. Il runtime del plug-in è ospitato in una sandbox nei nodi del cluster. La sandbox fornisce un ambiente isolato e sicuro.

Sintassi

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

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome	Digita	Obbligatorio	Descrizione
output_schema	`string`	✔️	Valore `type` letterale che definisce lo schema di output dei dati tabulari, restituito dal codice R. Il formato è ColumnName `typeof(:`ColumnType[, ...].`)` Ad esempio: `typeof(col1:string, col2:long)`. Per estendere lo schema di input, usare la sintassi seguente: `typeof(*, col1:string, col2:long)`.
script	`string`	✔️	Script R valido da eseguire.
script_parameters	`dynamic`		Contenitore di proprietà di coppie nome e valore da passare allo script R come dizionario riservato `kargs` . Per altre informazioni, vedere Variabili R riservate.
`hint.distribution`	`string`		Hint per l'esecuzione del plug-in da distribuire tra più nodi del cluster. Il valore predefinito è `single`. `single` significa che una singola istanza dello script verrà eseguita su tutti i dati della query. `per_node` significa che se la query prima della distribuzione del blocco R, un'istanza dello script verrà eseguita in ogni nodo sui dati contenuti.
external_artifacts	`dynamic`		Contenitore di proprietà di coppie nome e URL per gli artefatti accessibili dall'archiviazione cloud. Possono essere resi disponibili per lo script da usare in fase di esecuzione. Gli URL a cui si fa riferimento in questo contenitore di proprietà devono essere inclusi nei criteri di callout del cluster e in una posizione disponibile pubblicamente oppure contengono le credenziali necessarie, come illustrato nelle stringa di connessione di archiviazione. Gli artefatti vengono resi disponibili per l'utilizzo dello script da una directory temporanea locale, `.\Temp`. I nomi specificati nel contenitore delle proprietà vengono usati come nomi di file locali. Vedere Esempio. Per altre informazioni, vedere Installare i pacchetti per il plug-in R.

Variabili R riservate

Le variabili seguenti sono riservate per l'interazione tra Linguaggio di query Kusto e il codice R:

df: dati tabulari di input (i valori precedenti T ), come dataframe R.
kargs: valore dell'argomento script_parameters , come dizionario R.
result: un dataframe R creato dallo script R. Il valore diventa i dati tabulari che vengono inviati a qualsiasi operatore di query Kusto che segue il plug-in.

Abilitare il plug-in

Il plug-in è disabilitato di default.
Abilitare o disabilitare il plug-in nella portale di Azure nella scheda Configurazione del cluster. Per altre informazioni, vedere Gestire le estensioni del linguaggio nel cluster di Azure Esplora dati (anteprima)

Immagine sandbox R

L'immagine sandbox R si basa su R 3.4.4 per Windows e include pacchetti del bundle R Essentials di Anaconda.

Esempi

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

Demo seno.

Suggerimenti per incrementare le prestazioni

Ridurre il set di dati di input del plug-in alla quantità minima richiesta (colonne/righe).
Usare i filtri nel set di dati di origine usando il Linguaggio di query Kusto, quando possibile.
Per eseguire un calcolo su un subset delle colonne di origine, proiettare solo le colonne prima di richiamare il plug-in.
Usare hint.distribution = per_node ogni volta che la logica nello script è distribuibile.
È anche possibile usare l'operatore partition per partizionare i dati di input et.

Quando possibile, usare il Linguaggio di query Kusto per implementare la logica dello script R.

Ad esempio:

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

Suggerimenti per l'uso

Per evitare conflitti tra delimitatori di stringa Kusto e delimitatori di stringa R:
- Usare i caratteri virgolette singole (') per i valori letterali stringa Kusto nelle query Kusto.
- Usare i caratteri virgolette doppie (") per i valori letterali stringa R negli script R.

Usare l'operatore dati esterno per ottenere il contenuto di uno script archiviato in una posizione esterna, ad esempio l'archiviazione BLOB di Azure o un repository GitHub pubblico.

Ad esempio:

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

Installare pacchetti per il plug-in R

Seguire queste istruzioni dettagliate per installare i pacchetti che non sono inclusi nell'immagine di base del plug-in.

Prerequisiti

Creare un contenitore BLOB per ospitare i pacchetti, preferibilmente nella stessa posizione del cluster. Ad esempio, https://artifactswestus.blob.core.windows.net/rsupponendo che il cluster si trova negli Stati Uniti occidentali.
Modificare i criteri di callout del cluster per consentire l'accesso a tale posizione.
- Questa modifica richiede autorizzazioni AllDatabasesAdmin .
- Ad esempio, per abilitare l'accesso a un BLOB che si trova in https://artifactswestus.blob.core.windows.net/r, eseguire il comando seguente:
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/r/","CanCall": true } ]'
```

Installare i pacchetti

Gli snips di esempio seguenti presuppongono un computer R locale nell'ambiente Windows.

Verificare di usare la versione R appropriata: la versione corrente di R Sandbox è la 3.4.4:
```
> R.Version()["version.string"]

$version.string
[1] "R version 3.4.4 (2018-03-15)"
```
Se necessario, è possibile scaricarlo da qui.
Avviare x64 RGui
Creare una nuova cartella vuota da popolare con tutti i pacchetti pertinenti da installare. In questo esempio viene installato il pacchetto brglm2, quindi si crea "C:\brglm2".
Aggiungere il percorso della cartella appena creato ai percorsi lib:
```
> .libPaths("C://brglm2")
```

Verificare che la nuova cartella sia ora il primo percorso in .libPaths():

> .libPaths()

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

Al termine dell'installazione, qualsiasi pacchetto installato verrà aggiunto a questa nuova cartella. Verrà ora installato il pacchetto richiesto e le relative dipendenze:
```
> install.packages("brglm2")
```
Nel caso in cui la domanda "Si vuole installare da origini i pacchetti che necessitano di compilazione?" viene visualizzata la risposta "Y".
Verificare che le nuove cartelle siano state aggiunte a "C:\brglm2":
Selezionare tutti gli elementi nella cartella e comprimerli, ad esempio libs.zip (non comprimere la cartella padre). Si otterrà una struttura di archivio simile alla seguente:

libs.zip:
- brglm2 (cartella)
- enrichwith (cartella)
- numDeriv (cartella)
Caricare libs.zip nel contenitore BLOB impostato in precedenza
Chiamare il plug-in r .
- Specificare il external_artifacts parametro con un contenitore di proprietà di nome e riferimento al file ZIP (URL del BLOB, incluso un token di firma di accesso condiviso).
- Nel codice r inline importare zipfile e sandboxutils chiamare il install() relativo metodo con il nome del file ZIP.

Esempio

Installare il pacchetto 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

Assicurarsi che il nome dell'archivio (primo valore nella coppia di pacchetti) abbia il suffisso *.zip per evitare conflitti durante l'decompressione delle cartelle il cui nome è identico al nome dell'archivio.

Condividi tramite