쿼리 V2 HTTP 응답

아티클
01/10/2024

HTTP 응답 상태 줄

요청이 성공하면 HTTP 응답 상태 코드는 입니다200 OK. HTTP 응답 본문은 아래에 설명된 대로 JSON 배열입니다.

요청이 실패하면 HTTP 응답 상태 코드가 또는 5xx 오류입니다4xx. 이유 구에는 실패에 대한 추가 정보가 포함됩니다. HTTP 응답 본문은 아래에 설명된 대로 JSON 개체입니다.

참고

요청은 의 상태 코드를 200 OK반환할 수 있지만 HTTP 응답 본문은 오류를 나타냅니다. 이는 HTTP 상태 줄이 이미 반환된 후 오류가 발생할 때 발생할 수 있습니다. 판독기는 이러한 조건에 대해 명시적으로 검사 것으로 예상됩니다.

HTTP 응답 헤더

요청의 성공/실패에 관계없이 두 개의 사용자 지정 HTTP 헤더가 응답에 포함됩니다.

x-ms-client-request-id: 서비스는 상관 관계를 위해 요청/응답 쌍을 식별하는 불투명 문자열을 반환합니다. 요청에 클라이언트 요청 ID가 포함되어 있으면 해당 값이 여기에 표시됩니다. 그렇지 않으면 일부 임의 문자열이 반환됩니다.
x-ms-activity-id: 서비스는 상관 관계를 위해 요청/응답 쌍을 고유하게 식별하는 불투명 문자열을 반환합니다. 와 달리 x-ms-client-request-id이 식별자는 요청의 정보에 영향을 받지 않으며 응답별로 고유합니다.

HTTP 응답 본문(요청 실패 시)

요청 실패 시 HTTP 응답 본문은 규칙에 따라 OneApiErrors 형식이 지정된 JSON 문서가 됩니다. 형식에 대한 설명은 OneApiErrors 여기 섹션 7.10.2를 참조 하세요. 다음은 이러한 오류에 대한 예입니다.

{
    "error": {
        "code": "General_BadRequest",
        "message": "Request is invalid and cannot be executed.",
        "@type": "Kusto.Data.Exceptions.KustoBadRequestException",
        "@message": "Request is invalid and cannot be processed: Semantic error: SEM0100: 'table' operator: Failed to resolve table expression named 'aaa'",
        "@context": {
            "timestamp": "2023-04-18T12:59:27.4855445Z",
            "serviceAlias": "HELP",
            "machineName": "KEngine000000",
            "processName": "Kusto.WinSvc.Svc",
            "processId": 12580,
            "threadId": 10260,
            "clientRequestId": "Kusto.Cli;b90f4260-4eac-4574-a27a-3f302db21404",
            "activityId": "9dcc4522-7b51-41db-a7ae-7c1bfe0696b2",
            "subActivityId": "d0f30c8c-e6c6-45b6-9275-73dd6b379ecf",
            "activityType": "DN.FE.ExecuteQuery",
            "parentActivityId": "6e3c8dab-0aaf-4df5-85b5-fc20b0b29a84",
            "activityStack": "(Activity stack: CRID=Kusto.Cli;b90f4260-4eac-4574-a27a-3f302db21404 ARID=9dcc4522-7b51-41db-a7ae-7c1bfe0696b2 > KD.Query.Client.ExecuteQueryAsKustoDataStream/8191428e-7139-4c5d-9da7-839a0f21c5b9 > P.WCF.Service.ExecuteQueryAsKustoDataStream..IInterNodeCommunicationQueryContract/6e3c8dab-0aaf-4df5-85b5-fc20b0b29a84 > DN.FE.ExecuteQuery/d0f30c8c-e6c6-45b6-9275-73dd6b379ecf)"
        },
        "@permanent": true,
        "@text": "aaa",
        "@database": "Samples",
        "@ClientRequestLogger": "",
        "innererror": {
            "code": "SEM0100",
            "message": "'table' operator: Failed to resolve table expression named 'aaa'",
            "@type": "Kusto.Data.Exceptions.SemanticException",
            "@message": "Semantic error: SEM0100: 'table' operator: Failed to resolve table expression named 'aaa'",
            "@context": {
                "timestamp": "2023-04-18T12:59:27.4855445Z",
                "serviceAlias": "HELP",
                "machineName": "KEngine000000",
                "processName": "Kusto.WinSvc.Svc",
                "processId": 12580,
                "threadId": 10260,
                "clientRequestId": "Kusto.Cli;b90f4260-4eac-4574-a27a-3f302db21404",
                "activityId": "9dcc4522-7b51-41db-a7ae-7c1bfe0696b2",
                "subActivityId": "d0f30c8c-e6c6-45b6-9275-73dd6b379ecf",
                "activityType": "DN.FE.ExecuteQuery",
                "parentActivityId": "6e3c8dab-0aaf-4df5-85b5-fc20b0b29a84",
                "activityStack": "(Activity stack: CRID=Kusto.Cli;b90f4260-4eac-4574-a27a-3f302db21404 ARID=9dcc4522-7b51-41db-a7ae-7c1bfe0696b2 > KD.Query.Client.ExecuteQueryAsKustoDataStream/8191428e-7139-4c5d-9da7-839a0f21c5b9 > P.WCF.Service.ExecuteQueryAsKustoDataStream..IInterNodeCommunicationQueryContract/6e3c8dab-0aaf-4df5-85b5-fc20b0b29a84 > DN.FE.ExecuteQuery/d0f30c8c-e6c6-45b6-9275-73dd6b379ecf)"
            },
            "@permanent": true,
            "@errorCode": "SEM0100",
            "@errorMessage": "'table' operator: Failed to resolve table expression named 'aaa'"
        }
    }
}

