쿼리/관리 HTTP 요청

아티클
12/08/2023

동사 및 리소스 요청

작업	HTTP 동사	HTTP 리소스
쿼리	GET	`/v1/rest/query`
쿼리	POST	`/v1/rest/query`
쿼리 v2	GET	`/v2/rest/query`
쿼리 v2	POST	`/v2/rest/query`
관리	POST	`/v1/rest/mgmt`

예를 들어 관리 명령("관리")을 서비스 엔드포인트로 보내려면 다음 요청 줄을 사용합니다.

POST https://help.kusto.windows.net/v1/rest/mgmt HTTP/1.1

포함할 요청 헤더 및 본문은 아래를 참조하세요.

요청 헤더

다음 표에는 쿼리 및 관리 작업에 사용되는 일반적인 헤더가 포함되어 있습니다.

표준 헤더	Description	필수/선택
`Accept`	`application/json`	필수
`Accept-Encoding`	지원되는 인코딩은 및 입니다 `gzip` . `deflate`	선택 사항
`Authorization`	인증 참조	필수
`Connection`	사용하도록 설정하는 것이 좋습니다. `Keep-Alive`	선택 사항
`Content-Length`	알려진 경우 요청 본문 길이를 지정하는 것이 좋습니다.	선택 사항
`Content-Type`	로 `application/json` 설정 `charset=utf-8`	필수
`Expect`	를 로 설정할 수 있습니다. `100-Continue`	선택 사항
`Host`	요청이 전송된 정규화된 도메인 이름으로 설정합니다(예: `help.kusto.windows.net`).	필수

다음 표에는 쿼리 및 관리 작업에 사용되는 일반적인 사용자 지정 헤더가 포함되어 있습니다. 달리 명시되지 않는 한 이러한 헤더는 원격 분석 목적으로만 사용되며 기능에 영향을 주지 않습니다.

모든 헤더는 선택 사항입니다. 사용자 지정 헤더를 지정하는 x-ms-client-request-id 것이 좋습니다. 실행 중인 쿼리 취소와 같은 일부 시나리오에서는 요청을 식별하는 데 사용되므로 이 헤더가 필요합니다.

사용자 지정 헤더	Description
`x-ms-app`	요청을 만드는 애플리케이션의 (친숙한) 이름입니다.
`x-ms-user`	요청을 만드는 사용자의 (친숙한) 이름입니다.
`x-ms-user-id`	`x-ms-user`과 동일
`x-ms-client-request-id`	요청에 대한 고유 식별자
`x-ms-client-version`	요청을 만드는 클라이언트에 대한 (친숙한) 버전 식별자
`x-ms-readonly`	지정된 경우 요청이 읽기 전용 모드로 실행되도록 강제하여 오래 지속되는 변경을 방지합니다.

요청 매개 변수

요청에 다음 매개 변수를 전달할 수 있습니다. GET 또는 POST 사용 여부에 따라 요청에서 쿼리 매개 변수 또는 본문의 일부로 인코딩됩니다.

매개 변수	Description	필수/선택
`csl`	실행할 쿼리 또는 관리 명령의 텍스트	필수
`db`	쿼리 또는 관리 명령의 대상인 scope 데이터베이스의 이름	일부 관리 명령의 경우 선택 사항입니다. 다른 명령 및 모든 쿼리에 필요합니다.
`properties`	요청 처리 방법 및 결과를 수정하는 요청 속성을 제공합니다. 자세한 내용은 요청 속성을 참조하세요.	선택 사항

GET 쿼리 매개 변수

GET을 사용하는 경우 요청의 쿼리 매개 변수는 요청 매개 변수를 지정합니다.

본문

POST를 사용하는 경우 요청 본문은 요청 매개 변수의 값을 사용하여 UTF-8로 인코딩된 단일 JSON 문서입니다.

예제

이 예제에서는 쿼리에 대한 HTTP POST 요청을 보여줍니다.

