R-Plug-In (Vorschau)

Artikel
01/23/2024

Das R-Plug-In führt eine benutzerdefinierte Funktion (UDF) mithilfe eines R-Skripts aus.

Das Skript ruft tabellarische Daten als Eingabe ab und erzeugt eine tabellarische Ausgabe. Die Runtime des Plug-Ins wird in einer Sandbox auf den Knoten des Clusters gehostet. Die Sandbox bietet eine isolierte und sichere Umgebung.

Syntax

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

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name	Typ	Erforderlich	BESCHREIBUNG
output_schema	`string`	✔️	Ein `type` Literal, das das Ausgabeschema der tabellarischen Daten definiert, die vom R-Code zurückgegeben werden. Das Format lautet: `typeof(`ColumnName`:`ColumnType[, ...]`)`. Beispiel: `typeof(col1:string, col2:long)`. Verwenden Sie zum Erweitern des Eingabeschemas die folgende Syntax: `typeof(*, col1:string, col2:long)`.
script	`string`	✔️	Das gültige auszuführende R-Skript.
script_parameters	`dynamic`		Ein Eigenschaftenbehälter mit Namen- und Wertpaaren, die als reserviertes `kargs` Wörterbuch an das R-Skript übergeben werden sollen. Weitere Informationen finden Sie unter Reservierte R-Variablen.
`hint.distribution`	`string`		Hinweis, dass die Ausführung des Plug-Ins auf mehrere Clusterknoten verteilt wird. Standardwert: `single`. `single`bedeutet, dass ein einzelner instance des Skripts die gesamten Abfragedaten überläuft. `per_node`bedeutet, dass, wenn die Abfrage vor dem R-Block verteilt wird, ein instance des Skripts auf jedem Knoten über die darin enthaltenen Daten ausgeführt wird.
external_artifacts	`dynamic`		Ein Eigenschaftenbehälter mit Namen- und URL-Paaren für Artefakte, auf die aus dem Cloudspeicher zugegriffen werden kann. Sie können für das Skript zur Verwendung zur Laufzeit zur Verfügung gestellt werden. URLs, auf die in diesem Eigenschaftenbehälter verwiesen wird, müssen in der Legendenrichtlinie des Clusters und an einem öffentlich verfügbaren Speicherort enthalten sein oder die erforderlichen Anmeldeinformationen enthalten, wie in Speicherverbindungszeichenfolgen erläutert. Die Artefakte werden für das Skript zur Nutzung aus einem lokalen temporären Verzeichnis zur Verfügung gestellt. `.\Temp` Die im Eigenschaftenbehälter angegebenen Namen werden als lokale Dateinamen verwendet. Siehe Beispiel. Weitere Informationen finden Sie unter Installieren von Paketen für das R-Plug-In.

Reservierte R-Variablen

Die folgenden Variablen sind für die Interaktion zwischen Kusto-Abfragesprache und dem R-Code reserviert:

df: Die Eingabe tabellarischer Daten (die oben genannten T Werte) als R-DataFrame.
kargs: Der Wert des script_parameters-Arguments als R-Wörterbuch.
result: Ein R-DataFrame, der vom R-Skript erstellt wurde. Der Wert wird zu den tabellarischen Daten, die an einen beliebigen Kusto-Abfrageoperator gesendet werden, der dem Plug-In folgt.

Aktivieren des Plug-Ins

Das Plug-In ist standardmäßig deaktiviert.
Aktivieren oder deaktivieren Sie das Plug-In im Azure-Portal auf der Registerkarte Konfiguration Ihres Clusters. Weitere Informationen finden Sie unter Verwalten von Spracherweiterungen in Ihrem Azure Data Explorer-Cluster (Vorschau)

R Sandbox-Image

Das R-Sandboximage basiert auf R 3.4.4 für Windows und enthält Pakete aus dem R Essentials-Paket von Anaconda.

Beispiele

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

Sinus-Demo.

Leistungstipps

Reduzieren Sie das Eingabedataset des Plug-Ins auf die erforderliche Mindestmenge (Spalten/Zeilen).
Verwenden Sie nach Möglichkeit Filter für das Quelldataset mithilfe der Kusto-Abfragesprache.
Um eine Berechnung für eine Teilmenge der Quellspalten durchzuführen, projizieren Sie nur diese Spalten, bevor Sie das Plug-In aufrufen.
Verwenden Sie hint.distribution = per_node immer dann, wenn die Logik in Ihrem Skript verteilbar ist.
Sie können auch den Partitionsoperator verwenden, um die Eingabedaten zu partitionieren et.

