Wtyczka języka R (wersja zapoznawcza)

Dotyczy: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Wtyczka języka R uruchamia funkcję zdefiniowaną przez użytkownika (UDF) przy użyciu skryptu języka R.

Skrypt pobiera dane tabelaryczne jako dane wejściowe i generuje dane wyjściowe tabelaryczne. Środowisko uruchomieniowe wtyczki jest hostowane w piaskownicy w węzłach klastra. Piaskownica zapewnia izolowane i bezpieczne środowisko.

Składnia

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

Dowiedz się więcej na temat konwencji składni.

Parametry

Nazwisko	Type	Wymagania	opis
output_schema	string	✔️	Literał type definiujący schemat wyjściowy danych tabelarycznych zwrócony przez kod języka R. Format to: typeof(ColumnName: ColumnType[, ...]). Na przykład: typeof(col1:string, col2:long). Aby rozszerzyć schemat wejściowy, użyj następującej składni: typeof(*, col1:string, col2:long).
skrypt	string	✔️	Prawidłowy skrypt języka R do wykonania.
script_parameters	dynamic		Torba właściwości par nazw i wartości, które mają zostać przekazane do skryptu języka R jako słownika zarezerwowanego kargs . Aby uzyskać więcej informacji, zobacz Zmienne zarezerwowane języka R.
hint.distribution	string		Wskazówka dotycząca wykonywania wtyczki do dystrybucji między wieloma węzłami klastra. Domyślna wartość to single. single oznacza, że pojedyncze wystąpienie skryptu zostanie uruchomione na wszystkich danych zapytania. per_node oznacza, że jeśli zapytanie przed dystrybucją bloku języka R, wystąpienie skryptu zostanie uruchomione w każdym węźle na danych, które zawiera.
external_artifacts	dynamic		Worek właściwości i pary adresów URL dla artefaktów, które są dostępne z magazynu w chmurze. Można je udostępnić skryptowi do użycia w czasie wykonywania. Adresy URL, do których odwołuje się ta torba właściwości, muszą być uwzględnione w zasadach objaśnień klastra i w publicznie dostępnej lokalizacji lub zawierają niezbędne poświadczenia, jak wyjaśniono w parametry połączenia magazynu. Artefakty są udostępniane dla skryptu do korzystania z lokalnego katalogu tymczasowego, .\Temp. Nazwy podane w torbie właściwości są używane jako lokalne nazwy plików. Zobacz przykład. Aby uzyskać więcej informacji, zobacz Instalowanie pakietów dla wtyczki języka R.

Zarezerwowane zmienne języka R

Następujące zmienne są zarezerwowane do interakcji między język zapytań Kusto a kodem języka R:

• df: dane tabelaryczne wejściowe (wartości T powyżej) jako ramka danych języka R.
• kargs: wartość argumentu script_parameters jako słownik języka R.
• result: ramka danych języka R utworzona przez skrypt języka R. Wartość staje się danymi tabelarycznymi, które są wysyłane do dowolnego operatora zapytania Kusto, który jest zgodny z wtyczką.

Włączanie wtyczki

• Wtyczka jest domyślnie wyłączona.
• Włącz lub wyłącz wtyczkę w witrynie Azure Portal na karcie Konfiguracja klastra. Aby uzyskać więcej informacji, zobacz Zarządzanie rozszerzeniami językowymi w klastrze usługi Azure Data Explorer (wersja zapoznawcza)

Obraz piaskownicy języka R

• Obraz piaskownicy języka R jest oparty na wersji R 3.4.4 dla systemu Windows i zawiera pakiety z pakietu R Essentials platformy Anaconda.

Przykłady

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 

Wskazówki dotyczące wydajności

• Zmniejsz wejściowy zestaw danych wtyczki do minimalnej wymaganej ilości (kolumny/wiersze).

• Użyj filtrów w źródłowym zestawie danych przy użyciu język zapytań Kusto, jeśli to możliwe.

• Aby wykonać obliczenie w podzestawie kolumn źródłowych, przed wywołaniem wtyczki projektuj tylko te kolumny.

