Compartilhar via

Plug-in R (versão prévia)

  • Artigo

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

O plug-in R executa uma UDF (função definida pelo usuário) usando um script R.

O script obtém dados tabulares como entrada e produz saída tabular. O tempo de execução do plug-in é hospedado em uma sandbox nos nós do cluster. A sandbox fornece um ambiente isolado e seguro.

Sintaxe

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

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome Digitar Obrigatória Descrição
output_schema string ✔️ Um type literal que define o esquema de saída dos dados tabulares, retornados pelo código R. O formato é: typeof(ColumnName :ColumnType[, ...]). Por exemplo: typeof(col1:string, col2:long). Para estender o esquema de entrada, use a seguinte sintaxe: typeof(*, col1:string, col2:long).
script string ✔️ O script R válido a ser executado.
script_parameters dynamic Um recipiente de propriedades de pares de nome e valor a ser passado para o script R como o dicionário reservado kargs . Para obter mais informações, consulte Variáveis R reservadas.
hint.distribution string Dica para que a execução do plug-in seja distribuída em vários nós de cluster. O valor padrão é single. single significa que uma única instância do script será executada em todos os dados da consulta. per_node significa que, se a consulta antes do bloco R for distribuída, uma instância do script será executada em cada nó sobre os dados que ele contém.
external_artifacts dynamic Um recipiente de propriedades de pares de nome e URL para artefatos que podem ser acessados no armazenamento em nuvem. Eles podem ser disponibilizados para o script usar em tempo de execução. As URLs referenciadas nesse recipiente de propriedades devem ser incluídas na política de texto explicativo do cluster e em um local disponível publicamente ou conter as credenciais necessárias, conforme explicado em cadeias de conexão de armazenamento. Os artefatos são disponibilizados para o script consumir a partir de um diretório temporário local, .\Temp. Os nomes fornecidos no recipiente de propriedades são usados como os nomes de arquivo locais. Veja Exemplo. Para obter mais informações, consulte Instalar pacotes para o plug-in do R.

Variáveis R reservadas

As seguintes variáveis são reservadas para interação entre a Linguagem de Consulta Kusto e o código R:

  • df: os dados tabulares de entrada (os valores acima T ), como um DataFrame do R.
  • kargs: O valor do argumento script_parameters, como um dicionário R.
  • result: Um DataFrame do R criado pelo script do R. O valor se torna os dados tabulares que são enviados para qualquer operador de consulta Kusto que segue o plug-in.

Habilitar o plug-in

Imagem de área restrita do R

  • A imagem da área restrita do R é baseada no R 3.4.4 para Windows e inclui pacotes do pacote R Essentials do Anaconda.

Exemplos

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

Demonstração senológica.

Dicas de desempenho

  • Reduza o conjunto de dados de entrada do plug-in para a quantidade mínima necessária (colunas/linhas).

  • Use filtros no conjunto de dados de origem usando a Linguagem de Consulta Kusto, quando possível.

  • Para fazer um cálculo em um subconjunto das colunas de origem, projete apenas essas colunas antes de invocar o plug-in.

  • Use hint.distribution = per_node sempre que a lógica em seu script for distribuível.

  • Você também pode usar o operador de partição para particionar os dados de entrada et.

  • Sempre que possível, use a Linguagem de Consulta Kusto para implementar a lógica do script R.

    Por exemplo:

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

Dicas de uso

  • Para evitar conflitos entre delimitadores de cadeia de caracteres Kusto e delimitadores de cadeia de caracteres R:

    • Use caracteres de aspas simples (') para literais de cadeia de caracteres Kusto em consultas Kusto.
    • Use caracteres de aspas duplas (") para literais de cadeia de caracteres R em scripts R.

  • Use o operador de dados externos para obter o conteúdo de um script armazenado em um local externo, como o armazenamento de blobs do Azure ou um repositório público do GitHub.

    Por exemplo:

    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

Instalar pacotes para o plug-in do R

Siga estas instruções passo a passo para instalar pacotes que não estão incluídos na imagem base do plug-in.

Pré-requisitos

  1. Crie um contêiner de blob para hospedar os pacotes, preferencialmente no mesmo local que o cluster. Por exemplo, https://artifactswestus.blob.core.windows.net/rsupondo que o cluster esteja no Oeste dos EUA.

  2. Altere a política de texto explicativo do cluster para permitir o acesso a esse local.

    • Essa alteração requer permissões AllDatabasesAdmin .

    • Por exemplo, para habilitar o acesso a um blob localizado em https://artifactswestus.blob.core.windows.net/r, execute o seguinte comando:

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

Instalar Pacotes

Os recortes de exemplo abaixo pressupõem que o computador R local no ambiente Windows.

  1. Verifique se você está usando a versão R apropriada – a versão atual do R Sandbox é 3.4.4:

    > R.Version()["version.string"]

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

    Se necessário, você pode baixá-lo aqui.

  2. Inicie o RGui x64

  3. Crie uma nova pasta vazia para ser preenchida com todos os pacotes relevantes que você gostaria de instalar. Neste exemplo, instalamos o pacote brglm2, criando "C:\brglm2".

  4. Adicione o caminho da pasta recém-criado aos caminhos da lib:

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

  5. Verifique se a nova pasta agora é o primeiro caminho em .libPaths():

    > .libPaths()

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

  6. Uma vez feita essa configuração, qualquer pacote que instalarmos será adicionado a essa nova pasta. Vamos instalar o pacote solicitado e suas dependências:

    > install.packages("brglm2")

    Caso a pergunta "Deseja instalar a partir de fontes os pacotes que precisam de compilação?" apareça, responda "Y".

  7. Verifique se novas pastas foram adicionadas a "C:\brglm2":

    Captura de tela do conteúdo do diretório da biblioteca.

  8. Selecione todos os itens nessa pasta e compacte-os, por exemplo, libs.zip (não compacte a pasta pai). Você deve obter uma estrutura de arquivo como esta:

    libs.zip:

    • brglm2 (pasta)
    • enriquecer com (pasta)
    • numDeriv (pasta)

  9. Carregar libs.zip para o contêiner de blob definido acima

  10. Chame o r plug-in.

    • Especifique o external_artifacts parâmetro com um recipiente de propriedades de name e referência ao arquivo ZIP (a URL do blob, incluindo um token SAS).
    • No código r embutido, importe zipfile e sandboxutils chame seu install() método com o nome do arquivo ZIP.

Exemplo

Instale o pacote 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

Certifique-se de que o nome do arquivo (primeiro valor no par de pacotes) tenha o sufixo *.zip para evitar colisões ao descompactar pastas cujo nome é idêntico ao nome do arquivo.