R 플러그 인(미리 보기)

아티클
10/31/2024

적용 대상: ✅Microsoft Fabric ✅Azure Data Explorer✅Azure Monitor ✅Microsoft Sentinel

R 플러그 인은 R 스크립트를 사용하여 UDF(사용자 정의 함수)를 실행합니다.

스크립트는 테이블 형식 데이터를 입력으로 가져오고 테이블 형식 출력을 생성합니다. 플러그 인의 런타임은 클러스터 노드의 샌드박스에서 호스트됩니다. 샌드박스는 격리되고 안전한 환경을 제공합니다.

구문

T | evaluate [hint.distribution = (singleper_node | )] r(output_schema, 스크립트 [, script_parameters] [, external_artifacts])

구문 규칙에 대해 자세히 알아봅니다.

매개 변수

이름	Type	필수	설명
output_schema	`string`	✔️	`type` R 코드에서 반환하는 테이블 형식 데이터의 출력 스키마를 정의하는 리터럴입니다. 형식은 ColumnName ColumnType[, ...]`)`입니다`typeof(`.`:` 예: `typeof(col1:string, col2:long)`. 입력 스키마를 확장하려면 다음 구문을 `typeof(*, col1:string, col2:long)`사용합니다.
스크립트	`string`	✔️	실행할 유효한 R 스크립트입니다.
script_parameters	`dynamic`		예약된 `kargs` 사전으로 R 스크립트에 전달할 이름 및 값 쌍의 속성 모음입니다. 자세한 내용은 예약된 R 변수를 참조 하세요.
`hint.distribution`	`string`		여러 클러스터 노드에 분산될 플러그 인의 실행에 대한 힌트입니다. 기본값은 `single`입니다. `single` 는 스크립트의 단일 인스턴스가 전체 쿼리 데이터를 통해 실행된다는 것을 의미합니다. `per_node` 는 R 블록이 배포되기 전에 쿼리를 배포하는 경우 스크립트 인스턴스가 포함된 데이터를 통해 각 노드에서 실행된다는 것을 의미합니다.
external_artifacts	`dynamic`		클라우드 스토리지에서 액세스할 수 있는 아티팩트용 이름 및 URL 쌍의 속성 모음입니다. 스크립트를 런타임에 사용할 수 있도록 설정할 수 있습니다. 이 속성 모음에서 참조되는 URL은 클러스터의 설명선 정책 및 공개적으로 사용 가능한 위치에 포함되거나 스토리지 연결 문자열 설명된 대로 필요한 자격 증명을 포함해야 합니다. 아티팩트를 로컬 임시 디렉터리 `.\Temp`에서 스크립트에서 사용할 수 있습니다. 속성 모음에 제공된 이름은 로컬 파일 이름으로 사용됩니다. 예제를 참조하세요. 자세한 내용은 R 플러그 인에 대한 패키지 설치를 참조하세요.

예약된 R 변수

다음 변수는 Kusto 쿼리 언어 R 코드 간의 상호 작용을 위해 예약되어 있습니다.

df: R 데이터 프레임으로 입력 테이블 형식 데이터(위의 값 T )입니다.
kargs: R 사전으로 script_parameters 인수의 값입니다.
result: R 스크립트에서 만든 R DataFrame입니다. 이 값은 플러그 인 뒤에 있는 Kusto 쿼리 연산자에게 전송되는 테이블 형식 데이터가 됩니다.

플러그 인 사용

플러그 인은 기본값으로 사용 중지됩니다.
클러스터의 구성 탭에서 Azure Portal에서 플러그 인을 사용하거나 사용하지 않도록 설정합니다. 자세한 내용은 Azure Data Explorer 클러스터에서 언어 확장 관리(미리 보기)를 참조 하세요.

R 샌드박스 이미지

R 샌드박스 이미지는 Windows용 R 3.4.4를 기반으로 하며 Anaconda의 R Essentials 번들의 패키지를 포함합니다.

예제

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 Storage 또는 공용 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 플러그 인용 패키지 설치

다음 단계별 지침에 따라 플러그 인의 기본 이미지에 포함되지 않은 패키지를 설치합니다.

필수 조건

클러스터와 동일한 위치에서 패키지를 호스트하는 Blob 컨테이너를 만듭니다. 예를 들어 https://artifactswestus.blob.core.windows.net/r클러스터가 미국 서부에 있다고 가정합니다.
해당 위치에 대한 액세스를 허용하도록 클러스터의 설명선 정책을 변경합니다.
- 이 변경에는 AllDatabasesAdmin 권한이 필요합니다.
- 예를 들어, Blob https://artifactswestus.blob.core.windows.net/r에 대한 액세스를 사용하도록 설정하려면 다음 명령을 실행합니다.
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/r/","CanCall": true } ]'
```

패키지 설치

아래 예제에서는 Windows 환경에서 로컬 R 머신을 가정합니다.

적절한 R 버전을 사용하고 있는지 확인합니다. 현재 R 샌드박스 버전은 3.4.4입니다.
```
> R.Version()["version.string"]

$version.string
[1] "R version 3.4.4 (2018-03-15)"
```
필요한 경우 여기에서 다운로드할 수 있습니다.
x64 RGui 시작
설치하려는 모든 관련 패키지로 채울 새 빈 폴더를 만듭니다. 이 예제에서는 brglm2 패키지를 설치하므로 "C:\brglm2"를 만듭니다.
새로 만든 폴더 경로를 lib 경로에 추가합니다.
```
> .libPaths("C://brglm2")
```
이제 새 폴더가 .libPaths()의 첫 번째 경로인지 확인합니다.
```
> .libPaths()

[1] "C:/brglm2"    "C:/Program Files/R/R-3.4.4/library"
```
이 설정이 완료되면 설치하는 모든 패키지가 이 새 폴더에 추가됩니다. 요청된 패키지 및 해당 종속성을 설치해 보겠습니다.
```
> install.packages("brglm2")
```
"소스에서 컴파일이 필요한 패키지를 설치하시겠습니까?"라는 질문이 나타나면 "Y"라고 대답합니다.
새 폴더가 "C:\brglm2"에 추가되었는지 확인합니다.
해당 폴더의 모든 항목을 선택하고 압축하여 libs.zip(부모 폴더를 압축하지 마세요). 다음과 같은 보관 구조를 가져와야 합니다.

libs.zip:
- brglm2(폴더)
- enrichwith(폴더)
- numDeriv(폴더)
위에서 설정한 Blob 컨테이너에 libs.zip 업로드
플러그 인을 r 호출합니다.
- external_artifacts 이름 및 ZIP 파일에 대한 참조의 속성 모음을 사용하여 매개 변수를 지정합니다(SAS 토큰을 포함한 Blob의 URL).
- 인라인 r 코드에서 ZIP 파일의 이름으로 해당 install() 메서드를 sandboxutils 가져오 zipfile 고 호출합니다.

예시

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 접미사가 있는지 확인합니다.

다음을 통해 공유