HTTP 응답 본문(요청 성공)

요청 성공에 따라 HTTP 응답 본문은 요청 결과를 인코딩하는 JSON 배열이 됩니다.

논리적으로 V2 응답은 여러 Tables를 포함하는 DataSet 개체를 설명합니다. 이러한 테이블은 요청에 의해 요청된 실제 데이터 또는 요청 실행에 대한 추가 정보(예: 요청에서 사용하는 리소스의 회계)를 나타낼 수 있습니다. 또한 실제 요청은 상태 반환되더라도 200 OK 실제로 실패할 수 있으며, 이 경우 응답에는 부분 응답 데이터와 오류 표시가 포함됩니다.

물리적으로 응답 본문의 JSON 배열은 JSON 개체의 목록이며, 각 개체를 프레임이라고 합니다. DataSet 개체는 DataSetHeader 및 DataSetCompletion의 두 프레임으로 인코딩됩니다. 첫 번째 프레임은 항상 첫 번째 프레임이고 두 번째 프레임은 항상 마지막 프레임입니다. "사이"에서 Table 개체를 설명하는 프레임을 찾을 수 있습니다.

Table 개체는 다음 두 가지 방법으로 인코딩할 수 있습니다.

단일 프레임: DataTable. 이것이 기본값입니다.
또는 4가지 종류의 프레임인 TableHeader (먼저 제공되며 테이블을 설명함), TableFragment (테이블의 데이터를 설명함), TableProgress (선택 사항이며 테이블의 데이터에서 얼마나 멀리 떨어져 있는지 예측) 및 TableCompletion (테이블의 마지막 프레임)의 "혼합"으로 사용할 수 있습니다.

두 번째 사례는 "프로그레시브 모드"라고 하며 클라이언트 요청 속성 results_progressive_enabled 이 로 설정된 true경우에만 표시됩니다. 이 경우 각 TableFragment 프레임은 추가 작업 또는 바꾸기 작업으로 테이블에 대한 이전의 모든 프레임에 의해 누적된 데이터에 대한 업데이트를 설명합니다. (예를 들어 쿼리의 "최상위 수준"에서 장기 실행 집계 계산이 수행될 때 후자가 사용되므로 초기 집계 결과가 나중에 보다 정확한 결과로 바뀝니다.)

DataSetHeader

프레임은 DataSetHeader 항상 데이터 세트의 첫 번째 프레임이며 정확히 한 번 나타납니다.

{
    "Version": string,
    "IsProgressive": Boolean
}

위치:

Version 는 프로토콜 버전입니다. 현재 버전은 v2.0입니다.

IsProgressive 는 이 데이터 세트에 점진적 프레임이 포함되어 있는지 여부를 나타내는 부울 플래그입니다. 프로그레시브 프레임은 다음 중 하나입니다.

프레임	Description
`TableHeader`	테이블에 대한 일반 정보를 포함합니다.
`TableFragment`	테이블의 사각형 데이터 분할된 데이터베이스를 포함합니다.
`TableProgress`	진행률(0-100)을 포함합니다.
`TableCompletion`	이 프레임이 마지막 프레임임을 나타냅니다.

위의 프레임은 테이블을 설명합니다. 플래그가 IsProgressive true로 설정되지 않으면 집합의 모든 테이블이 단일 프레임을 사용하여 직렬화됩니다.

DataTable: 클라이언트가 데이터 세트의 단일 테이블에 대해 필요한 모든 정보를 포함합니다.

TableHeader

true로 설정된 옵션으로 results_progressive_enabled 만들어진 쿼리에는 이 프레임이 포함될 수 있습니다. 이 표에 따라 클라이언트는 및 TableProgress 프레임의 TableFragment 인터리빙 시퀀스를 기대할 수 있습니다. 테이블의 마지막 프레임은 입니다 TableCompletion.

{
    "TableId": Number,
    "TableKind": string,
    "TableName": string,
    "Columns": Array,
}

위치:

