查詢/管理 HTTP 回憶

發行項
06/20/2023

回應狀態

HTTP 回應狀態行會遵循 HTTP 標準回應碼。例如，代碼 200 表示成功。

下列狀態碼目前正在使用中，但可能會傳回任何有效的 HTTP 程式碼。

程式碼	子代碼	描述
100	繼續	用戶端可以繼續傳送要求。
200	[確定]	要求已成功開始處理。
400	BadRequest	要求的格式錯誤，且 (永久) 失敗。
401	未經授權	用戶端必須先進行驗證。
403	禁止	用戶端要求遭到拒絕。
404	NotFound	要求所參考的實體不存在。
413	PayloadTooLarge	要求承載已超過限制。
429	TooManyRequests	要求已因節流而遭到拒絕。
504	逾時	要求已逾時。
520	ServiceError	服務在處理要求時發現錯誤。

注意

200 狀態碼表示已順利開始處理要求，而非要求已順利完成。在處理要求期間傳回 200 狀態碼之後所發生的失敗，稱為「部分查詢失敗」，當遇到這類錯誤時，系統會在回應資料流中插入特殊指標，以警告用戶端發生的情況。

回應標頭

系統將會傳回下列自訂標頭。

自訂標頭	描述
`x-ms-client-request-id`	在相同名稱的要求標頭中傳送的唯一要求識別碼，或某些唯一的識別碼。
`x-ms-activity-id`	要求的全域唯一相互關聯識別碼。是由服務所建立。

回應本文

如果狀態代碼為 200，回應本文是 JSON 檔，會將查詢或管理命令的結果編碼為矩形數據表序列。如需詳細資料，請參閱下文。

注意

資料表的順序是由 SDK 所反映。例如，使用 .NET Framework Kusto.Data 程式庫時，資料表的順序接著會成為 SDK 所傳回物件中 System.Data.IDataReader 的結果。

如果狀態碼指出發生了 4xx 或 5xx 錯誤 (而不是 401 錯誤)，則回應主體是 JSON 文件，會將失敗的詳細資料編碼。如需詳細資訊，請參閱 Microsoft REST API 指南。

注意

如果要求中未包含 Accept 標頭，則失敗的回應主體不一定是 JSON 文件。

一系列資料表的 JSON 編碼

一系列資料表的 JSON 編碼是具有下列名稱/值對的單一 JSON 屬性包。

名稱	值
資料表	Table 屬性包的陣列。

Table 屬性包具有下列名稱/值對。

名稱	值
TableName	可用來識別資料表的字串。
資料行	Column 屬性包的陣列。
資料列	Row 陣列的陣列。

Column 屬性包具有下列名稱/值對。

名稱	值
ColumnName	識別此資料行的字串。
DataType	提供資料行大約 .NET 類型的字串。
ColumnType	提供資料行純量資料類型的字串。

Row 陣列的順序與個別 Columns 陣列的順序相同。 Row 陣列也有一個元素，與相關資料行的資料列值一致。無法以 JSON 表示的純量資料類型 (例如 datetime 和 timespan) 會以 JSON 字串表示。

下列範例顯示此類物件的一種可能變化，其中包含名為 Table_0 的單一資料表，而該資料表具有類型 string的單一資料行 Text 和單一資料列。

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

另一個範例：

此螢幕快照顯示 JSON 檔案的樹視圖，其中包含 Table 物件的陣列。

回應中資料表的意義

在大部分情況下，管理命令會傳回具有單一數據表的結果，其中包含管理命令所產生的資訊。例如，.show databases 命令會傳回單一資料表，其中包含叢集內所有可存取資料庫的詳細資料。

查詢通常會傳回多個資料表。每個表格式運算式陳述式，都會依序產生一或多個資料表，以表示陳述式所產生的結果。

注意

因為有批次和 fork 運算子，可能會產生多個這類的資料表。

通常會產生三個資料表：

@ExtendedProperties 資料表提供了其他值，例如用戶端的視覺化指示 (轉譯運算子所提供的資訊)、查詢的有效資料庫指標相關資訊，或查詢的查詢結果快取有效使用方式相關資訊。

若為使用 v1 通訊協定傳送的查詢，資料表會有類型 string 的單一資料行，其值為 JSON 編碼的字串，例如：

值

{"Visualization":"piechart",...}

{"Cursor":"637239957206013576"}

若為使用 v2 通訊協定傳送的查詢，資料表會有三個資料行：(1) 稱為 TableId 的 integer 資料行，指出記錄適用於結果集內的哪個資料表；(2) 稱為 Key 的 string 資料行，指出記錄所提供的資訊類型 (可能的值：Visualization、ServerCache 和 Cursor)；(3) 稱為 Value 的 dynamic 資料行，提供由索引鍵決定的資訊。

TableId Key 值

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

1 視覺效果 {"Visualization":"piechart",...}

值
{"Visualization":"piechart",...}
{"Cursor":"637239957206013576"}

TableId	Key	值
1	ServerCache	{"OriginalStartedOn":"2021-06-11T07:48:34.6201025Z",...}
1	視覺效果	{"Visualization":"piechart",...}

QueryStatus 資料表，提供了執行查詢本身的其他相關資訊，例如查詢是否順利完成，以及查詢所耗用的資源有哪些。

此資料表的結構如下：

時間戳記	嚴重性	SeverityName	StatusCode	StatusDescription	Count	RequestId	ActivityId	SubActivityId	ClientActivityId
2020-05-02 06:09:12.7052077	4	Info	0	查詢已順利完成	1	...	...	...	...

小於或等於 2 的嚴重性值表示失敗。

TableOfContents 資料表會最後建立，並列出結果中的其他資料表。

此資料表的範例如下：

序數	種類	名稱	識別碼
0	QueryResult	PrimaryResult	db9520f9-0455-4cb5-b257-53068497605a
1	QueryProperties	@ExtendedProperties	908901f6-5319-4809-ae9e-009068c267c7
2	QueryStatus	QueryStatus	00000000-0000-0000-0000-000000000000

Share via