쿼리/관리 HTTP 응답

아티클
01/10/2024

응답 상태

HTTP 응답 상태 줄은 HTTP 표준 응답 코드를 따릅니다. 예를 들어 코드 200은 성공을 나타냅니다.

유효한 HTTP 코드가 반환될 수 있지만 다음 상태 코드는 현재 사용 중입니다.

코드	하위 코드	Description
100	계속	클라이언트는 요청을 계속 보낼 수 있습니다.
200	확인	요청이 성공적으로 처리를 시작했습니다.
400	BadRequest	요청이 잘못 구성되고 실패했습니다(영구적으로).
401	권한 없음	클라이언트는 먼저 인증해야 합니다.
403	사용할 수 없음	클라이언트 요청이 거부되었습니다.
404	NotFound	요청은 존재하지 않는 엔터티를 참조합니다.
413	PayloadTooLarge	요청 페이로드가 제한을 초과했습니다.
429	TooManyRequests	제한으로 인해 요청이 거부되었습니다.
504	제한 시간	요청 시간이 초과되었습니다.
520	ServiceError	서비스에서 요청을 처리하는 동안 오류가 발견되었습니다.

참고

200 상태 코드는 요청 처리가 성공적으로 시작되었으며 성공적으로 완료되지 않았다는 것을 보여줍니다. 200개의 상태 코드가 반환된 후 요청 처리 중에 발생한 실패를 "부분 쿼리 실패"라고 하며, 이 오류가 발생하면 클라이언트에 발생했음을 알리기 위해 특수 표시기가 응답 스트림에 삽입됩니다.

응답 헤더

다음 사용자 지정 헤더가 반환됩니다.

사용자 지정 헤더	Description
`x-ms-client-request-id`	동일한 이름의 요청 헤더 또는 일부 고유 식별자에 전송된 고유 요청 식별자입니다.
`x-ms-activity-id`	요청에 대한 전역적으로 고유한 상관 관계 식별자입니다. 서비스에서 만듭니다.

응답 본문

상태 코드가 200인 경우 응답 본문은 쿼리 또는 관리 명령의 결과를 직사각형 테이블 시퀀스로 인코딩하는 JSON 문서입니다. 자세한 내용은 다음을 참조하세요.

참고

테이블 시퀀스는 SDK에 의해 반영됩니다. 예를 들어 .NET Framework Kusto.Data 라이브러리를 사용하는 경우 테이블 시퀀스는 SDK에서 반환된 개체의 System.Data.IDataReader 결과가 됩니다.

상태 코드가 401 이외의 4xx 또는 5xx 오류를 나타내는 경우 응답 본문은 오류의 세부 정보를 인코딩하는 JSON 문서입니다. 자세한 내용은 Microsoft REST API 지침을 참조하세요.

참고

헤더가 Accept 요청에 포함되지 않은 경우 오류의 응답 본문이 반드시 JSON 문서가 아닌 것은 아닙니다.

테이블 시퀀스의 JSON 인코딩

테이블 시퀀스의 JSON 인코딩은 다음 이름/값 쌍이 있는 단일 JSON 속성 모음입니다.

Name	값
테이블	Table 속성 모음의 배열입니다.

Table 속성 모음에는 다음과 같은 이름/값 쌍이 있습니다.

Name	값
TableName	테이블을 식별하는 문자열입니다.
열	Column 속성 모음의 배열입니다.
행	행 배열의 배열입니다.

Column 속성 모음에는 다음과 같은 이름/값 쌍이 있습니다.

Name	값
ColumnName	열을 식별하는 문자열입니다.
DataType	열의 대략적인 .NET 형식을 제공하는 문자열입니다.
ColumnType	열의 스칼라 데이터 형식 을 제공하는 문자열입니다.

행 배열의 순서는 각 Columns 배열과 같습니다. Row 배열에는 관련 열의 행 값과 일치하는 요소가 하나 있습니다. 및 와 timespan같이 datetime JSON에서 나타낼 수 없는 스칼라 데이터 형식은 JSON 문자열로 표시됩니다.