TableId 는 테이블의 고유 ID입니다.
TableKind는 다음 중 하나입니다.
- PrimaryResult
- QueryCompletionInformation
- QueryTraceLog
- QueryPerfLog
- TableOfContents
- QueryProperties
- QueryPlan
- Unknown
TableName 는 테이블의 이름입니다.
Columns 는 테이블의 스키마를 설명하는 배열입니다.

{
    "ColumnName": string,
    "ColumnType": string,
}

지원되는 열 형식은 여기에 설명되어 있습니다.

TableFragment

프레임에는 TableFragment 테이블의 사각형 데이터 조각이 포함됩니다. 실제 데이터 외에도 이 프레임에는 조각으로 TableFragmentType 수행할 작업을 클라이언트에 알려주는 속성도 포함되어 있습니다. 기존 조각에 추가된 조각이거나 대체합니다.

{
    "TableId": Number,
    "FieldCount": Number,
    "TableFragmentType": string,
    "Rows": Array
}

위치:

TableId 는 테이블의 고유 ID입니다.
FieldCount 는 테이블의 열 수입니다.
TableFragmentType 는 클라이언트가 이 조각을 사용하여 수행해야 하는 작업을 설명합니다. TableFragmentType는 다음 중 하나입니다.
- DataAppend
- DataReplace
Rows 는 조각 데이터를 포함하는 2차원 배열입니다.

TableProgress

프레임은 TableProgress 위에서 설명한 프레임과 인터리브할 TableFragment 수 있습니다. 유일한 목적은 클라이언트에 쿼리 진행률을 알리는 것입니다.

{
    "TableId": Number,
    "TableProgress": Number,
}

위치:

TableId 는 테이블의 고유 ID입니다.
TableProgress 는 백분율(0-100)의 진행률입니다.

TableCompletion

프레임은 TableCompletion 테이블 전송의 끝을 표시합니다. 해당 테이블과 관련된 프레임은 더 이상 전송되지 않습니다.

{
    "TableId": Number,
    "RowCount": Number,
}

위치:

TableId 는 테이블의 고유 ID입니다.
RowCount 는 테이블의 총 행 수입니다.

DataTable

플래그가 false로 설정된 상태에서 EnableProgressiveQuery 발급된 쿼리에는 프레임(TableHeader, , TableFragmentTableProgress및 TableCompletion)이 포함되지 않습니다. 대신 데이터 세트의 각 테이블은 클라이언트에 필요한 모든 정보를 포함하는 프레임을 사용하여 DataTable 전송되어 테이블을 읽습니다.

{
    "TableId": Number,
    "TableKind": string,
    "TableName": string,
    "Columns": Array,
    "Rows": Array,
}

위치:

TableId 는 테이블의 고유 ID입니다.
TableKind는 다음 중 하나입니다.
- PrimaryResult
- QueryCompletionInformation
- QueryTraceLog
- QueryPerfLog
- QueryProperties
- QueryPlan
- Unknown
TableName 는 테이블의 이름입니다.
Columns 는 테이블의 스키마를 설명하는 배열이며 다음을 포함합니다.

{
    "ColumnName": string,
    "ColumnType": string,
}

Rows 는 테이블의 데이터를 포함하는 2차원 배열입니다.

응답에 있는 테이블의 의미

PrimaryResult- 쿼리의 기본 테이블 형식 결과입니다. 각 테이블 형식 식 문에 대해 문에서 생성된 결과를 나타내는 하나 이상의 테이블이 순서대로 생성됩니다. 일괄 처리 및 포크 연산자 때문에 이러한 테이블이 여러 개 있을 수 있습니다.
QueryCompletionInformation - 쿼리가 성공적으로 완료되었는지 여부 및 쿼리에서 사용한 리소스(v1 응답의 QueryStatus 테이블과 유사)와 같은 쿼리 자체 실행에 대한 추가 정보를 제공합니다.
QueryProperties - 클라이언트 시각화 지침(예: 렌더링 연산자의 정보를 반영하기 위해 내보내짐) 및 데이터베이스 커서 정보와 같은 추가 값을 제공합니다.
QueryTraceLog- 성능 추적 로그 정보(클라이언트 요청 속성에서 가 true로 설정된 경우 perftrace 반환됨).

DataSetCompletion

프레임은 DataSetCompletion 데이터 세트의 마지막 프레임입니다.

{
    "HasErrors": Boolean,
    "Cancelled": Boolean,
    "OneApiErrors": Array,
}

위치:

HasErrors 는 데이터 세트를 생성하는 동안 오류가 있는 경우 true입니다.
Cancelled 는 데이터 세트 생성을 초래한 요청이 완료되기 전에 취소된 경우 true입니다.
OneApiErrors 는 가 true인 경우에만 HasErrors 반환됩니다. 형식에 대한 설명은 OneApiErrors 여기 섹션 7.10.2를 참조 하세요.

다음을 통해 공유