다음을 통해 공유

쿼리/관리 HTTP 요청

  • 아티클

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

동사 및 리소스 요청

작업 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

포함할 내용을 알아보려면 요청 헤더 및 본문을 참조하세요.

요청 헤더

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

표준 헤더 설명 필수/선택
Accept 클라이언트가 받는 미디어 형식입니다. application/json로 설정합니다. Required
Accept-Encoding 지원되는 콘텐츠 인코딩입니다. 지원되는 인코딩은 다음과 deflate같습니다gzip. 선택 사항
Authorization 인증 자격 증명입니다. 자세한 내용은 인증을 참조하세요. Required
Connection 작업 후 연결이 계속 열려 있는지 여부입니다. 권장 사항은 .로 설정하는 Connection 것입니다 Keep-Alive. 선택 사항
Content-Length 요청 본문의 크기입니다. 알려진 경우 요청 본문 길이를 지정합니다. 선택 사항
Content-Type 요청 본문의 미디어 형식입니다. 로 application/json charset=utf-8설정합니다. Required
Expect 서버의 예상 응답입니다. 로 설정할 100-Continue수 있습니다. 선택 사항
Host 요청이 전송된 정규화된 도메인 이름입니다. 예들 들어 help.kusto.windows.net입니다. Required

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

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

Custom 헤더 설명
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 사용 여부에 따라 요청에서 쿼리 매개 변수 또는 본문의 일부로 인코딩됩니다.

매개 변수 설명 필수/선택
csl 실행할 쿼리 또는 관리 명령의 텍스트입니다. Required
db 쿼리 또는 관리 명령의 대상인 데이터베이스의 이름입니다. 일부 관리 명령의 경우 선택 사항입니다.
모든 쿼리 및 기타 모든 명령에 필요합니다.
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을 사용하여 이전 쿼리를 보내는 요청을 만드는 방법을 보여 줍니다.

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

    AAD_APPLICATION_IDAAD_APPLICATION_KEY Microsoft Entra 애플리케이션 인증을 설정한 후 관련 값으로 대체AAD_TENANT_NAME_OR_ID합니다.

    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"
}

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

    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

  3. 응답 상태 코드에 따라 응답을 읽습니다.

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

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

참고 항목

문자열이 아닌 매개 변수와 길이가 아닌 매개 변수는 문자열 형식의 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\"])"
        }
    }
}

자세한 내용은 지원되는 요청 속성을 참조 하세요.

데이터베이스 캐싱 정책 표시 보내기 명령

다음 예제에서는 데이터베이스 캐싱 정책을 표시하는 Samples 요청을 보냅니다.


{
    "db": "Samples",
    "csl": ".show database Samples policy caching",
    "properties": {
        "Options": {
            "maxmemoryconsumptionperiterator": 68719476736,
            "max_memory_consumption_per_query_per_node": 68719476736,
            "servertimeout": "50m"
        }
    }
}