다음 예제에서는 형식의 단일 열 Textstring과 단일 행이 있는 라는 Table_0 단일 테이블이 포함된 경우 이러한 개체를 사용할 수 있는 개체를 보여 줍니다.

{
    "Tables": [{
        "TableName": "Table_0",
        "Columns": [{
            "ColumnName": "Text",
            "DataType": "String",
            "ColumnType": "string"
        }],
        "Rows": [["Hello, World!"]]
}

다음은 또 다른 예제입니다.

Table 개체의 배열을 포함하는 JSON 파일의 트리 뷰를 보여 주는 스크린샷

응답에 있는 테이블의 의미

대부분의 경우 관리 명령은 관리 명령에서 생성된 정보를 포함하는 단일 테이블로 결과를 반환합니다. 예를 들어 .show databases 명령은 클러스터에 있는 모든 액세스 가능한 데이터베이스의 세부 정보가 포함된 단일 테이블을 반환합니다.

쿼리는 일반적으로 여러 테이블을 반환합니다. 각 테이블 형식 식 문에 대해 문에서 생성된 결과를 나타내는 하나 이상의 테이블이 순서대로 생성됩니다.

참고

일괄 처리 및 포크 연산자 때문에 이러한 테이블이 여러 개 있을 수 있습니다.

세 개의 테이블이 생성되는 경우가 많습니다.

@ExtendedProperties 클라이언트 시각화 지침(렌더링 연산자가 제공하는 정보), 쿼리의 유효 데이터베이스 커서에 대한 정보 또는 쿼리 결과 캐시의 효과적인 사용에 대한 정보와 같은 추가 값을 제공하는 테이블입니다.

v1 프로토콜을 사용하여 보낸 쿼리의 경우 테이블에는 다음과 같이 JSON으로 인코딩된 문자열인 형식 string의 단일 열이 있습니다.

값

{"시각화":"piechart",...}

{"커서":"637239957206013576"}

v2 프로토콜을 사용하여 보낸 쿼리의 경우 테이블에는 세 개의 열이 있습니다. (1) integer 레코드가 적용되는 결과 집합의 테이블을 나타내는 열입니다 TableId . (2) string 레코드에서 제공하는 정보의 종류를 나타내는 라는 Key 열(가능한 값: Visualization, ServerCache및 Cursor); (3) dynamic 키 결정 정보를 제공하는 라는 Value 열입니다.

TableId 키 값

1 ServerCache {"OriginalStartedOn":"2021-06-11T07:48:34.6201025Z",...}

1 시각화 {"시각화":"piechart",...}

값
{"시각화":"piechart",...}
{"커서":"637239957206013576"}

TableId	키	값
1	ServerCache	{"OriginalStartedOn":"2021-06-11T07:48:34.6201025Z",...}
1	시각화	{"시각화":"piechart",...}

쿼리가 성공적으로 완료되었는지 여부 및 쿼리에서 사용한 리소스와 같은 쿼리 자체의 실행에 대한 추가 정보를 제공하는 QueryStatus 테이블입니다.

이 표에는 다음과 같은 구조가 있습니다.

타임스탬프	심각도	SeverityName	StatusCode	StatusDescription	개수	RequestId	ActivityId	SubActivityId	ClientActivityId
2020-05-02 06:09:12.7052077	4	정보	0	쿼리가 성공적으로 완료됨	1	...	...	...	...

심각도 값이 2 이하이면 실패를 나타냅니다.

마지막으로 만들어지고 결과의 다른 테이블을 나열하는 TableOfContents 테이블입니다.

이 테이블의 예는 다음과 같습니다.

서수	종류	Name	Id
0	QueryResult	PrimaryResult	db9520f9-0455-4cb5-b257-53068497605a
1	QueryProperties	@ExtendedProperties	908901f6-5319-4809-ae9e-009068c267c7
2	QueryStatus	QueryStatus	00000000-0000-0000-0000-000000000000