R プラグイン (プレビュー)

適用対象: ✅Microsoft Fabric✅Azure データ エクスプローラー✅Azure Monitor✅Microsoft Sentinel

R プラグインは、R スクリプトを使用してユーザー定義関数 (UDF) を実行します。

このスクリプトは、表形式のデータを入力として取得し、表形式の出力を生成します。 プラグインのランタイムはクラスタのノード上のサンドボックスでホストされます。 サンドボックスは、分離された安全な環境を提供します。

構文

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

構文規則について詳しく知る。

パラメーター

件名	タイプ	Required	説明
output_schema	string	✔️	R コードによって返される表形式データの出力スキーマを定義する type リテラル。 形式は typeof(ColumnName: ColumnType[, ...])です。例: typeof(col1:string, col2:long)。 入力スキーマを拡張するには、typeof(*, col1:string, col2:long) という構文を使用します。
script	string	✔️	実行する有効な R スクリプト。
script_parameters	dynamic		予約された kargs ディクショナリとして R スクリプトに渡される名前と値のペアのプロパティ バッグ。 詳しくは、「予約済み R 変数」を参照してください。
hint.distribution	string		プラグインの実行を複数のクラスター ノードに分散するためのヒント。 既定値は single です。 single は、スクリプトの 1 つのインスタンスがクエリ データ全体に対して実行されることを意味します。 per_node は、R ブロックが分散される前のクエリの場合、スクリプトのインスタンスは、含まれているデータを介して各ノードで実行されることを意味します。
external_artifacts	dynamic		クラウド ストレージからアクセスできる成果物の名前と URL のペアのプロパティ バッグ。 実行時にスクリプトで使用できるように設定できます。 このプロパティ バッグで参照される URL は、クラスターの callout ポリシーパブリックに利用可能な場所に含めるか、torage 接続文字列で説明されているように、必要な資格情報を含める必要があります。 成果物は、スクリプトがローカルの一時ディレクトリ (.\Temp) から使用できます。 プロパティ バッグに指定された名前は、ローカル ファイル名として使用されます。 「例」を参照してください。 詳細については、「R プラグインのパッケージをインストールする」を参照してください。

予約済み R 変数

次の変数は、Kusto クエリ言語と R コード間のやり取りのために予約されています。

• df: R DataFrame としての入力表形式データ (上記の T の値)。
• kargs: 引数 script_parameters の値を R 辞書として指定します。
• result: R スクリプトで作成された R DataFrame。 値は、プラグインに従う任意の Kusto クエリ演算子に送信される表形式のデータになります。

プラグインの有効化

• プラグインは既定では無効です。
• クラスターの [構成] タブで、Azure portal のプラグインを有効または無効にします。 詳細については、「 Azure Data Explorer クラスターでの言語拡張機能の管理 (プレビュー)」を参照してください。

R サンドボックス イメージ

• R Sandbox イメージは R 3.4.4 for Windows に基き、Anaconda の R Essentials bundle からのパッケージを含んでいます。

例

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 

パフォーマンスに関するヒント

• プラグインの入力データセットを、必要な最小量 (列/行) に減らします。

• 可能な場合は、Kusto 照会言語を使用してソース データセットのフィルターを使用します。

• ソース列のサブセットに対して計算を行うには、プラグインを呼び出す前に、その列だけをプロジェクトに含めます。

• スクリプト内のロジックが配布可能な場合は、hint.distribution = per_nodeを使用します。

• パーティション演算子を使用して入力データをパーティション分割することもできます。

• 可能な場合は常に Kusto クエリ言語を使用して、R スクリプトのロジックを実装します。

  次に例を示します。

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

使用上のヒント

• Kusto 文字列の区切り記号と R 文字列の区切り記号が競合しないようにするには、次のようにします。

  • Kusto クエリの Kusto 文字列リテラルには単一引用符 ( ' ) を使用します。
  • R スクリプトで R 文字列リテラルに二重引用符文字 ( " ) を使用します。

• 外部データ演算子を使用して、Azure BLOB ストレージ やパブリック GitHub リポジトリなどの外部の場所に格納したスクリプトの内容を取得します。

  次に例を示します。

  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 
  

R プラグインのパッケージをインストールする

プラグインの基本イメージに含まれていないパッケージをインストールするには、次の手順に従います。

前提条件

1. パッケージをホストする BLOB コンテナーを作成します。できれば、クラスターと同じ場所に作成します。 たとえば https://artifactswestus.blob.core.windows.net/r では、クラスターが米国西部にあると想定されています。

2. クラスターのコールアウト ポリシーを変更して、その場所へのアクセスを許可します。

   • この変更を行うには、AllDatabasesAdmin アクセス許可が必要です。

   • たとえば、https://artifactswestus.blob.core.windows.net/r にある BLOB にアクセスできるようにするには、次のコマンドを実行します。

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

パッケージをインストールする

下の例のスニペットは、Windows 環境でのローカル R マシンを想定しています。

1. 適切な R バージョンを使用していることを確認します。現行の R サンドボックス バージョンは 3.4.4 です。

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

   必要に応じて、こちらからダウンロードできます。

2. x64 RGui を起動します

3. インストールするすべての関連パッケージが取り込まれる新しい空のフォルダーを作成します。 この例では brglm2 パッケージをインストールするため、"C:\brglm2" を作成します。

4. 新しく作成したフォルダー パスをライブラリ パスに追加します。

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

5. 新しいフォルダーが .libPaths() の最初のパスになっていることを確認します。

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

6. この設定が完了すると、インストールするすべてのパッケージがこの新しいフォルダーに追加されます。 要求パッケージとその依存関係をインストールしてみましょう。

   > install.packages("brglm2")
   

   "Do you want to install from sources the packages which need compilation? (ソースからコンパイルが必要なパッケージをインストールしますか)" という質問が表示された場合は、"Y" で答えます。

7. 新しいフォルダーが "C:\brglm2" に追加されたことを確認します。

   

8. そのフォルダー内のすべての項目を選択し、libs.zip などに圧縮します (親フォルダーを圧縮しないでください)。 次のようなアーカイブ構造になっている必要があります。

   libs.zip:

   • brglm2 (フォルダー)
   • enrichwith (フォルダー)
   • numDeriv (フォルダー)

9. 上記で設定した BLOB コンテナーに libs.zip をアップロードします

10. r プラグインを呼び出します。

    • 名前のプロパティ バッグと ZIP ファイルへの参照 (SAS トークンを含む BLOB の URL) を使用して、 external_artifacts パラメーターを指定します。
    • インライン r コードで、sandboxutilsからzipfileをインポートし、ZIP ファイルの名前でそのinstall() メソッドを呼び出します。

例

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

アーカイブ名 (パック ペアの最初の値) に *.zip サフィックスが付いていることを確認し、アーカイブ名と同じ名前のフォルダーを解凍する際の競合を防ぎます。

---