R-Plug-In (Vorschau)

Gilt für: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Das R-Plug-In führt eine benutzerdefinierte Funktion (UDF) mit einem R-Skript aus.

Das Skript ruft tabellarische Daten als Eingabe ab und erzeugt tabellarische Ausgaben. Die Laufzeit des Plug-Ins wird in einem Sandkasten auf den Knoten des Clusters gehostet. Der Sandkasten stellt eine isolierte und sichere Umgebung bereit.

Syntax

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

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name	Type	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 die folgende Syntax, um das Eingabeschema zu erweitern: typeof(*, col1:string, col2:long)
Skript	string	✔️	Das gültige R-Skript, das ausgeführt werden soll.
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 auf die Ausführung des Plug-Ins, die über mehrere Clusterknoten verteilt werden sollen. Der Standardwert ist single. single bedeutet, dass eine einzelne Instanz des Skripts über die gesamten Abfragedaten ausgeführt wird. per_node bedeutet: Wenn die Abfrage vor der Verteilung des R-Blocks ausgeführt wird, wird eine Instanz des Skripts auf jedem Knoten über den darin enthaltenen Daten ausgeführt.
external_artifacts	dynamic		Ein Eigenschaftenbehälter mit Namen und URL-Paaren für Artefakte, auf die über den Cloudspeicher zugegriffen werden kann. Sie können für das Skript zur Laufzeit zur Verfügung gestellt werden. URLs, auf die in diesem Eigenschaftenbehälter verwiesen wird, müssen in die Popuprichtlinie des Clusters und an einem öffentlich verfügbaren Speicherort aufgenommen werden oder die erforderlichen Anmeldeinformationen enthalten, wie in Speicher-Verbindungszeichenfolge s 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 tabellarischen Eingabedaten (die Werte oben T ) als R DataFrame.
• kargs: Der Wert des arguments script_parameters 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 auf das Plug-In folgt.

Aktivieren des Plug-Ins

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

R-Sandkastenbild

• Das R-Sandkastenimage basiert auf R 3.4.4 für Windows und enthält Pakete aus dem R Essentials-Bündel 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 

Leistungstipps

• Verringern Sie das Eingabe-Dataset des Plug-Ins auf die erforderliche Mindestmenge (Spalten/Zeilen).

• Verwenden Sie nach Möglichkeit Filter für das Quelldatenset mithilfe des Kusto-Abfragesprache.

• Um eine Berechnung für eine Teilmenge der Quellspalten vorzunehmen, projizieren Sie nur diese Spalten, bevor Sie das Plug-In aufrufen.

• Verwenden Sie hint.distribution = per_node , wann immer die Logik in Ihrem Skript verteilt werden kann.

• Sie können auch den Partitionsoperator für die Partitionierung der Eingabedaten et verwenden.

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

  Zum 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 gespeichert haben, z. B. Azure Blob Storage oder ein öffentliches GitHub-Repository.

  Zum 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 diese Schritt-für-Schritt-Anleitungen zum Installieren von Paketen, die nicht im Basisimage des Plug-Ins enthalten sind.

Voraussetzungen

1. Erstellen Sie einen BLOB-Container, um die Pakete zu hosten, vorzugsweise an derselben Stelle wie Ihr Cluster. Angenommen, https://artifactswestus.blob.core.windows.net/rIhr Cluster befindet sich in West-USA.

2. Ändern Sie die Popuprichtlinie des Clusters, um den Zugriff auf diesen Standort zuzulassen.

   • Für diese Änderung sind AllDatabasesAdmin-Berechtigungen erforderlich.

   • Führen Sie beispielsweise den folgenden Befehl aus, um den Zugriff auf ein Blob zu aktivieren, in https://artifactswestus.blob.core.windows.net/rdem sich ein Blob befindet:

   .alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/r/","CanCall": true } ]'
   

Installieren von Paketen

Im folgenden Beispiel wird davon ausgegangen, dass der lokale R-Computer in der Windows-Umgebung ausgeführt wird.

1. Überprüfen Sie, ob Sie die entsprechende R-Version verwenden – die aktuelle R-Sandbox-Version lautet 3.4.4:

   > R.Version()["version.string"]
   
   $version.string
   [1] "R version 3.4.4 (2018-03-15)"
   

   Bei Bedarf können Sie es von hier herunterladen.

2. Starten der x64-RGui

3. Erstellen Sie einen neuen leeren Ordner, der mit allen relevanten Paketen aufgefüllt werden soll, die Sie installieren möchten. In diesem Beispiel wird das brglm2-Paket installiert, sodass "C:\brglm2" erstellt wird.

4. Fügen Sie den neu erstellten Ordnerpfad zu lib-Pfaden hinzu:

   > .libPaths("C://brglm2")
   

5. Überprüfen Sie, ob der neue Ordner jetzt der erste Pfad in .libPaths():

   > .libPaths()
   
   [1] "C:/brglm2"    "C:/Program Files/R/R-3.4.4/library"
   
   

6. Sobald dieses Setup abgeschlossen ist, werden alle von uns installierten Pakete diesem neuen Ordner hinzugefügt. Lassen Sie uns das angeforderte Paket und seine Abhängigkeiten installieren:

   > install.packages("brglm2")
   

   Falls die Frage "Möchten Sie aus Quellen installieren, die kompiliert werden müssen?", antwortet "Y".

7. Überprüfen Sie, ob neue Ordner zu "C:\brglm2" hinzugefügt wurden:

   

8. Wählen Sie alle Elemente in diesem Ordner aus, und zippen Sie sie in z. B. libs.zip (zippen Sie nicht den übergeordneten Ordner). Sie sollten eine Archivstruktur wie folgt abrufen:

   libs.zip:

   • brglm2 (Ordner)
   • anreichern (Ordner)
   • numDeriv (Ordner)

9. Hochladen libs.zip in den oben festgelegten BLOB-Container

10. Rufen Sie das r Plug-In auf.

    • Geben Sie den external_artifacts Parameter mit einem Eigenschaftenbehälter namens an, und verweisen Sie auf die ZIP-Datei (die URL des Blobs, einschließlich eines SAS-Tokens).
    • Importieren zipfile Sie in Ihrem Inline-R-Code die sandboxutils Methode mit dem Namen der ZIP-Datei, und rufen Sie sie install() auf.

Beispiel

Installieren Sie das brglm2-Paket:

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 zu verhindern, wenn Ordner, deren Name mit dem Archivnamen identisch ist, aufzuheben.

---