POST https://help.kusto.windows.net/v2/rest/query HTTP/1.1

요청 헤더

Accept: application/json
Authorization: Bearer ...AzureActiveDirectoryAccessToken...
Accept-Encoding: deflate
Content-Type: application/json; charset=utf-8
Host: help.kusto.windows.net
x-ms-client-request-id: MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1
x-ms-user-id: EARTH\davidbg
x-ms-app: MyApp

요청 본문

{
  "db":"Samples",
  "csl":"print Test=\"Hello, World!\"",
  "properties":"{\"Options\":{\"queryconsistency\":\"strongconsistency\"},\"Parameters\":{},\"ClientRequestId\":\"MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1\"}"
}

이 예제에서는 curl을 사용하여 위의 쿼리를 보내는 요청을 만드는 방법을 보여 줍니다.

인증을 위한 토큰을 가져옵니다.

AAD_TENANT_NAME_OR_ID애플리케이션 인증을 설정한 후 , AAD_APPLICATION_ID및 AAD_APPLICATION_KEY 를 관련 값으로 Microsoft Entra

curl "https://login.microsoftonline.com/AAD_TENANT_NAME_OR_ID/oauth2/token" \
  -F "grant_type=client_credentials" \
  -F "resource=https://help.kusto.windows.net" \
  -F "client_id=AAD_APPLICATION_ID" \
  -F "client_secret=AAD_APPLICATION_KEY"

이 코드 조각은 전달자 토큰을 제공합니다.

{
  "token_type": "Bearer",
  "expires_in": "3599",
  "ext_expires_in":"3599", 
  "expires_on":"1578439805",
  "not_before":"1578435905",
  "resource":"https://help.kusto.windows.net",
  "access_token":"eyJ0...uXOQ"
}

쿼리 엔드포인트에 대한 요청에서 전달자 토큰을 사용합니다.

curl -d '{"db":"Samples","csl":"print Test=\"Hello, World!\"","properties":"{\"Options\":{\"queryconsistency\":\"strongconsistency\"}}"}"' \
-H "Accept: application/json" \
-H "Authorization: Bearer eyJ0...uXOQ" \
-H "Content-Type: application/json; charset=utf-8" \
-H "Host: help.kusto.windows.net" \
-H "x-ms-client-request-id: MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1" \
-H "x-ms-user-id: EARTH\davidbg" \
-H "x-ms-app: MyApp" \
-X POST https://help.kusto.windows.net/v2/rest/query

이 사양에 따라 응답을 읽습니다.

클라이언트 요청 속성 및 쿼리 매개 변수 설정

다음 예제 본문에서 필드의 csl 쿼리는 및 d라는 n 두 개의 매개 변수를 선언합니다. 이러한 쿼리 매개 변수의 값은 요청 본문의 Parameters 필드 아래에 properties 있는 필드 내에 지정됩니다. Options 필드는 클라이언트 요청 속성을 정의합니다.

참고

문자열이 아닌 매개 변수와 비-long 매개 변수는 문자열 형식으로 KQL 리터럴로 표현되어야 합니다.

{
    "db": "Samples",
    "csl": "declare query_parameters (n:long, d:dynamic); StormEvents | where State in (d) | top n by StartTime asc",
    "properties": {
        "Options": {
            "maxmemoryconsumptionperiterator": 68719476736,
            "max_memory_consumption_per_query_per_node": 68719476736,
            "servertimeout": "50m"
        },
        "Parameters": {
            "n": 10, "d": "dynamic([\"ATLANTIC SOUTH\"])"
        }
    }
}

자세한 내용은 쿼리 매개 변수를 참조하세요.

다음을 통해 공유

쿼리/관리 HTTP 요청

동사 및 리소스 요청

요청 헤더

요청 매개 변수

GET 쿼리 매개 변수

본문

예제

클라이언트 요청 속성 및 쿼리 매개 변수 설정

피드백

피드백

추가 리소스