• Używaj hint.distribution = per_node za każdym razem, gdy logika w skry skryscie jest dystrybuowana.

• Możesz również użyć operatora partycji do partycjonowania danych wejściowych et.

• Jeśli to możliwe, użyj język zapytań Kusto, aby zaimplementować logikę skryptu języka R.

  Na przykład:

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

Porady dotyczące użycia

• Aby uniknąć konfliktów między ogranicznikami ciągów Kusto i ogranicznikami ciągów języka R:

  • Użyj znaków pojedynczego cudzysłowu (') dla literałów ciągu Kusto w zapytaniach Kusto.
  • Użyj znaków podwójnego cudzysłowu (") dla literałów ciągu języka R w skryptach języka R.

• Użyj zewnętrznego operatora danych, aby uzyskać zawartość skryptu przechowywanego w lokalizacji zewnętrznej, takiej jak magazyn obiektów blob platformy Azure lub publiczne repozytorium GitHub.

  Na przykład:

  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 
  

Instalowanie pakietów dla wtyczki języka R

Postępuj zgodnie z instrukcjami krok po kroku, aby zainstalować pakiety, które nie są uwzględnione w obrazie podstawowym wtyczki.

Wymagania wstępne

1. Utwórz kontener obiektów blob do hostowania pakietów, najlepiej w tym samym miejscu co klaster. Na przykład , zakładając, https://artifactswestus.blob.core.windows.net/rże klaster znajduje się w regionie Zachodnie stany USA.

2. Zmień zasady objaśnienie klastra, aby zezwolić na dostęp do tej lokalizacji.

   • Ta zmiana wymaga uprawnień AllDatabasesAdmin .

   • Aby na przykład włączyć dostęp do obiektu blob znajdującego się w https://artifactswestus.blob.core.windows.net/rlokalizacji , uruchom następujące polecenie:

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

Instalowanie pakietów

W poniższym przykładzie przyjęto założenie, że lokalna maszyna R w środowisku systemu Windows.

1. Sprawdź, czy używasz odpowiedniej wersji języka R — bieżąca wersja piaskownicy języka R to 3.4.4:

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

   W razie potrzeby możesz pobrać go z tego miejsca.

2. Uruchamianie interfejsu RGui x64

3. Utwórz nowy pusty folder, który ma zostać wypełniony wszystkimi odpowiednimi pakietami, które chcesz zainstalować. W tym przykładzie instalujemy pakiet brglm2, więc tworzymy "C:\brglm2".

4. Dodaj nowo utworzoną ścieżkę folderu do ścieżek lib:

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

5. Sprawdź, czy nowy folder jest teraz pierwszą ścieżką w pliku .libPaths():

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

6. Po zakończeniu tej konfiguracji do tego nowego folderu zostaną dodane wszystkie zainstalowane pakiety. Zainstalujmy żądany pakiet i jego zależności:

   > install.packages("brglm2")
   

   Jeśli pojawi się pytanie "Czy chcesz zainstalować ze źródeł pakiety, które wymagają kompilacji?" pojawia się odpowiedź "Y".

7. Sprawdź, czy nowe foldery zostały dodane do folderu "C:\brglm2":

   

8. Zaznacz wszystkie elementy w tym folderze i spakuj je, np. libs.zip (nie spakuj folderu nadrzędnego). Struktura archiwum powinna wyglądać następująco:

   libs.zip:

   • brglm2 (folder)
   • enrichwith (folder)
   • numDeriv (folder)

9. Przekaż libs.zip do kontenera obiektów blob, który został ustawiony powyżej

10. Wywołaj wtyczkę r .

    • external_artifacts Określ parametr z nazwą właściwości i odwołaniem do pliku ZIP (adres URL obiektu blob, w tym token SAS).
    • W kodzie wbudowanym r zaimportuj zipfile sandboxutils metodę i wywołaj metodę install() z nazwą pliku ZIP.

Przykład

Zainstaluj pakiet 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

Upewnij się, że nazwa archiwum (pierwsza wartość w parze pakietów) ma sufiks *.zip, aby zapobiec kolizjom podczas rozpakowywania folderów, których nazwa jest identyczna z nazwą archiwum.

---