查詢 V2 HTTP 回應

發行項
01/10/2024

HTTP 回應狀態行

如果要求成功，HTTP 回應狀態代碼為 200 OK。 HTTP 回應本文是 JSON 陣列，如下所示。

如果要求失敗，HTTP 回應狀態代碼為 4xx 或 5xx 錯誤。原因片語將包含有關失敗的其他資訊。 HTTP 回應本文是 JSON 物件，如下所述。

注意

要求可能會傳回的狀態代碼 200 OK，但 HTTP 回應本文會指出錯誤。當 HTTP 狀態行傳回之後引發錯誤時，可能會發生這種情況。讀取器預期會明確檢查這類條件。

HTTP 回應標頭

不論要求的成功/失敗為何，回應中都包含兩個自定義 HTTP 標頭：

x-ms-client-request-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。最優先的一律為第一個框架，而其次則一律為最後一個框架。在「之間」，可以找到描述資料表物件的框架。

資料表物件可以透過兩種方式編碼：

作為單一框架：DataTable。此為預設值。
或者，作為四種框架的「混合」：TableHeader (這會先出現，並描述資料表)、TableFragment (其描述資料表的資料)、TableProgress (其為選用，並且會在資料表的資料中提供我們在資料表資料中的位置估計)，以及 TableCompletion (其為資料表的最後一個框架)。

第二個案例稱為「漸進模式」，且只有在用戶端要求的屬性 results_progressive_enabled 設定為 true 時才會出現。在此情況下，每個 TableFragment 框架會描述資料表的所有先前這類框架所累積的資料的更新 (例如附加作業或取代作業)。 (使用後者時，例如，在查詢的「最上層」執行一些長時間執行的彙總計算時，將會在稍後以更精確的結果取代初始彙總結果。)

DataSetHeader

框架 DataSetHeader 一律是數據集中的第一個畫面，而且只會顯示一次。

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

其中：

Version 是通訊協定版本。目前版本為 v2.0。

IsProgressive 是布爾旗標，指出此數據集是否包含漸進式框架。漸進式框架是下列其中一項：

Frame	描述
`TableHeader`	包含關於資料表的一般資訊
`TableFragment`	包含資料表的矩形資料分區
`TableProgress`	包含進度，以百分比為單位 (0-100)
`TableCompletion`	指出此框架是最後一個框架

上述框架描述資料表。如果 IsProgressive 旗標未設定為 true，則會使用單一框架將集合中的每個資料表序列化：

DataTable：包含客戶端在數據集中單一數據表所需的所有資訊。

TableHeader

將 results_progressive_enabled 選項設為 true 所進行的查詢可能包含此框架。在此資料表之後，用戶端可以預期會有 TableFragment 和 TableProgress 框架交錯的順序。資料表的最後一個框架是 TableCompletion。

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

其中：

TableId 是資料表的唯一識別碼。
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 是資料表的唯一識別碼。
FieldCount 是資料表中的資料行數目。
TableFragmentType 描述用戶端應該對此片段執行的動作。 TableFragmentType 為下列其中一項：
- DataAppend
- DataReplace
Rows 是包含片段資料的二維陣列。

TableProgress

TableProgress 框架可以與上面所述的 TableFragment 框架交錯。其唯一目的是通知用戶端查詢的進度。

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

其中：

TableId 是資料表的唯一識別碼。
TableProgress 是進度，以百分比 (0--100) 為單位。

TableCompletion

TableCompletion 框架標示資料表傳輸的結尾。將不再傳送與該資料表相關的任何框架。

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

其中：

TableId 是資料表的唯一識別碼。
RowCount 資料表中的資料列總數。

DataTable

將 EnableProgressiveQuery 旗標設為 false 而發出的查詢，將不會包含任何框架 (TableHeader、TableFragment、TableProgress 和 TableCompletion)。相反地，系統會使用 DataTable 包含用戶端所需所有資訊的框架來傳輸數據集中的每個數據表，以讀取數據表。

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

其中：

TableId 是資料表的唯一識別碼。
TableKind 為下列其中一項：
- PrimaryResult
- QueryCompletionInformation
- QueryTraceLog
- QueryPerfLog
- QueryProperties
- QueryPlan
- Unknown
TableName 是資料表的名稱。
Columns 是描述資料表結構描述的陣列，並包含：

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

Rows 是包含資料表資料的二維陣列。

回應中資料表的意義

PrimaryResult - 查詢的主要表格式結果。針對每個表格式運算式陳述式，將依序產生一或多個資料表，以表示陳述式所產生的結果。因為有批次和 fork 運算子，可能會產生多個這類的資料表。
QueryCompletionInformation - 提供查詢本身執行的其他相關資訊，例如是否已順利完成，以及查詢所耗用的資源 (類似於 v1 回應) 中的 QueryStatus 資料表。
QueryProperties - 提供其他值，例如用戶端視覺效果指令 (發出，例如，反映轉譯運算子中的資訊) 和資料庫數據指標資訊。
QueryTraceLog - 效能追蹤記錄資訊 (用戶端要求中的 perftrace 設定為 true 時傳回)。

DataSetCompletion

框架 DataSetCompletion 是數據集的最後一個框架。

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

其中：

HasErrors 如果產生數據集時發生錯誤，則為 true。
Cancelled 如果導致產生數據集的要求在完成之前已取消，則為 true。
只有 HasErrors 為 true 才會傳回 OneApiErrors。如需 OneApiErrors 格式的描述，請參閱這裡的 7.10.2 一節。

共用方式為