Verwenden Sie nach Möglichkeit die Kusto-Abfragesprache, um die Logik Ihres R-Skripts zu implementieren.

Beispiel:

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

Verwendungstipps

So vermeiden Sie Konflikte zwischen Kusto-Zeichenfolgentrennzeichen und R-Zeichenfolgentrennzeichen:
- Verwenden Sie einzelne Anführungszeichen (') für Kusto-Zeichenfolgenliterale in Kusto-Abfragen.
- Verwenden Sie doppelte Anführungszeichen (") für R-Zeichenfolgenliterale in R-Skripts.

Verwenden Sie den externen Datenoperator , um den Inhalt eines Skripts abzurufen, das Sie an einem externen Speicherort wie Azure Blob Storage oder einem öffentlichen GitHub-Repository gespeichert haben.

Beispiel:

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

Installieren von Paketen für das R-Plug-In

Befolgen Sie die folgenden schritt-für-Schritt-Anweisungen, um Pakete zu installieren, die nicht im Basisimage des Plug-Ins enthalten sind.

Voraussetzungen

Erstellen Sie einen Blobcontainer, um die Pakete zu hosten, vorzugsweise an derselben Stelle wie Ihr Cluster. Angenommen, https://artifactswestus.blob.core.windows.net/rIhr Cluster befindet sich in den USA, Westen.
Ändern Sie die Beschriftungsrichtlinie des Clusters, um den Zugriff auf diesen Speicherort zuzulassen.
- Für diese Änderung sind Die Berechtigungen "AllDatabasesAdmin " erforderlich.
- Führen Sie beispielsweise den folgenden Befehl aus, um den Zugriff auf ein Blob zu ermöglichen, das sich in https://artifactswestus.blob.core.windows.net/rbefindet:
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/r/","CanCall": true } ]'
```

Installieren von Paketen

In den folgenden Beispiel-Snips wird davon ausgegangen, dass der lokale R-Computer in der Windows-Umgebung vorhanden ist.

Vergewissern Sie sich, dass Sie die entsprechende R-Version verwenden – aktuelle R Sandbox-Version ist 3.4.4:
```
> R.Version()["version.string"]

$version.string
[1] "R version 3.4.4 (2018-03-15)"
```
Bei Bedarf können Sie es hier herunterladen.
Starten Sie die x64 RGui
Erstellen Sie einen neuen leeren Ordner, der mit allen relevanten Paketen gefüllt wird, die Sie installieren möchten. In diesem Beispiel installieren wir das brglm2-Paket und erstellen daher "C:\brglm2".
Fügen Sie den neu erstellten Ordnerpfad zu lib-Pfaden hinzu:
```
> .libPaths("C://brglm2")
```
Vergewissern Sie sich, dass der neue Ordner jetzt der erste Pfad in .libPaths() ist:
```
> .libPaths()

[1] "C:/brglm2"    "C:/Program Files/R/R-3.4.4/library"
```
Sobald dieses Setup abgeschlossen ist, wird jedes Paket, das wir installieren, diesem neuen Ordner hinzugefügt. Installieren Sie das angeforderte Paket und die zugehörigen Abhängigkeiten:
```
> install.packages("brglm2")
```
Wenn die Frage "Möchten Sie aus Quellen die Pakete installieren, die kompiliert werden müssen?" angezeigt wird, beantworten Sie "Y".
Vergewissern Sie sich, dass "C:\brglm2" neue Ordner hinzugefügt wurden:
Wählen Sie alle Elemente in diesem Ordner aus, und zippen Sie sie z. B. in libs.zip (nicht den übergeordneten Ordner zippen). Sie sollten eine Archivstruktur wie folgt erhalten:

libs.zip:
- brglm2 (Ordner)
- enrichwith (Ordner)
- numDeriv (Ordner)
Hochladen libs.zip in den oben festgelegten Blobcontainer
Rufen Sie das Plug-In auf r .
- Geben Sie den external_artifacts Parameter mit einem Eigenschaftenbehälter mit Namen und Verweis auf die ZIP-Datei (die URL des Blobs, einschließlich eines SAS-Tokens) an.
- Importieren zipfile Sie in Ihrem Inline-r-Code aus sandboxutils , und rufen Sie die zugehörige install() Methode mit dem Namen der ZIP-Datei auf.

Beispiel

Installieren Sie das Paket 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

Stellen Sie sicher, dass der Name des Archivs (erster Wert im Packpaar) das Suffix *.zip aufweist, um Kollisionen beim Entpacken von Ordnern zu verhindern, deren Name mit dem Archivnamen identisch ist.

Diese Funktion wird nicht unterstützt.