쿼리 매개 변수 선언 문

아티클
01/23/2024

Kusto로 전송된 쿼리에는 이름 또는 값 쌍 집합이 포함될 수 있습니다. 쌍을 쿼리 텍스트 자체와 함께 쿼리 매개 변수라고 합니다. 쿼리는 쿼리 매개 변수 선언 문에서 이름과 형식을 지정하여 하나 이상의 값을 참조할 수 있습니다.

쿼리 매개 변수에는 두 가지 기본 사용됩니다.

주입 공격에 대한 보호 메커니즘으로.
쿼리를 매개 변수화하는 방법입니다.

특히 Kusto로 보내는 쿼리에서 사용자 제공 입력을 결합하는 클라이언트 애플리케이션은 SQL 삽입 공격에 해당하는 Kusto로부터 보호하는 메커니즘을 사용해야 합니다.

쿼리 매개 변수 선언

쿼리 매개 변수, 쿼리 텍스트 또는 사용하는 함수를 참조하려면 먼저 사용하는 쿼리 매개 변수를 선언해야 합니다. 각 매개 변수에 대해 선언은 이름과 스칼라 형식을 제공합니다. 필요에 따라 매개 변수에 기본값이 있을 수도 있습니다. 기본값은 요청이 매개 변수에 대한 구체적인 값을 제공하지 않는 경우에 사용됩니다. 그런 다음 Kusto는 해당 형식에 대한 일반적인 구문 분석 규칙에 따라 쿼리 매개 변수의 값을 구문 분석합니다.

Syntax

declarequery_parameters(Name1:Type1 [=DefaultValue1] [,...] );

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

매개 변수

이름	형식	필수	Description
Name1	`string`	✔️	쿼리에 사용되는 쿼리 매개 변수의 이름입니다.
Type1	`string`	✔️	또는 `datetime`과 같은 `string` 해당 형식입니다. 사용자가 제공하는 값은 문자열로 인코딩됩니다. 적절한 구문 분석 메서드가 쿼리 매개 변수에 적용되어 강력한 형식의 값을 가져옵니다.
DefaultValue1	`string`		매개 변수의 기본값입니다. 이 값은 적절한 스칼라 형식의 리터럴이어야 합니다.

참고

사용자 정의 함수와 마찬가지로 형식 dynamic 의 쿼리 매개 변수에는 기본값이 있을 수 없습니다.
테이블 형식 문은 세미콜론으로 함께 연결/구분됩니다. 그렇지 않으면 동일한 쿼리의 일부로 간주되지 않습니다.

예제

쿼리 실행

declare query_parameters(maxInjured:long = 90);
StormEvents 
| where InjuriesDirect + InjuriesIndirect > maxInjured
| project EpisodeId, EventType, totalInjuries = InjuriesDirect + InjuriesIndirect

출력

EpisodeId	EventType	totalInjuries
12459	겨울 날씨	137
10477	과도한 열	200
10391	열	187
10217	과도한 열	422
10217	과도한 열	519

클라이언트 애플리케이션에서 쿼리 매개 변수 지정

쿼리 매개 변수의 이름과 값은 쿼리를 만드는 애플리케이션에서 값으로 string 제공됩니다. 이름이 반복되지 않습니다.

값의 해석은 쿼리 매개 변수 선언 문에 따라 수행됩니다. 모든 값은 쿼리 본문의 리터럴인 것처럼 구문 분석됩니다. 구문 분석은 쿼리 매개 변수 선언 문에 지정된 형식에 따라 수행됩니다.

REST API

쿼리 매개 변수는 클라이언트 애플리케이션에서 요청 본문의 JSON 개체 슬롯을 통해 properties 이라는 Parameters중첩된 속성 모음에 제공됩니다. 예를 들어 애플리케이션에서 사용자의 생일을 요청하도록 하여 일부 사용자의 나이를 계산하는 Kusto에 대한 REST API 호출 본문은 다음과 같습니다.

{
    "ns": null,
    "db": "myDB",
    "csl": "declare query_parameters(birthday:datetime); print strcat(\"Your age is: \", tostring(now() - birthday))",
    "properties": "{\"Options\":{},\"Parameters\":{\"birthday\":\"datetime(1970-05-11)\",\"courses\":\"dynamic(['Java', 'C++'])\"}}"
}

Kusto SDK

Kusto 클라이언트 라이브러리를 사용할 때 쿼리 매개 변수의 이름과 값을 제공하는 방법을 알아보려면 쿼리 매개 변수를 사용하여 사용자 입력 보호를 참조하세요.

Kusto.Explorer

서비스에 요청할 때 전송되는 쿼리 매개 변수를 설정하려면 쿼리 매개 변수 "렌치" 아이콘(ALT + P)을 사용합니다.

이 기능은 Azure Monitor에서 지원되지 않습니다.